mtgodot-poc/audit/contracts/world.reset-cleanup.md

world.reset_cleanup

Scope

审计 40250 在进入 Loading、换图、死亡/断线和退出时，对网络状态、Actor、地面物品、飞行物、特效、地图和临时 UI 的清理边界与顺序。

Reference call chain

• CPythonNetworkStream::SetLoadingPhase
  • 执行旧阶段 leave callback。
  • 切到 Loading 并设置 Loading 回调。
  • 调用 CPythonPlayer::Clear()。
  • 调用 CFlyingManager::Instance().DeleteAllInstances()。
  • 调用 CEffectManager::Instance().DeleteAllInstances()。
  • 调用 __DirectEnterMode_Initialize()。
• CNetworkActorManager::Destroy / __RemoveAllActors / __RemoveAllGroundItems
  • 清空 Actor 字典、主 VID、角色实例、地面物品。
• CMapManager::LoadMap / UnloadMap / Clear
  • 先离开/清理当前地图，再加载 property、terrain、object 和 environment，最后 Enter 新地图。
• CPythonApplication::Destroy
  • 按 manager 所有权释放窗口、角色、地图、特效、网络、声音和设备资源。

Current call chain

• M2Client / EntityStore::reset_for_map_change
  • 清空实体、目标、战斗/交互状态以及 Loading 前产生的临时网络队列。
• NetPlay.clear_for_map_change
  • 对齐 CPythonPlayer::Clear()，清空当前 Actor 的目标、预约、连击、命中窗、击退同步、技能/钓鱼/攻击门和经验基线。
• GameScene::_on_world_reset
  • 重置主角同步尝试、调用 NetWorld.clear_for_map_change() 与地面物品清理，关闭临时窗口并停止 BGM。
• NetWorld.clear_for_map_change
  • 清理 Actor 节点、HP 条、伤害队列、主 VID、PvP 和决斗状态，并调用 FlyObject.clear_for_map_change()。
• FlyObject.clear_for_map_change
  • 清理活动弹道、弹道视觉节点和爆点视觉节点。
• GameScene::_reload_map_for_warp
  • 先对旧 Metin2World 调用 unload_map() 并 queue_free()，再创建并加载新 world；静态顺序已对齐参考端先 Leave/Clear 旧地图再 Load。
• Metin2World::unload_map
  • 清理 chunks、stream queue、environment、objects root、光照和缓存；当前析构依赖 Godot 节点生命周期，没有独立的 Destroy 等价层。
• AppFlow::_exit_tree / GameScene::_exit_tree / GDExtension terminator
  • 在整个客户端退出时清空模型纹理、动作片段、NPC 模型规格、UI 纹理和音频流/播放缓存，补齐 CPythonApplication::Destroy 的进程级资源释放边界。

Field-level findings

• 40250 的 SetLoadingPhase 先运行旧 phase leave callback，再把网络阶段切到 Loading，随后依次执行 CPythonPlayer::Clear、CFlyingManager::DeleteAllInstances、CEffectManager::DeleteAllInstances 和 __DirectEnterMode_Initialize。当前 classic warp 在 M2Client::pump_classic 中先直接 EntityStore::reset_for_map_change()，再同步发 world_reset/warp，最后才替换 socket/stage；网络阶段没有独立的 Loading owner，顺序只能算近似。
• 当前 EntityStore::reset_for_map_change 会清实体、变化队列、目标、飞行 cue、effect cue、掉落、PVP、观察者、技能、快捷栏、冷却和 points 基线；这是数据层完整清理，但它把 pending change 直接丢弃，不产生参考端 manager 的显式删除事件，场景层必须依赖 world_reset 同步清理。
• GameScene::_on_world_reset 再清 NetPlay、NetWorld、GroundItems、临时窗口、UI top stack 和 BGM；信号连接是同步调用，但 queue_free 本身延迟到 frame 末，因此旧节点可能在清理回调后短时间仍存在。
• NetWorld.clear_for_map_change 现在除遍历 _by_vid 外，还会清 _upgrade_queue、_chat_tails、target/hover VID，并解绑 target effect；但模型升级、HP 条和 queue_free 延迟回调仍没有统一 generation，未在 _by_vid 的其他附属节点仍依赖各组件自己的 guard。
• M2Client::disconnect_from_server 现在先对活动 ClassicSession/NetClient 的 EntityStore 做 reset_for_map_change()，再发出 world_reset，最后释放 transport；这对齐 40250 离线阶段先清 phase owner、后清网络对象的边界。真实断线由 session 失败事件驱动的重连顺序仍需独立包级证明。
• GameScene._exit_tree 在卸载 native world 前调用 Audio.shutdown()，同步停止 BGM/3D 播放器并清空 MP3/MSS stream cache；这补齐了 CSoundManager::Destroy 的所有权边界，避免场景节点销毁后音频资源继续存活。
• 已修正 screen_hp_bar_test 对死亡后旧 HP 控件的错误访问：40250 的 Die/DetachTextTail 语义是移除旧尾标，回归现在检查控件从 world registry 移除，并通过 entity_info 验证重新进入可见性路径；rendering_scenario_test failures=0 但退出码 139，仍存在退出阶段资源/对象释放风险。

