mtgodot-poc/audit/contracts/world.npc-drop-actor-spawn.md

# world.npc_drop_actor_spawn

## Scope

审计 40250 Windows 客户端的 NPC、怪物、石头、建筑/墙体、玩家实体、地面掉落、所有权、私人商店招牌和实体清理链。判断标准是实体是否按相同的包字段、VID 生命周期、分类、可见性、模型/动作资源、名字尾标、掉落所有权和删除时序进入客户端；服务端掉落概率、散落规则或本地活动规则不能因为在当前端有脚本就当作 40250 客户端等价实现。

## Reference call chain

- `UserInterface/PythonNetworkStreamPhaseGameActor.cpp`
  - `RecvCharacterAppendPacket` / `RecvCharacterAdditionalInfo` / `RecvCharacterUpdatePacket` 解包 race、character type、parts、affect、位置、速度、名字、公会、等级、mount 等字段；不可见 race 不创建实例；角色新增最终进入 `CNetworkActorManager` / `CInstanceBase`，非零 mount vnum 由角色实例处理。
  - `RecvCharacterDeletePacket` 通过 actor manager 删除 VID，并同步通知私人商店消失。
  - `RecvOwnerShipPacket` 把 owner VID 与 victim VID 写入网络 actor manager。
- `UserInterface/NetworkActorManager.cpp` / `UserInterface/PythonCharacterManager.cpp` / `UserInterface/InstanceBase.cpp`
  - actor manager 负责 add/update/move/delete、VID 查找和实例状态；character manager 负责碰撞、拾取、排序、距离可见性和渲染列表；`CInstanceBase` 按 race/type 选择模型、动作、名字和状态。
  - 40250 的可见性由 `CHAR_STAGE_VIEW_BOUND`、`AFFECT_SHOW_ALWAYS` 和 wall 判定共同决定；离开范围时走 delete/blend-out，数据与渲染实例不是同一层。
- `UserInterface/PythonNetworkStreamPhaseGameItem.cpp` / `UserInterface/PythonItem.cpp` / `UserInterface/PythonTextTail.cpp` / `Packet.h`
  - `RecvItemGroundAddPacket` 将全局坐标转本地坐标后调用 `CPythonItem::CreateItem(vid, vnum, x, y, z)`；未知 item data 不创建地面物体。
  - `RecvItemOwnership` 调用 `SetOwnership(vid, name)`，更新独立 owner 尾标；`RecvItemGroundDelPacket` 删除地面实例并删除对应 item text tail。
  - `CreateItem` 从 `CItemData::GetDropModelThing()` 建立掉落模型，注册 item text tail；`GetCloseMoney` / `GetCloseItem`、模型拾取和网络 `CG_ITEM_PICKUP` 负责交互，服务器回包才完成真正拾取。
- `UserInterface/PythonNetworkStreamPhaseGame.cpp`
  - `RecvShopSignPacket` 对空 sign 触发 `BINARY_PrivateShop_Disappear`，非空 sign 触发 `BINARY_PrivateShop_Appear(vid, sign)`；该包不是普通实体 spawn，必须依赖已存在角色 VID。

## Current call chain

- `extension/src/net/classic/classic_parser.cpp` 已将 character add/additional/update/delete、`GC_OWNERSHIP`、`GC_ITEM_GROUND_ADD/DEL/OWNERSHIP` 和 `GC_SHOP_SIGN` 分别写入 `EntityStore`/ground store；`M2Client::poll` 将实体和地面变化转为 Godot signal。
- `extension/src/net/entity_store.cpp/.h` 以 VID 保存实体，spawn 是整行替换；地面掉落独立保存 `vid/vnum/pos/owner`，shop sign 是已存在实体的可变字段；未知 VID 的 shop sign/owner 不凭空创建实体。
- `project/net_world.gd` 在数据层保存全部实体，在场景层按主角距离、`AFFECT_SHOW_ALWAYS` 和 wall race 创建/淡出节点；`_on_spawn` 写入分类、名字、parts、affect、速度、mount 和 shop sign，`_on_info` 刷新可变字段；`project/ui/mob_view.gd` 负责 NPC/怪物模型、动作、受击和名字补点。
- `project/ui/ground_items.gd` 监听 ground add/del，按 item proto 解析名字/颜色，加载 item bag/money 模型或 fallback BoxMesh，创建名字与 owner 尾标、稀有掉落光柱，按距离和 500ms 节流发送拾取；服务端 ground del 负责最终消失。
- `project/entity_rules.gd`、`project/metin_spawn_event_system.gd`、`project/mob_drop_scatter.gd` 等本地 helper 还承担木门/建筑分类、石头活动、掉落散落和所有权保护等自定义规则；这些不等于 40250 Windows 客户端本身的 authority。

## Branch matrix

