mtgodot-poc/audit/contracts/world.entity-spawn-state-sync.md

# world.entity_spawn_state_sync

## Scope

审计 Actor 的 Add、AdditionalInfo、Add2、Update、Move、Delete、主角色切换、VID 重用、可见性和实体节点/网络数据同步。目标不是比较函数名，而是确认 40250 的字段、前置条件、分支、调用顺序、资源副作用和清理行为在当前客户端中保持相同；Godot 的节点/信号只是平台适配，不能掩盖网络实体状态的缺失。

## Reference implementation and evidence

- `../40250/Server Client TMP4/ClientVS22/source/UserInterface/NetworkActorManager.cpp`
  - `AppendActor`, `UpdateActor`, `MoveActor`, `RemoveActor`, `SetMainActorVID`, `__AppendCharacterManagerActor`, `__RemoveCharacterManagerActor`, `__RemoveDynamicActors`。
  - Add 时保存完整 `SNetworkActorData`；创建失败时删除数据行；主角色使用立即删除，远端 Delete 使用 `DeleteInstanceByFade`。
  - `UpdateActor` 的副作用顺序为 armor、weapon、hair、guild、affect、move speed、attack speed、alignment、PK、state flags。
  - 同 VID 重新创建时，只有 mount 状态发生切换才保留旧实例位置；否则使用新 Actor 的当前坐标。
- `../40250/Server Client TMP4/ClientVS22/source/UserInterface/PythonNetworkStreamPhaseGameActor.cpp`
  - `RecvCharacterAppendPacket`：旧 Add 的两包链；PC/NPC 暂存，其他种族直接完成 Add。
  - `RecvCharacterAdditionalInfo`：合并暂存 Actor；VID 不匹配时记录错误，不新建 Actor。
  - `RecvCharacterAppendPacketNew`：Add2 完整填充字段，并在 `IsInvisibleRace` 时丢弃。
  - `RecvCharacterUpdatePacket`：传递 state、affect、装备、速度、guild、alignment、PK、mount。
  - `RecvCharacterDeletePacket`：删除 Actor 并清理相关附属对象。
- `../40250/Server Client TMP4/ClientVS22/source/UserInterface/PythonCharacterManager.cpp`
  - `DeleteInstance` 立即移除；`DeleteInstanceByFade` 进入 dead instance list 后延迟销毁。
- `../40250/Server Client TMP4/ClientVS22/source/UserInterface/InstanceBase.cpp`
  - `SCreateData` 承接 race、parts、移动/攻击速度、guild、state、affect、mount 等创建字段。

## Current implementation and evidence

- `extension/src/net/classic/classic_parser.cpp`
  - Add 的 PC/NPC 使用 `m_pending_actor` 等待 AdditionalInfo；非 PC/NPC 直接 `mut_spawn`。
  - Add2 现在先执行与 40250 相同的隐身种族过滤，再一次性构造完整 `Entity` 并调用 `mut_spawn_full`；旧 Add 的非 PC/NPC 也保留 `state_flag`、`affect_flag`。
  - Update 现在把 state、affect、装备、速度、guild、alignment、PK、mount 一次传入 `mut_char_update`，不再拆出独立 affect mutation。
  - pending 现在与 40250 一样只有一个静态暂存记录；后一个旧 Add 覆盖前一个，AdditionalInfo 只能完成最后暂存 VID。Delete 后迟到 AdditionalInfo、map reset 后迟到包仍需继续核对。
- `extension/src/net/entity_store.cpp`
  - `apply(GC_CHARACTER_ADD/ADD2/UPDATE)` 现在保留 state、affect；Add2 还完整保存 empire、guild、alignment、PK、mount，并过滤三种隐身 race。
  - `apply(GC_CHAR_ADD_INFO)` 现在必须命中已有 Entity，未知 VID 只记录忽略，不再通过 `touch` 创建部分 Entity。
  - `mut_spawn_main` / generic `GC_MAIN_CHARACTER` 现在统一产生一次 `MainSet` 边沿；首次主角为 `Spawn -> MainSet`，重复主角包仅为一次 `MainSet`，不再依赖重复事件或场景轮询。