Deep audit round 2026-09-20

本轮继续沿 40250 的 Loading、断线和 Destroy 路径做了静态复核，并重新执行清理相关回归：

• 40250 的 SetLoadingPhase() 通过 phase leave callback 先退出旧阶段，再由同一个网络阶段 owner 依次清 CPythonPlayer、飞行实例、特效实例和 direct-enter 状态；SetOffLinePhase() 也会重置主 Actor、选人和 direct-enter 状态。当前 M2Client::pump_classic() 仅在 GC_WARP 分支发 world_reset，而 M2Client::disconnect_from_server() 只销毁 session/stream 和回到 Idle，不发 world_reset。因此保留 GameScene 的断线重连分支不能依赖网络对象析构完成旧场景清理。
• 当前 EntityStore::reset_for_map_change()、NetPlay.clear_for_map_change()、GameScene._on_world_reset()、NetWorld.clear_for_map_change() 和 FlyObject.clear_for_map_change() 的幂等性主要来自各自清空容器；它们没有统一的 reset generation。_upgrade_queue、目标特效、模型升级回调、HP 条和 queue_free 延迟回调仍由各节点分别判断，旧回调回灌到新地图的安全性没有证明。
• GameScene._exit_tree() 现在显式调用当前 world 的 unload_map()；AppFlow._exit_tree 和渲染回归退出前还会清空模型纹理、动作片段、NPC 规格和 UI 纹理缓存。此前的 rendering_scenario_test.gd 退出码 139/54 个 ObjectDB 泄漏在该清理链补齐后已变为干净退出码 0。fly_reset_test.gd 中由 FlyInstance.handler 自捕获形成的 5 个 RefCounted 环也已解除；当前仍有 test_exp_fly_parity.gd 旧式 fixture 的 3 个退出警告，属于测试 harness 清理问题。dungeon_state_test.gd、bgm_test.gd 和 net_entity_test 通过，只能证明局部清理。

本轮结论：核心实体、飞行物和临时状态有清理实现，但断线重连、统一 generation、同步/延迟释放边界、旧新地图共存和进程退出安全仍未达到 40250 的统一生命周期语义，合同保持 PARTIAL。

Implementation fix round 2026-09-22T06:45Z

本轮按 CPythonNetworkStream::SetLoadingPhase 的 manager 清理边界，先为 NetWorld 增加失败回归 project/net_world_reset_test.gd。修复前该回归稳定复现三项残留：换图后 _upgrade_queue 仍保留旧 VID，_chat_tails 仍保留旧文本，target/hover VID 仍指向已删除 Actor。随后在 NetWorld.clear_for_map_change 中按 Loading 清理顺序解绑 target effect、清空模型升级队列和聊天尾标，并归零 target/hover 引用。

同时修正 screen_hp_bar_test.gd：死亡会销毁/移除旧 HP 条，不再访问已 queue_free 的旧 Control；复活/位置变化通过 entity_info 重新建立 presentation state 后检查镜头后的隐藏行为。修复后两个回归均干净退出且无 previously freed 输出。

