mtgodot-poc/audit/contracts/world.dungeon-activity.md

# world.dungeon_activity

## Scope

审计 `GC_DUNGEON` 目标点、地下城事件/计时、`DUNGEON_RESULT` 结果窗口、地图导航提示、镜头/屏幕效果，以及当前端额外提供的 Boss、排行和具体副本 helper。判断标准是当前端是否复现 40250 Windows 客户端的协议字段、目标点状态、到达/重复提示、结果展示和中断清理；服务端才拥有副本奖励、Boss 血量、排行和副本规则，当前端本地计算这些内容不能作为 40250 客户端 parity 证明。

## Reference call chain

- `UserInterface/PythonNetworkStreamPhaseGame.cpp`
  - `RecvDungeon` 读取 `TPacketGCDungeon`；`TIME_ATTACK_START` 分支在 40250 中不启动本地计时，`DESTINATION_POSITION` 读取两个坐标并调用 `CPythonPlayer::SetDungeonDestinationPosition`。
  - `PythonEventManager.cpp` 的 `DUNGEON_RESULT` 分支把九个整数交给 `interface.ShowDungeonResult`；客户端展示结果，不在此处结算奖励。
- `UserInterface/PythonPlayer.cpp` / `PythonPlayer.h`
  - `SetDungeonDestinationPosition` 保存全局像素/厘米目标，立即调用 `AlarmHaveToGo`；更新时用整数 Manhattan 距离判断 `< 10000` 到达，未到达且超过 20 秒再次提示，并在到达时清空目标。
  - `AlarmHaveToGo` 创建 `effect/etc/compass/appear_middle.mse`，朝目标方向旋转罗盘提示。
- `UserInterface/PythonEventManager.cpp` / `GameLib/GameEventManager.cpp`
  - 事件窗口负责结果 UI、等待和清理；`GameEventManager` 的相关路径是屏幕波动/运动效果，不是 Boss 或排行 authority。
- `GameLib/MapManager.cpp` / `Packet.h` / `PythonNetworkStreamPhaseGame.h`
  - 提供地图/副本协议常量和包布局；副本目标与结果由服务端包驱动，客户端没有本地奖励、Boss HP 或排行榜结算。

## Current call chain

- native `EntityStore::apply` 已解析 `GC_DUNGEON` 的 subheader 和目标坐标；`M2Client::poll` 发出 `dungeon_event`，`M2Client::request_dungeon`/`ClassicSession::send_dungeon` 能发送请求。
- `project/dungeon_state.gd` 已实现 `TIME_ATTACK_START` 不启动本地计时、目标坐标转换、立即提示、10,000 cm Manhattan 到达阈值、20 秒重复 alarm、到达清理和 `world_reset` 清理。
- `project/ui/dungeon_result_ui.gd` 已接收九个字段并呈现击杀、隐藏目标、药水、复活、完成、时间和经验等结果；`game_scene.gd` 已连接 `dungeon_result_requested`。
- `project/world_boss_system.gd`、`project/dungeon_ranking_system.gd`、`project/spider_dungeon_system.gd`、`project/flame_dungeon_razador_system.gd`、`project/endless_spire_dungeon_system.gd` 是当前端额外的本地规则/authority helper。40250 Windows 客户端没有对应的本地 Boss HP、掉落、排行或副本奖励实现，不能把这些 helper 的单元测试当成 parity PASS。

## Branch matrix

| 场景 | 40250 | 当前端 | 结论 |
|---|---|---|---|
| 地下城请求 | `__CanActMainInstance`/游戏阶段检查后发送对应请求；结果由服务端包驱动 | native 只做 `is_in_game` 和 session send；没有完整动作门控、请求去重和拒绝回滚证据 | PARTIAL |
| `TIME_ATTACK_START` | `RecvDungeon` 消费包但分支为空，不凭客户端包启动计时 | `DungeonState` 记录 subheader 但不启动本地计时 | PASS（已覆盖的分支） |
| 目标点回包 | 读取 x/y→`SetDungeonDestinationPosition`→立即 compass alarm | `GC_DUNGEON`→`dungeon_event`→坐标转换→`destination_changed` 和 `alarm_requested` | PARTIAL：协议/状态接近，但 alarm 没有在 `game_scene.gd` 接到实际 compass/effect 消费者 |
| 目标点重复提示 | 未到达时每 20 秒 `AlarmHaveToGo`，使用参考 `.mse` 资源并按目标方向旋转 | `DungeonState` 每 20 秒发 `alarm_requested`，但当前没有实际资源效果调用 | GAP：信号存在，视觉副作用缺失 |
| 目标到达 | Manhattan `< 10000` 后清除目标并停止提示 | 同阈值和清理信号已实现 | PASS（状态算法） |
| 地图切换/断线 | 玩家状态重置并清理目标提示 | `world_reset` 清理目标；实际断线、重连、旧包乱序未完整验证 | PARTIAL |
| 副本结果 | `DUNGEON_RESULT` 九个整数交给 `ShowDungeonResult`，仅展示服务端结果 | `QuestDialog` 发 `dungeon_result_requested`，`DungeonResultUI` 展示九字段 | PARTIAL：展示链存在，但真实 `DUNGEON_RESULT`→UI 回包和关闭/重复/中断未端到端覆盖 |
| 奖励、Boss、排行 | 客户端不计算副本奖励、Boss HP、掉落或排行榜权威 | 本地 helper 直接推进 Boss 阶段/掉落/库存奖励和排行统计 | GAP（custom authority）：与 40250 客户端职责不一致 |
| 屏幕波动/地图事件 | `GameEventManager` 处理屏幕波动和运动事件 | 当前副本合同没有证明该引用链的实际资源/中断效果 | PARTIAL：不能用 Boss/排行 helper 代替原版事件效果 |