- `project/net_world.gd`
  - `_on_spawn` 会替换旧节点；已按 40250 改为仅在 mount 状态切换时保留旧 global position，普通重建使用新包坐标，并始终使用新包朝向。
  - `_fading` 只跟踪旧节点的 blend-out；收到同 VID 新 Spawn 时会立即解除门控并重建 live 节点，旧 tween 独立完成。
  - `_on_info` 只更新已有节点，不会修复 generic AdditionalInfo 误创建的部分节点。
  - `_on_main_set` / `set_local_vid` 没有完全复刻 `SetMainActorVID` 对远端 Actor 字典和动态实例的清理范围。
- `extension/src/net/m2_client.cpp`
  - classic Add2 现在由 `mut_spawn_full` 产生一条完整 Spawn，再由 `pump_classic` 统一向 Godot 发出；不会再拆成 Add2 Spawn + Info + affect 三条事件。

## Branch matrix

| 场景 | 40250 行为 | 当前端行为 | 结论 |
|---|---|---|---|
| 旧 Add 新 VID | 保存 Add 字段；PC/NPC 等待 AdditionalInfo，其他种族直接 AppendActor | PC/NPC 使用单个 static-equivalent pending；非 PC/NPC 现在完整保存 state/affect | PARTIAL |
| AdditionalInfo 命中 | 合并暂存记录后只创建完整 Actor | classic parser 命中 pending 后完整 Spawn；generic apply 命中已有 Entity 后发一次 Info | PARTIAL |
| AdditionalInfo 未命中 | 记录错误，不创建 Actor | classic parser 与 generic apply 均不创建 Entity | MAPPED |
| Add2 新 VID | 隐身种族直接丢弃；其他分支一次性填满字段后 AppendActor | 两条 parser/apply 路径均过滤隐身 race，并一次性填满字段后 `mut_spawn_full` | PARTIAL |
| Update 已有 VID | 按固定顺序更新装备、guild、affect、速度、alignment、PK、state、mount | shared mutator 一次更新完整字段并发一次 Info；平台渲染副作用仍需核对 | PARTIAL |
| Update 未知 VID | 记录错误，不创建 | mutator 丢弃；generic update 丢弃 | MAPPED（字段完整性仍需补测） |
| Delete 远端 | `DeleteInstanceByFade`，并清理附属引用 | Godot 远端 fade + queue_free；同 VID 新 Spawn 可立即建 live replacement | PARTIAL：dead-list 与 Godot 双节点短时并存仍是平台适配 |
| Delete 主角色 | 立即删除 | main/local 由 game scene 和 net world 分层清理 | PARTIAL |
| 同 VID 重用 | 非 mount 切换使用新坐标；mount 切换可保留旧位置，朝向使用新包 | `_on_spawn` 已按 mount 状态决定是否保留位置，朝向统一取新包；淡出期间允许立即替换 live 节点 | PARTIAL：旧 dead-list/tween 的跨帧可见性仍是平台适配 |
| Main VID 切换 | 清空 Actor 字典、重置位置，并清理动态实例 | 只设置 main/local VID 并移除本地节点；通常依赖 map reset | PARTIAL |
| 可见性 | distance、wall、AFFECT_SHOW_ALWAYS、动态实例规则 | data/node 两层可见性和 fade 已有对应测试 | MAPPED（frame/淡出时序为平台适配） |

## Equivalence matrix