本轮仍未补齐统一 reset generation、真实断线重连的完整包序、通用 EffectManager 和跨中断矩阵，因此合同保持 PARTIAL。

Implementation fix round 2026-09-22T07:10Z

本轮继续追踪 rendering_scenario_test 的退出阶段差异。按 40250 CMapManager::UnloadMap / CPythonApplication::Destroy 的显式所有权顺序，修改 GameScene._reload_map_for_warp：旧 world 先调用 unload_map()、再排队释放，之后才创建新 world；新增 GameScene._exit_tree，在场景被直接释放时显式卸载当前 world。回归测试清理也改为先发 world_reset、卸载 native map，再在 frame boundary 由 SceneTree 释放节点。

该修复闭合了“新地图先构造、旧地图延迟清理”的静态顺序差异，但 rendering_scenario_test 修复后仍为 failures=0、退出码 139，并报告 54 个 ObjectDB 泄漏。因此 native model/resource 的最终释放、通用 EffectManager 和退出崩溃仍保持 PARTIAL，不能把渲染场景记为 PASS。

Implementation fix round 2026-09-22T07:40Z

本轮继续追踪 139/泄漏的真实 owner。Metin2Model、Metin2AnimPlayer、MobView 和 UiAssets 都持有跨场景缓存；此前只卸载 world/节点不会释放这些进程级资源。按 40250 CPythonApplication::Destroy 的 manager 释放边界，新增 AppFlow._exit_tree 的模型纹理、动作片段、NPC 规格和 UI 纹理清理，并在真实资源渲染回归中按 world_reset -> unload_map -> queue_free -> frame boundary -> cache clear 执行退出。

修复前回归为 failures=0、退出码 139、54 个 ObjectDB 泄漏；修复后 rendering_scenario_test 为退出码 0，且不再打印 ObjectDB 泄漏。GDExtension terminator 也补充了 Metin2Model::clear_texture_cache，防止未经过 AppFlow 的宿主退出遗漏该 cache。随后按 CFlyingManager::DeleteAllInstances 的同步删除边界，FlyObject 在地图清理和自然过期时解除 handler、target、world、data 引用，fly_reset_test 的 5 个 ObjectDB 泄漏已清零；统一 reset generation、断线显式 world_reset 和通用 EffectManager 仍未闭合，合同保持 PARTIAL。

Implementation fix round 2026-09-22T07:55Z

复核 CFlyingManager::DeleteAllInstances 时发现，当前 FlyInstance.handler 闭包捕获实例自身，而实例又持有该 Callable；只清理实例数组不能打破这个 RefCounted 环。新增 _release_instance()，在地图清理和自然过期两个删除路径中同步解除 handler、target、world、data 引用，并同步释放弹道/爆点视觉节点，保持 Loading 边界的确定性。

修复前 fly_reset_test.gd 行为断言通过但退出报告 5 个 ObjectDB 泄漏；修复后退出码 0 且无 ObjectDB 泄漏。test_exp_fly_parity.gd 的 6/6 行为断言仍通过，但旧式单函数 fixture 仍报告 3 个 ObjectDB/不在 SceneTree 的路径警告，单独记为 harness 待清理，不提升整个飞行合同状态。

Implementation fix round 2026-09-22T08:35Z

在 Debug 原生库重新跑真实资源渲染回归时，断言虽为 0 且退出码为 0，但退出仍报告 2 个 ObjectDB：AudioStreamMP3 和 AudioStreamPlaybackMP3。按 40250 CSoundManager::Destroy，新增 Audio.shutdown()，停止 BGM/3D 播放器、解除 player stream，并清空 _cache/_mss_cache；GameScene._exit_tree() 在 world unload 前调用该 shutdown。

修复后 Debug 渲染回归不再报告 ObjectDB 泄漏；这次也确认了 Release/Debug 原生库必须分别重建和验证。通用特效 manager、统一 reset generation、真实断线/GC_WARP 包序仍保持 PARTIAL。

Branch matrix