| 场景 | 40250 | 当前端 | 结论 |
|---|---|---|---|
| 角色/NPC/怪物新增 | add packet→actor manager→`CInstanceBase`→模型/尾标；不可见 race 跳过 | parser/store→`entity_spawned`→`NetWorld`，可延迟 placeholder 后升级真模型 | PARTIAL：字段链存在，但不可见 race、未知 race、真资源缺失时的失败分支未完整证明 |
| character additional/update | 按包刷新 parts、名字、公会、affect、速度、状态和 shop 相关数据 | `_on_info`/`_apply_field_updates` 按顺序刷新部分字段 | PARTIAL：顺序入口有，角色类型、异常字段、重复/乱序包和实际 model attachment 缺 live 证据 |
| VID 重用 | 删除旧实例后重新 add；actor manager 查找不应残留旧状态 | EntityStore whole-row spawn，NetWorld 销毁并重建节点 | PARTIAL：设计上接近，但旧节点延迟释放与同 VID 新 spawn 的边界没有完整回归 |
| 远端删除/淡出 | actor manager 删除；尾标、商店和交互引用同步清理 | `entity_despawned`→`_fade_and_free`，数据层/场景层分离 | PARTIAL：删除链存在，blend-out 期间重复 spawn、目标/尾标/交互引用的完整时序仍需验证 |
| 距离可见性 | `CHAR_STAGE_VIEW_BOUND`、always-show、wall 分支控制实例和渲染列表 | `_update_visibility` 每帧以 20000cm/20010cm、affect bit、wall race 建/淡出 | PARTIAL：基础分支已映射；距离常量、真实 actor manager 淡出和复杂 wall/always-show 组合仍未完全证明 |
| 建筑/墙体/门 | 由 race 与 InstanceBase/碰撞数据决定，墙体不因距离错误消失 | `entity_rules`/cursor shape 识别 door/building，wall race 强制可见 | PARTIAL：分类与 cursor 入口有；模型、碰撞、阻挡和真实 wall 生命周期未统一证明 |
| 地面掉落新增 | 坐标转换→CItemData drop model→item text tail；未知 vnum 不创建 | ground store→`ground_items`，item bag/money 或 BoxMesh fallback→Label3D | PARTIAL：协议、坐标、名字尾标和 fallback 有；真实 drop model/effect/sound/未知 vnum 失败语义不等价 |
| 地面掉落所有权 | `RecvItemOwnership` 更新独立 owner text tail；服务器仍是拾取 authority | owner 写入 ground row/owner_tag，并在本地 pickup 前做名字判断 | PARTIAL：回包链存在；本地 owner precheck 是额外 optimistic gate，party/anti-flag/native action gate 未完整接入 |
| 地面掉落删除/拾取 | `GC_ITEM_GROUND_DEL` 同步删除模型和尾标；拾取成功依赖服务器包序 | ground del signal 删除节点，pickup 只发送请求 | PARTIAL：删除基础链有；`CG_ITEM_PICKUP→GC_DEL→ITEM_GET/ITEM_SET/UPDATE` 的 live 成功、失败、乱序和回滚未证明 |
| 私人商店招牌 | `GC_SHOP_SIGN` 空/非空走 disappear/appear，依赖已有角色 VID | `shop_sign` 进入实体 info，`_refresh_shop_sign` 创建/释放 Label3D | PARTIAL：空/非空状态可映射；BINARY 私人商店 UI、重复/未知 VID、重连清理和视觉资源不等价 |
| 怪物死亡与掉落 | 死亡/删除/地面掉落由服务端包和 actor/item manager 驱动 | `mob_view` 死亡表现，活动 helper 可生成本地掉落 | GAP（custom authority）：本地散落/活动掉落不能作为 40250 client parity，live server death→drop 时序仍缺证据 |

## Implementation-equivalence matrix

| 项目 | 状态 | 证据/限制 |
|---|---|---|
| Preconditions | PARTIAL | stage、VID、实体/ground store 和部分分类存在；未知 race/vnum、主 VID、模型工厂未就绪和 owner/anti-flag 门控未完整证明 |
| Branch structure | PARTIAL | actor add/info/update/delete、ground add/del/owner、shop sign 主要分支存在；visibility、不可见 race、未知数据和 server rejection 分支不等价 |
| Algorithms/formulas | PARTIAL | 坐标转换、20000cm 可见范围、owner 标签和拾取距离有实现；CItemData 模型选择、碰撞/拾取几何、drop effect 和参考资源算法未统一 |
| State transition order | PARTIAL | parser→store→signal→view 顺序明确；延迟模型升级、淡出、同 VID 重用、ground del 与 owner/sign 乱序的可观察顺序未闭合 |
| Constants/units | PARTIAL | `CHAR_STAGE_VIEW_BOUND`、+10 cull、ground height/pickup 距离、packet fields 有证据；Godot world unit 与 40250 pixel/cm、文本像素度量、模型锚点仍是近似 |
| Timing/event sources | PARTIAL | poll、ground signal、500ms pickup throttle、visibility interval 有；真实 frame cull、blend-out、drop animation/effect/sound、server packet delay 未覆盖 |
| Resource/data sources | PARTIAL | mob/NPC 资源扫描和部分真模型测试通过，但有 4 个 fallback；ground 使用通用 bag/BoxMesh，未证明所有 CItemData drop model、特效、音效和牌匾资源 |
| Protocol side effects | PARTIAL | classic parser/session 与 ground/ownership/shop sign 基础路径存在；完整拾取回包、商店 UI、不可见实体过滤和未知 packet 语义缺 live 证据 |
| Interruption/failure/cleanup | PARTIAL | `net_world_vis_test.gd` 的基本可见性/重显/删除回归已通过；地图切换基础清理已有，但实体淡出、地面掉落、尾标、商店、同 VID 重用、断线/重连和模型 fallback 的组合清理未完整证明 |

