跳转到内容

属性系统与同步 ​

属性同步在所属 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,不在本文保留另一套分期或完成记录。

基于 MIT 许可发布