## Implementation-equivalence matrix

| 项目 | 状态 | 证据/限制 |
|---|---|---|
| Preconditions | PARTIAL | native 游戏阶段、包长度和目标字段检查存在；请求动作门控、重复请求、服务器拒绝和活动阶段限制未与 40250 等价证明 |
| Branch structure | PARTIAL | dungeon subheader、目标、到达、结果主分支存在；alarm 没有实际 compass 消费者，结果回包和中断分支证据不足 |
| Algorithms/formulas | PARTIAL | 目标坐标转换、10,000 cm Manhattan 阈值、20 秒间隔与参考一致；实际 `.mse` 方向/资源效果缺失，本地 Boss/排行公式属于额外 authority |
| State transition order | PARTIAL | 包→native event→目标状态→HUD 的顺序接近；alarm 只到 signal，world reset/重连/旧包清理和结果窗口生命周期未闭合 |
| Constants/units | PARTIAL | subheader 0/1、10,000 cm、20 秒和九字段结果存在；server cm→Godot world 的轴/地图基准需实机验证，Boss/排行常量不能视为 40250 客户端常量 |
| Timing/event sources | PARTIAL | 目标初次与 20 秒 alarm、到达检测存在；实际 compass effect、结果重复包、断线/切图/重连和计时事件未覆盖 |
| Resource/data sources | PARTIAL | 结果字段来自服务端包，目标坐标来自 `GC_DUNGEON`；参考 `appear_middle.mse` 没有实际接入，Boss/排行使用本地硬编码表 |
| Protocol side effects | PARTIAL | `GC_DUNGEON` parser、请求和结果 UI 入口存在；未证明请求被正确门控，alarm/结果的完整 UI/音效/资源副作用不完整 |
| Interruption/failure/cleanup | GAP | 目标 alarm、结果 UI、Boss/排行 helper 在拒绝、断线、乱序、地图切换、重复结果和重连时的恢复没有完整回归；本地 helper 可绕开服务器 authority |

## Regression evidence

- `project/dungeon_state_test.gd`：通过，覆盖目标状态、坐标、到达阈值和 alarm 计数；没有证明实际 compass `.mse` 消费者已连接。
- `project/dungeon_result_test.gd`：通过，覆盖九字段结果窗口的本地展示；没有真实 `DUNGEON_RESULT` native 回包、重复结果、断线和关闭时序。
- `project/test_dungeon_ranking_parity.gd`、`project/test_spider_dungeon_parity.gd`、`project/test_spider_dungeon_key_parity.gd`、`project/test_flame_dungeon_razador_parity.gd`、`project/test_endless_spire_dungeon_parity.gd`：通过，验证当前端自定义 helper；40250 客户端没有同等本地 authority，因此不能证明 Windows 客户端 parity。
- `build/extension/net_entity_test`、`build/extension/net_classic_session_test`、`build/extension/net_classic_wire_test`：通过基础 parser/session/wire 检查；未覆盖 alarm 视觉副作用、目标乱序/旧包、结果 live UI、断线重连和 server rejection。

### Active GameLib dungeon-block review

- `GameLib/DungeonBlock.cpp`/`.h` 以资源 `CGraphicThing` 建立多个 `CDungeonModelInstance`，维护 deformable vertex buffer、bounding sphere、model intersection、static collision data、height instance、Update/Render/Shadow 和 Destroy；它是地图对象碰撞/渲染生命周期的一部分。
- 当前副本 helper 与 dungeon HUD 主要实现目标、结果和本地状态，没有 40250 `DungeonBlock` 的多模型/碰撞/高度/阴影对象链；`DUNGEON_RESULT` 测试通过不能覆盖该地图对象资源语义。
- 本轮完成 `DungeonBlock` 活跃源码静态核对，地下城合同继续为 `PARTIAL`。

## Status

## Deep audit round 2026-09-21

### Fresh regression results

- `dungeon_state_test.gd`、`dungeon_result_test.gd`、`test_dungeon_ranking_parity.gd`、`test_spider_dungeon_parity.gd`、`test_spider_dungeon_key_parity.gd`、`test_flame_dungeon_razador_parity.gd`、`test_endless_spire_dungeon_parity.gd` 均退出码 0；对应本地断言为 30/30、32/32、34/34、31/31、22/22。
- `net_entity_test`、`net_classic_session_test`、`net_classic_wire_test` 均退出码 0。

### Static parity conclusion

- `TIME_ATTACK_START`、目标坐标转换、10,000 cm Manhattan 到达阈值和 20 秒 alarm 状态算法已接近参考实现；但 `alarm_requested` 没有实际消费 `appear_middle.mse`、方向旋转和音效的生产链。
- `DUNGEON_RESULT` 九字段展示窗口只有本地 UI/假回包证据，尚未证明真实 native 回包到窗口的重复、关闭、断线和重连时序。
- Boss、排行、蜘蛛/火焰/无限塔 helper 在本端直接维护阶段、掉落、奖励或统计；这些不是 40250 Windows 客户端 authority，不能把其单元测试计为 parity 通过。
- 请求门控、拒绝回滚、旧包/乱序、地图切换和重连清理仍缺 live 证据。

### Status update

本轮仍为 `PARTIAL`；完成三个地下城/活动方向的合同审计并登记，未修改实现。

`PARTIAL`。当前端已经具备 `GC_DUNGEON` 目标点的主要 parser、坐标状态和与 40250 一致的 Manhattan/20 秒算法，也有结果窗口骨架；但 40250 的 compass `.mse` alarm 没有实际消费者，结果链缺少 live 回包时序证据，且 Boss、排行和具体副本 helper 是当前端本地 authority，不是 40250 Windows 客户端实现。本轮完成审计并记录，未修改实现。