## Regression evidence

- `project/net_world_vis_test.gd`：通过；覆盖主角进入范围后的远端节点创建、单次创建、离开范围裁剪和删除信号去重。仍不证明真实 actor manager 的 wall/always-show/模型失败组合。
- `project/entity_rules_test.gd`：通过；验证实体分类/可攻击规则，但不证明 40250 的模型、碰撞和 visibility chain。
- `project/forest_mob_render_test.gd`：24 个结果、0 failures、4 fallback；有 Godot ObjectDB leak warning，且仍需人工资源 sign-off，因此不能标记 PASS。
- `project/mob_view_test.gd`、`project/mob_winding_test.gd`、`project/net_world_push_test.gd`：通过；覆盖单体模型/绕序/受击推开，不能证明完整 actor manager 生命周期。
- `project/test_ground_pickup_parity.gd`、`project/mob_death_drop_test.gd`、`project/test_mob_drop_scatter_parity.gd`、`project/test_metin_spawn_event_parity.gd`：通过；主要覆盖当前端 helper、掉落散落和活动石头规则，不等于 40250 live drop/model/pickup parity。
- `build/extension/net_entity_test`、`build/extension/net_classic_session_test`、`build/extension/net_classic_wire_test`：覆盖部分实体、地面包和协议边界；未覆盖上述 visibility 失败、真实资源失败、完整拾取回包、商店牌匾和重连组合清理。

### Active GameLib spawn/property review

- `GameLib/MonsterAreaInfo.cpp` 保存刷怪区域 origin/size、左右上下边界、数量、随机初始位置、方向、group/leader/VID/name 和清理默认值；`Property.cpp`/`PropertyLoader.cpp`/`PropertyManager.cpp` 为地图 object/property 注册提供 CRC 和 token 数据。
- 当前实体生成主要来自服务端 spawn packet 和 `NetWorld`，地图静态刷怪区域/property 并没有一条等价的客户端本地 `MonsterAreaInfo` 消费链；因此本轮只确认参考数据模型和清理边界，不能把网络实体测试当作静态刷怪 parity。

### Active UserInterface NPC data review

- `PythonNonPlayer.h`/`PythonNonPlayerModule.cpp` 以 MMPT mob table 为权威，提供 `LoadNonPlayerData`、vnum/name/type/event/color、VID event lookup 和按等级区间匹配的 mob list；`PythonCharacterModule.cpp` 再用 event type 决定角色 render/behavior。
- 当前 `Metin2Proto`/`EntityStore` 能解析 mob proto 并生成网络实体，但 event type、mob color/name、等级筛选和 unknown vnum/缺记录失败分支没有完整接入 `NetWorld`/NPC view；本轮静态证据确认“能生成一个怪物”不等于 NPC data chain 一致。
- 本轮完成 UserInterface NPC 数据入口静态核对，合同保持 `PARTIAL`。

## Deep audit round 2026-09-20

本轮复跑 `project/net_world_vis_test.gd` 时发现固定 100ms 可见性节流会让快速连续帧的结果不稳定；40250 `CPythonCharacterManager::Update` 每帧执行距离检查，因此已改为每帧调用 `_update_visibility()`。连续两次测试均 PASS。该结果只证明当前 Godot 可见性状态机的基础边沿，不足以把 40250 的 actor manager 淡出、wall 判定和真实资源失败分支标为等价。

## Status

`PARTIAL`。当前端已经具备 40250 实体/掉落协议的主要 native parser、VID 数据层、NPC/怪物场景层、地面物体和 shop sign 状态入口；可见性基础回归和每帧更新边界已修复，但掉落模型/特效/音效、建筑碰撞、完整 actor/ground 生命周期和 live 拾取/商店回包证据仍不足。

### 2026-09-22 死代码删除

以下文件只被自身测试引用、运行时从不加载，已删除；本文中以它们为实现或证据的结论作废，相关行为需按 40250 源码单元重新移植：`metin_spawn_event_system.gd`, `test_metin_spawn_event_parity.gd`。