| 项目 | 状态 | 证据/缺口 |
|---|---|---|
| Preconditions | MAPPED | unknown AdditionalInfo/update 不创建；Add/Add2 隐身 race 在 parser/apply 两条入口均提前丢弃 |
| Branch structure | PARTIAL | Add/AdditionalInfo/Add2/Update 的隐身、PC/NPC、主角色、未知 VID 和交错旧 Add 已覆盖主要分支；Delete/map reset 后迟到包仍缺 fixture |
| Algorithms/formulas | PARTIAL | 可见距离和 EntityStore tick 有对应实现；同 VID 的 mount 位置保留和淡出期间立即重建条件已对齐，旧 dead-list/tween 的跨帧并存仍是平台适配 |
| State transition order | PARTIAL | Add2 已变为单次完整 Spawn，Update 已合并为一次 shared mutator；渲染桥接的逐字段副作用顺序仍需验证 |
| Data completeness | MAPPED | Add/Add2/Update/AdditionalInfo 的协议字段已落入 EntityStore，包含 state/affect/empire/guild/alignment/PK/mount |
| Constants/units | PARTIAL | VID、位置、yaw、移动速度和 mount 标志要在 Add/Update/Move 组合包中逐字段验证 |
| Timing/event sources | PARTIAL | 40250 manager update/dead list 与 Godot frame、signal、queue_free 的交错未完成证明 |
| Resource/data sources | PARTIAL | 40250 `SCreateData`/`CInstanceBase` 与当前 model factory 的失败、替换、升级 ownership 未完全覆盖 |
| Protocol side effects | PARTIAL | Add/Info/Update/Delete 入口已映射；Add2/unknown AdditionalInfo 已对齐，渲染层删除/更新副作用仍需证明 |
| Interruption/failure/cleanup | PARTIAL | 模型创建失败、升级中 Delete、pending stale、Delete/map reset 后迟到包和主 VID 清理仍需自动测试 |

## Required tests

- 旧 Add -> AdditionalInfo 的命中、未知 VID、交错两个 Add、Delete 后迟到 AdditionalInfo、map reset 后迟到 AdditionalInfo。
- Add/Add2 的完整字段快照：race/type/position/yaw/speeds/state/affect/empire/guild/alignment/PK/parts/mount/name。
- 隐身种族在旧 Add 和 Add2 中均不产生 Entity/node。
- Update 前后 state、affect、装备、guild、速度、alignment、PK、mount 的字段和事件顺序。
- Add -> Info -> Update -> Delete -> 同 VID Add，分别覆盖普通远端、mount 切换、非 mount 切换、淡出未完成和模型升级中；淡出未完成时新 Add 必须立即建 live replacement。
- 主 VID 切换时旧 Actor、HP、尾标、target、hover、模型和动态实例的清理顺序。
- 模型工厂返回失败、map reset 中断、重复 Delete、重复 Add 和跨帧 signal 的一致性。

## Deep audit round 2026-09-20

本轮补做了参考实现的创建/重建/可见性时序核对，并运行实体层与 Godot 节点层回归：

1. 40250 `CNetworkActorManager::Update()` 在 `CPythonNetworkStream::OnProcess()` 中每次网络处理调用 `__UpdateMainActor()`，再遍历 Actor 字典；当前 `NetWorld._process()` 已按每个 Godot frame 调用 `_update_visibility()`，不再使用 100ms 节流。`net_world_vis_test.gd` 已覆盖远端进入范围、单次建节点、离开范围淡出、数据层保留和重新进入，当前通过；旧版本的 4 项可见性失败已不再复现。
2. 参考 `__AppendCharacterManagerActor()` 对已有 VID 重建时读取旧坐标，但只有从骑乘到非骑乘或反向切换才覆盖新创建数据的坐标；当前 `_on_spawn()` 已改为只在 mounted 布尔状态切换时保留旧位置，普通同 VID Add/换装使用新坐标，朝向始终使用新包。
3. 参考显式 `RemoveActor()` 对普通远端 actor 走 `DeleteInstanceByFade`，主 actor 走立即 `DeleteInstance()`；`_on_despawn()` 现已按 `_main_vid` 区分这两个分支。`_on_spawn()` 仍在同 VID 新 Spawn 时解除 `_fading` 并立即创建 live replacement，旧 tween 只负责旧节点。重复 Delete 和跨帧双节点生命周期仍需继续核对。
4. 本轮已修复 Add/Add2/Update 的字段和分支差异：classic parser 的旧 Add 非 PC/NPC、Add2、Update 与 generic `EntityStore::apply` 均通过完整字段结构或 shared mutator 保留 state/affect 等字段；Add2 过滤 20025/20038/20039；未知 generic AdditionalInfo 不再 `touch()` 创建半实体。随后又将 classic pending 从 keyed map 收敛为 40250 的单个 static-equivalent 槽，并覆盖交错 Add；Delete/map reset 后迟到 AdditionalInfo 和渲染层副作用顺序仍需验证。
5. `SetMainActorVID` 参考实现会清空 NetworkActor 字典、重置主坐标；当前 `NetWorld::_on_main_set()` 只改 `_main_vid` 并重刷名字色，旧远端节点、动态实例和 UI 引用的清理依赖外层 map reset，主 VID 切换的独立语义未证明。

