属性系统与同步
属性同步在所属 Scene 的逻辑线程上管理实体值、变更历史和每个观察者的进度。cell 内的权威 Cell 持有模拟写权,worldServer 管理分配,baseServer 持有长期资料权威,database 执行存储请求。外部引擎机制仅作为参考。
执行摘要
已有 ChangeHistory、ViewerAttrState、DeltaBuilder、AttrSyncManager、FrameCodec、AttrSyncScheduler、域投影、slice 格及 Scene AOI 接线。客户端实际发送、业务成员数据注入和持久结算需要单独接线,不能把机制单测当成完整产品路径。
0. 当前实现边界
modules/game/attrsync 提供可复用原语。Scene 可收集输出帧,GameConnection 提供通道能力;完整 World → Gateway → 客户端状态交付仍需验收。契约有生成产物,不代表所有应用都已停止使用手写帧。
1. 基本规则
每份模拟状态只有一个写入者。网络输入和后台结果通过有界交接到所属逻辑边界。属性可见性、传输可靠性和持久性分别定义;发给客户端不等于已经保存。
2. 属性模型
2.1 生命周期分类
区分静态配置、持久状态、易失场景状态与派生计算。属性定义描述类型、默认值和策略;实体容器保存当前值。存储结构不由线上契约直接冻结。
2.2 类型与复合格
当前 attrsync 机制使用整数值及 slice 格。组合 ID 为 (slot << 16) | base;slot 0 表示长度格,数据格从 1 开始。必须先声明上限、设置长度,再访问有效格。收缩删除越界值、脏标记及待发的无效格。
2.3 权威与可见域
玩家持久写权与 Scene 模拟写权由当前 World 按职责管理,迁移时显式交接。可见域独立于数据权威:Public/World、Self、Team、Guild 等投影由域声明及宿主成员判定决定。
当前机制中 Public/World 可见,Self 依据观察者与实体标识判定,Team/Guild 依赖注入的 group gate;未提供成员判定时不可见。宿主必须正确映射玩家身份与实体身份,不能把默认值当成完整授权策略。
2.4 派生属性
公式及依赖调度必须有明确顺序。Lua 钩子在受控边界执行,设置写白名单、递归边界和预算;不能由异步结果修改已完成 tick 的判定。
3. 变更历史与增量
3.1 核心状态
ChangeHistory 保存有序变更,ViewerAttrState 保存观察者已知基线和 ACK 进度。每实体当前值、dirty 集与历史由 EntityAttrs 管理。
3.2 收集
DeltaBuilder 基于当前值、历史和观察者进度构造输出,按属性 ID 保持确定顺序。重复写入按机制规则合并。调度器可以先 peek 候选负载,决定预算后再提交收集副作用。
3.3 快照
首次可见、历史不足、增量超阈值或 ACK 降级时发送快照。快照包含全量当前可见值,不能仅设置 is_snapshot 标志而遗漏数据。快照和增量使用同一域裁剪规则。
3.4 合并
同属性保留最终值;slice 长度先于数据格应用,收缩后不能通过同批的旧格重新恢复越界状态。业务事件不能无条件套用属性最后写入覆盖语义。
4. 可见性
4.1 Scene AOI 接线
Scene 挂接 AttrSyncManager 后,实体创建/进入时注册属性;首次 Enter/Sync 建观察者状态并收集快照,Leave 回收观察者状态。同一可见范围内移动不应不断重复首见快照。
4.2 域投影
每观察者获得独立投影。AOI 决定能否看见实体,字段域决定能否看到其属性;二者都必须满足。成员、隐身、死亡等玩法规则由宿主提供,不能仅靠附近查询完成授权。
4.3 规则变化
队伍、公会或其他可见性条件变化时,宿主需要重建或刷新相关投影,覆盖权限收回后的旧客户端状态。现有 group gate 并不自动维护所有业务成员变化。
4.4 跨服
跨服复用 Scene 与现有同步机制。转移唯一权威、刷新路由和重建观察者基线后恢复同步;当前不依赖 Ghost;未来同 Space 多 Cell 需连续可见性、邻接投影与去重,保留此扩展边界。参见跨服场景设计。
5. 预算、优先级与节流
5.1 预算
AttrSyncScheduler 使用每观察者 token bucket。传输水位独立控制是否能入队;预算通过不代表网络一定可写。
5.2 优先级
现有调度考虑 importance、dirty 数量及饥饿保护。距离、实际可见性和具体玩法重要性需要真实宿主数据,不能把算法入口存在写成全部已经接入。
5.3 节流
按 min_interval 控制低频属性;即时属性走其声明规则。预算不足时保留可恢复状态,不因跳过本拍而丢掉最终权威值。
5.4 通道
movement、attributes、events、control 的规则见网络设计。属性差分不能随意使用易弃通道替代基线与 ACK 协议。
6. 实体生命周期
进入可见范围先发送可用基线,再应用增量;离开时清理观察者状态及客户端实体。销毁 Instance 时清理其 Scene 的实体、AOI 和输出;拒绝销毁后到达的旧输入与后台完成。
7. 编码与契约
7.1 当前编码
AttrDelta 和 FrameCodec 提供 varint/zigzag 编解码与边界校验。属性元数据、域声明与消息定义来自 XML/XSD 生成产物。.proto 是已有契约投影,不代表真实路径已采用 protobuf。
7.2 序号与恢复
使用序号、基线和 ACK 检测进度;ACK 超时通过真实快照降级。链路重连、业务会话恢复和权威迁移是不同事件,恢复后按实际基线决定补发或重建。
7.3 实体继承
生成器按实体定义展开继承,运行端消费扁平元数据。继承结构不应导致各 SDK 独立实现另一套属性协议。兼容窗口仍按SDK 契约验收。
8. 持久化
8.1 所有权
baseServer 持有玩家长期资料,worldServer 持有场景状态;两者不是同一份完整资料的并行写入副本。保存队列、journal 与实际存储交由 database。跨服保留原 Base 和数据库归属。
8.2 写入交接
AttrSyncManager::ChangeSink 把变更交给宿主,不直接链接数据层。Base 校验资料变更后向 database 提交,存储路径先记录 journal 再按策略更新档案。必须验证字段转换、保存失败、顺序和重放,不能只看 mark_dirty 就宣布奖励持久化成功。
8.3 结算
World 发出带稳定结算 ID 的请求,Base 校验后修改长期态并经 database 持久提交;既有 IRewardSink / AvatarRewardSink 可复用,但不能继续跨边界直接修改本地资料对象。业务必须补齐持久化映射、去重、重试与恢复确认。结算成功下行以约定的持久确认结果为准。
8.4 外部存储
当前业务保存仍是本地档案与 journal。SQL、Redis、列式分析存储等按具体部署需求触发,不将配置字段或库依赖算成已经接入。
9. 客户端预测
预测值与权威值分开保存;仅对明确允许的字段预测,权威应答到达后校正。移动预测、战斗判定和完整 SDK 状态恢复需要真实玩法与端侧验收,不能由服务端原语推导完成。
10. 线程与停机
10.1 tick 边界
在所属逻辑线程消费输入、推进模拟、处理钩子、收集同步输出。异步结果通过请求标识交接并重新校验目标、会话及权威代次,不参与已完成的判定。
10.2 关闭顺序
PlayerStore 停止受理、等待保存生产者退出、收集脏状态、排空 SaveQueue 并在期限内推进 journal,最后关闭存储。超时残留保留待重放。此机制不恢复活动 Instance,也不保证所有长期态字段已经进入保存载荷。
11. 验收
覆盖快照与增量一致性、域过滤、成员变化、slice 收缩、ACK 超时、预算不足、慢客户端和 Scene 销毁。端到端检查编码、Gateway 路由、socket 发送、客户端应用以及持久结算重试。
12. 当前工作
机制实现与完整业务接线分开跟踪。当前真实任务只维护在根目录 todo.md,不在本文保留另一套分期或完成记录。