场景	40250	当前端	结论
GC_WARP / 进入 Loading	先切 Loading，再按固定顺序清理 Player、飞行物、特效和 Actor	world_reset 清理网络/场景状态，之后处理 warp；飞行物与效果队列已补齐	PARTIAL：顺序仍缺包级证明
同服换坐标	不重建地图，但 Loading/Actor 清理仍由阶段处理	_place_player_at_net_pos 复位主角位置，world_reset 仍清理实体	PARTIAL
跨服/跨图	旧地图 Leave/Clear 后加载新地图并 Enter	旧 world 先 unload_map/queue_free，再构造新 world	STATIC FIXED；渲染退出缓存已补齐
旧弹道/爆点	DeleteAllInstances，不能跨 Loading 回调	已在网络层、NetWorld 和 FlyObject 清理弹道/爆点，并解除实例自捕获 handler	MAPPED + regression
旧模型升级/聊天/目标呈现	Loading 时随 Actor/文本尾标/目标效果一起清理	_upgrade_queue、_chat_tails、target/hover VID 和 target effect 在 clear_for_map_change 中清理	FIXED + regression
旧特效/临时窗口	EffectManager 和 transient UI 在 Loading 清理	场景清理临时窗口并关闭 top stack；通用特效 manager 仍未统一	PARTIAL
退出/窗口关闭	Destroy 显式释放所有 manager	AppFlow/GDExtension/Audio/GameScene 退出清缓存；显式 disconnect 先 reset world 再释放 transport，完整 close consumer 尚未闭环	PARTIAL

Equivalence matrix

项目	状态	证据
Preconditions	MAPPED	world reset 仅在已建立 GameScene 的 warp/loading 路径调用
Branch structure	PARTIAL	同服、跨图、断线、窗口关闭和死亡分支尚未全部覆盖
Algorithms/formulas	MAPPED	清理本身无复杂公式；地图坐标转换仍使用当前 MapCoord 适配
State transition order	PARTIAL	参考端 Loading 是单一阶段 owner，当前由 session、M2Client、GameScene 和信号协作
Constants/units	MAPPED	飞行/地图数据单位已在各自组件中转换；没有证明所有资源释放计时一致
Timing/event sources	PARTIAL	Godot queue_free 是延迟释放，参考端 manager 删除是同步调用；本轮仅证明旧 presentation state 不回灌
Resource/data sources	PARTIAL	当前 world 使用 Godot child/RAII，参考端使用显式 manager ownership
Protocol side effects	PARTIAL	GC_WARP、重连、close 与 world reset 的组合顺序仍缺完整 fixture
Interruption/failure/cleanup	PARTIAL	异步 map load 失败、重复 warp、旧 session 竞态和 close cleanup 尚未证明

Regression evidence

• extension/tests/net_entity_test.cpp：map reset 丢弃实体、地面、目标、飞行、飞行目标和特效队列。
• project/fly_reset_test.gd：活动弹道、弹道视觉和爆点视觉在 map reset 后全部消失。
• project/screen_hp_bar_test.gd：实体/HP 条的 map reset 清理。
• project/net_world_reset_test.gd：模型升级队列、聊天尾标、target/hover 引用和 live actor 的 Loading 清理；修复前失败 3 项，修复后通过。
• project/dungeon_state_test.gd：world reset 清理地下城目标/到达状态，通过。
• project/bgm_test.gd：world reset 后 BGM 选曲/音量状态，通过。
• project/gamescene_test.gd：场景和动作/实体清理，通过。
• project/screen_hp_bar_test.gd：修复死亡后访问已释放旧控件的问题，当前干净通过。
• project/rendering_scenario_test.gd：修复前报告 failures=0、进程退出码 139、54 个 ObjectDB 泄漏；修复后退出码 0 且无 ObjectDB 泄漏，可作为退出资源清理回归证据。
• project/fly_reset_test.gd：修复前退出报告 5 个 ObjectDB 泄漏；解除 FlyInstance handler 自捕获环后退出干净。
• project/rendering_scenario_test.gd：Debug 原生库下音频清理前报告 2 个 AudioStreamMP3/AudioStreamPlaybackMP3 泄漏；接入 Audio.shutdown() 后退出干净。

Status

PARTIAL。本轮已修复明确的跨图 presentation 残留、旧地图卸载顺序和渲染场景进程级缓存泄漏，但统一 reset generation、通用特效 manager、断线重连和完整中断矩阵仍需继续审计。