## Evidence run

- `./build/extension/net_entity_test`：PASS，证明 EntityStore 的部分 Add/Info/Update/Delete、字段和状态队列夹具仍可运行。
- `godot --headless --path project --script net_world_vis_test.gd`：PASS，覆盖主角移动后可见实体创建、远端节点一次性构建、离开范围剔除、`entity_removed` 一次性事件、强制可见实体和重新进入。
- `project/gamescene_test.gd`：PASS，但该测试验证的是场景装配/实体镜像/初始定位，不覆盖上述可见性节流和同 VID 淡出竞态。
- 因此本合同继续 `PARTIAL`，可见性和字段回归已通过，但 Delete/map reset 后迟到包、主角色清理和渲染层副作用顺序仍未完全证明。

### Active UserInterface actor-sync review

- `NetworkActorManager.h` 保存每个 actor 的服务器时间、目标位置/持续时间、当前/目标坐标、owner/victim、affect flags 和 `UpdateActor/MoveActor/Update`；`PythonCharacterManager` 负责将其映射到可渲染实例和删除列表。
- 当前 `EntityStore`/`NetWorld` 以 packet 快照和 Godot interpolation 驱动 remote view，基础移动同步可用，但没有参考端 actor manager 的 server-time movement、owner/victim 和统一删除/fade/update transform 入口；这也是远端动作事件、VID 复用和跨图旧包清理的剩余风险。
- 本轮完成 NetworkActorManager 与角色 manager 接口静态核对，实体同步合同继续为 `PARTIAL`。

## Implementation fix round 2026-09-22T04:30Z

沿 40250 `NetworkActorManager::__AppendCharacterManagerActor()` 和
`CPythonNetworkStream::RecvMainCharacter()` 复核同 VID 重建及主实例注册边沿，补齐了两处已证实差异：

- `NetWorld._on_spawn()` 现在只在旧/新实例的 mounted 布尔状态发生变化时保留旧 global position；普通重生、换装或 VID 重用使用新 Add 数据的坐标。无论是否上下马，旋转都使用新包的 `angle_deg`。
- `EntityStore::mut_spawn_main()` 和 `EntityStore::apply(GC_MAIN_CHARACTER)` 现在在首次主角建立时按 `Spawn -> MainSet` 发出一次注册边沿，重复主角包只发一次 `MainSet`，消除了旧实现的缺失/重复通知。

新增回归：

- `project/net_world_respawn_test.gd`：普通同 VID 重建坐标/朝向、上下马重建保留旧位置但使用新朝向。
- `extension/tests/net_entity_test.cpp`：首次主角注册和重复主角包的 `MainSet` 次数。

修复前上述测试分别能够复现普通重建位置/朝向错误、上下马朝向错误以及 `MainSet` 缺失/重复；修复后
`build/extension/net_entity_test` 和 `net_world_respawn_test.gd` 通过。Add2 隐身种族、AdditionalInfo 未命中、旧 Add 字段完整性已在后续修复轮补齐；淡出期间同 VID 重用和主 VID 切换清理当时仍保持 `PARTIAL`。

## Implementation fix round 2026-09-22T05:10Z

按 40250 `PythonNetworkStreamPhaseGameActor::RecvCharacterAppendPacket*`、
`RecvCharacterAdditionalInfo`、`RecvCharacterUpdatePacket` 和
`NetworkActorManager::AppendActor/UpdateActor` 的完整字段链复核并修复：

- classic 旧 Add 的即时实体现在以完整 `Entity` 写入 state/affect；PC/NPC pending 合并继续一次完整 Spawn。
- classic Add2 和 generic Add2 都执行 `IsInvisibleRace` 等价过滤，并一次性保存 name、parts、state、affect、empire、guild、alignment、PK、mount 等全部字段。
- classic/generic Update 统一经 `mut_char_update` 更新 state、affect、装备、速度、guild、alignment、PK、mount，并在发生变化时只发一次 Info；mount 变化仍发 mount cue。
- generic AdditionalInfo 仅接受已存在的 actor；未知 VID 被忽略，不创建半实体，并补齐 empire 和字段变更检测。

新增/扩展回归：

- `extension/tests/net_entity_test.cpp`：Add/Add2/Update 全字段、隐身 Add2、未知 AdditionalInfo、单次 Spawn/Info。
- `extension/tests/net_classic_session_test.cpp`：40250 Add2 全字段、三种隐身 race、未知 AdditionalInfo 和清理。

修复前新增回归可复现 state/affect 丢失、Add2 元数据丢失、隐身实体错误出现、unknown AdditionalInfo 半实体和事件计数差异；修复后两个 native 测试均通过。淡出期间同 VID 重用、pending 交错清理、主 VID 切换清理和 Godot 可见性时序仍保持 `PARTIAL`。

## Implementation fix round 2026-09-22T05:35Z

按 40250 `RemoveActor -> DeleteInstanceByFade` 与后续 `AppendActor ->
__AppendCharacterManagerActor` 的实例生命周期复核并修复：

- `_on_despawn()` 的旧节点继续渐隐；如果渐隐未结束就收到同 VID 的新 Spawn，`_on_spawn()` 解除旧 `_fading` 门控并立即创建新的 live 节点，符合参考端 dead-list 不占用 `GetInstancePtr()` 的行为。
- 旧 fade tween 只释放旧节点，不会删除新节点；新节点使用新的权威位置和旋转。

扩展 `project/net_world_respawn_test.gd`，修复前可复现淡出期间同 VID Spawn 被直接丢弃；修复后覆盖立即重建、位置以及旧 tween 完成后的新节点存活。

## Implementation fix round 2026-09-22T05:55Z

按 40250 `PythonNetworkStreamPhaseGameActor::RecvCharacterAppendPacket` 的
`static SNetworkActorData s_kNetActorData` 和
`RecvCharacterAdditionalInfo` VID 匹配分支复核并修复：

- `ClassicParser::m_pending_actor` 从 keyed map 改为单个 `std::optional<Entity>`，后一个 PC/NPC 旧 Add 覆盖前一个，避免当前端比 40250 多出可交错完成的 pending actor。
- AdditionalInfo 只有在 VID 命中最后暂存记录时才调用一次 `mut_spawn_full`；被覆盖 VID 的迟到 AdditionalInfo 只记录未处理 header，不创建实体。

新增 `net_classic_session_test.cpp` 的交错旧 Add 回归，修复前可复现两个 pending 和第一个 VID 错误生成；修复后 `net_classic_session_test` 与 `net_entity_test` 通过。Delete 后迟到 AdditionalInfo、map reset 后迟到包、主 VID 清理和渲染副作用顺序仍保持 `PARTIAL`。

## Evidence reconciliation 2026-09-22T06:15Z

重新以当前工作树运行可见性回归：`net_world_vis_test.gd` 通过。当前 `_process()` 已逐帧执行 `_update_visibility()`，与 40250 `CNetworkActorManager::Update()` 的检查频率一致；因此旧审计中关于 100ms 节流和 4 项可见性失败的描述已更新为历史发现，不再作为当前缺陷。Add2 的当前 pump 也已改为单次完整 Spawn，旧的“Spawn + Info + affect 拆分”描述同步更正。

## Implementation fix round 2026-09-21T07:08Z

按 `CNetworkActorManager::__RemoveCharacterManagerActor` 的主/远端分支修正
`NetWorld._on_despawn()`：`_main_vid` 现在走立即删除，普通远端 actor 继续走
`DeleteInstanceByFade` 等价的渐隐路径。新增 `net_world_respawn_test.gd` 断言主角
不会进入 `_fading`，同时保留普通远端 actor 的同 VID 重建和旧 tween 隔离验证。

`net_world_respawn_test`、`net_world_reset_test`、`net_world_vis_test`、
`fly_target_lifecycle_test`、`netbridge_test` 均通过。主 VID 切换、Delete/map reset
后的迟到包和完整渲染副作用顺序仍保持 `PARTIAL`。

## Implementation fix round 2026-09-21T07:15Z

继续核对 `RecvCharacterAdditionalInfo` 的单槽暂存生命周期时发现：旧 Add
等待 AdditionalInfo 期间如果先收到 Delete，或随后进入 Loading/warp，参考端的
静态 `SNetworkActorData` 已失效；当前端原先仍保留 `m_pending_actor`，迟到的
AdditionalInfo 可以错误生成旧角色。现已在匹配 VID 的 Delete 中清槽，并新增
`ClassicSession::reset_for_map_change()`，将 parser 暂存和 EntityStore 一起清理。

新增回归覆盖 Delete 后 AdditionalInfo、map reset 后 AdditionalInfo；
`net_classic_session_test`、`net_entity_test` 和 `mtgodot` 构建通过。主 VID
切换、跨连接迟到 Update/Move 和渲染副作用顺序仍保持 `PARTIAL`。

## Status

`PARTIAL`。本轮已完成 Add/Add2/Update/AdditionalInfo 的主要协议字段、前置条件、事件粒度、单槽 pending、逐帧可见性和淡出期间同 VID 立即重建；仍必须补齐 Delete/map reset 后迟到包、主角色清理和 Godot 渲染副作用顺序的独立证明，不能宣称与 40250 完全等价。

## Implementation fix round 2026-09-21 — SetMainActorVID lifecycle boundary

本轮继续核对 40250 `CNetworkActorManager::SetMainActorVID`。参考实现收到新的主角色
VID 时会重置主坐标并清空 `m_kNetActorDict`，旧角色的 live instance、目标和临时 actor
状态不会带入新的主角色生命周期。当前端此前的 `NetWorld._on_main_set()` 只更新
`_main_vid` 并重算名字颜色；如果没有先经过完整 `world_reset`，旧远端节点、target/
hover、HP/击退同步、伤害队列和聊天尾标仍可能残留。

现在主 VID 发生实际变化时，`_on_main_set()` 会先解除目标特效，立即删除所有旧 live
actor，清空模型升级队列、sync-push/push、伤害队列、聊天尾标和渐隐索引，再注册新的
主 VID；相同 VID 的重复通知不触发清理。新增 `net_world_main_switch_test.gd` 覆盖旧
远端节点、target/hover 和临时表现状态在切换边沿全部清除，并与
`net_world_reset_test.gd`、`net_world_respawn_test.gd`、`net_world_vis_test.gd` 一起通过。

本轮只闭合了 Godot presentation 层对应 `SetMainActorVID` 的清理边沿；EntityStore 中
已有快照在切换后重新可见的生成时序、旧渐隐节点的最终销毁、跨连接迟到 Move/Update
以及完整渲染副作用顺序仍保持 `PARTIAL`。