mtgodot-poc/audit/contracts/world.map-load-transition.md

world.map_load_transition

Scope

审计 40250 地图 Leave/Clear/Load/Enter、玩家坐标驱动的区域加载、terrain/property/object/environment 初始化、区域卸载，以及当前 Metin2World 和 GameScene 的换图、失败和恢复行为。目标是比较可观察的生命周期与资源/碰撞边界，不要求 Godot 复制 DirectX 线程实现。

Reference implementation and evidence

• ../40250/Server Client TMP4/ClientVS22/source/GameLib/MapManager.cpp
  • LoadMap 先调用当前 CMapOutdoor::Leave()，设置 map name、LoadProperty()，按地图类型加载；户外地图 Load(x,y,z) 成功后注册/设置 environment，最后 Enter()。
  • UnloadMap 校验当前 map name 后 Clear()；不匹配时失败，不清理另一张地图。
  • UpdateMap 把玩家位置交给 CMapOutdoor::Update，触发区域/terrain 窗口更新。
• ../40250/Server Client TMP4/ClientVS22/source/GameLib/MapOutdoorLoad.cpp
  • CMapOutdoor::Load 先 Destroy，读取 Setting.txt，建立 terrain patch/quadtree/water/shadow，调用 Update(x,y,z)，再确定本地或 d:/ymir work/environment/ 的 .msenv 路径。
  • LoadTerrain 要求 AreaProperty.txt 的脚本类型和字段，按区域加载 water/height/attr/tile/shadow/minimap，并生成 ready terrain。
  • LoadArea 按区域目录加载 object/area 数据；请求重复区域时不重复创建。
• ../40250/Server Client TMP4/ClientVS22/source/GameLib/MapOutdoorUpdate.cpp
  • 首次或跨 LOAD_SIZE_WIDTH 窗口时加载周边 terrain/area；AssignTerrainPtr 绑定 3×3 指针窗口；移动时更新 terrain patch、area 和延迟垃圾回收。
  • 区域离开窗口后先放入 delete vector，按回收间隔销毁，不是瞬间删除所有资源。
• ../40250/Server Client TMP4/ClientVS22/source/GameLib/AreaLoaderThread.cpp
  • terrain/area 请求进入线程安全队列，由 loader thread 读取资源，主线程 Fetch 后再接入地图；请求队列和 shutdown 有独立生命周期。

Current implementation and evidence

• extension/src/metin2_world.cpp
  • load_map 一开始 unload_map()，解析 setting.txt、建立 AssetResolver/Property registry、按 load_radius 构建 chunk、解析 .msenv；失败时保留 setting_ok=false 并返回 false。
  • load_radius < 0 时同步构建整图；否则先 stream_update()，再在 load_map 内把整个队列同步建完，之后 _process 才按 stream_budget 增量构建新 focus 范围。
  • stream_update 以方形 tile 半径加载/卸载 chunk，卸载立即从 vector 移除并 queue_free root；没有 40250 的 terrain/area delete vector 与延迟垃圾回收语义。
  • unload_map 清空 chunk/队列/ambience、queue_free objects/environment，重置统计和错误状态；没有 load generation/token 防止旧异步结果回灌。
• project/game_scene.gd
  • 初次 setup 先解析 map path、创建 fallback lighting，再显式 _build_world，地图失败只 warning 并继续平地运行。
  • _on_world_reset 清理 NetPlay、NetWorld、掉落物、临时 UI 和 BGM；之后等待/接收 warp，再由 _reload_map_for_warp 创建新 world。
  • _reload_map_for_warp 先保存 old_world，调用 _build_world 完整加载新 world，之后才对旧 world queue_free；旧 world 在新 world 失败时也可能仍作为有效场景引用存在。
  • 同图 warp 仅放置本地主角；跨图 warp 才重建 world。地图切换后重新绑定 camera/player/net_world/HUD/atlas，但网络实体刷新与 world 加载之间没有原版 Enter 阶段契约。
• project/net_play.gd / project/net_world.gd
  • world reset 清除当前 Actor、移动/战斗/投射物/临时 UI 生命周期；场景层通过 queue_free 延迟删除节点。
  • reset 前后没有与 Metin2World 共用的 generation；旧网络包或旧模型回调如果晚于新 world，依赖各模块自己的 guard。

Reference-to-current call chain

40250	当前端
CMapManager::LoadMap -> Leave -> LoadProperty -> CMapOutdoor::Load -> Register/SetEnvironment -> Enter	GameScene::_reload_map_for_warp -> _build_world -> Metin2World::load_map -> _place_player_at_net_pos
CMapOutdoor::Load(x,y,z) -> Update -> terrain/area 3×3 window	load_map -> load_radius 方形 chunk queue；首轮队列在 load_map 内同步建完
Update -> AssignTerrainPtr -> UpdateTerrain/UpdateAreaList -> 延迟垃圾回收	set_focus_position -> stream_update -> _process build/unload；unload 立即 queue_free
UnloadMap(name) 校验 name -> Clear -> map resources reset	unload_map 无 map-name 校验，直接清当前 world
loader thread 请求/Fetch/Shutdown	stream_queue 在主线程逐帧处理，没有独立异步加载线程或旧请求取消 token

Branch matrix

场景	40250 行为	当前端行为	结论
首次加载	读取 Setting/Property，按玩家坐标加载周边 terrain/area，设置 environment 后 Enter	读取 setting/registry，按 load radius 建 chunk，再建 .msenv/fallback	PARTIAL：资源阶段接近，入口/ready 语义不同
同图 warp	保持当前 map，更新背景位置并更新区域窗口；Loading 阶段同步 Actor/临时对象清理	只放置主角；网络 reset 由前置 world_reset 处理	PARTIAL：地图与网络阶段未形成同一状态机
跨图 warp	旧 map Leave/Clear 后再 Load 新 map，旧资源不与新 map 长时间共存	新 world Load 成功后才 queue_free 旧 world	GAP：存在双 world/双环境/资源峰值和旧引用窗口
Setting 缺失/格式错误	LoadSetting/Load 失败；MapManager 返回 false，调用方决定是否进入下一阶段	load_map 返回 false，GameScene warning 后继续平地	PARTIAL：失败可见性和后续网络行为不等价
TextureSet/区域文件缺失	记录失败并影响 terrain/area ready；周边窗口仍有明确失败状态	chunk 可单独失败并继续；缺失对象以统计项/空节点容忍	ADAPTATION/PARTIAL：需要证明角色、碰撞和可见性边界一致
environment 缺失	仍通过 environment data name/注册流程；设置失败由原版环境 API报告	.msenv 失败后 fallback lighting；跨图可能保留旧 _sun/_env	PARTIAL：旧环境释放和失败回滚未闭合
streaming 进入新 tile	3×3 指针窗口、请求新 terrain/area、旧区域进 delete vector	以方形 radius 立即卸载并重新入队，stream_budget 逐帧构建	PARTIAL：窗口公式相近，时序/回收不同
重复 warp / 中断加载	map manager 当前状态和 loader queue 有明确销毁/重建边界	无显式 warp generation；新旧 _build_world 和 delayed queue_free 可交错	PARTIAL
map name 不匹配卸载	拒绝卸载并保留当前 map	world 实例无 map-name 校验，直接清理	GAP

Equivalence matrix

项目	状态	证据/缺口
Preconditions	PARTIAL	path/assets/setting 检查已存在；Unload 的 map-name 校验和 ready gate 不同
Branch structure	PARTIAL	同图/跨图、失败、重复 warp、缺 environment 和中断加载尚未用同一状态 fixture 覆盖
Algorithms/formulas	PARTIAL	cm/m 坐标、base position、chunk tile 和 height/attr 查询已有转换；区域窗口与 LOAD_SIZE_WIDTH 的精确边界尚未逐格证明
State transition order	GAP/PARTIAL	40250 Leave -> Load -> Environment -> Enter；当前新旧 world 共存且旧 world 后释放
Constants/units	PARTIAL	CHUNK_CM、CM_TO_M、map base、focus tile、load radius 与原版 terrain/cell/patch 常量需要 fixture
Timing/event sources	PARTIAL	参考端 loader thread + manager update；当前 Godot _process budget，异步回调/旧请求取消未等价
Resource/data sources	MAPPED	setting、property、textureset、height/attr/water/tile/shadow、object、environment 的源文件均已定位
Protocol side effects	PARTIAL	GC_WARP/world_reset/主角放置已接线，但 map ready、Actor burst 和 Enter 的相对时序未闭环
Interruption/failure/cleanup	PARTIAL	queue_free、fallback、重复 warp、旧 world 引用、stream queue 和失败重试缺少完整证据

Required tests

• 同图 warp：不创建第二个 World，清理 Actor/掉落物/飞行物/临时 UI 后主角和 focus tile 位置正确。
• 跨图 warp：记录 Leave/reset/build/Enter 的事件顺序，断言旧 world 不与新 world 长时间共存，且失败时旧 world 保留策略明确。
• 缺失/格式错误的 setting、textureset、terrain/area、object、.msenv；区分 hard failure、fallback 和可继续运行的缺失资源。
• 重复 warp、快速连续 warp、加载中再次 reset、旧 world queue_free 尚未执行时收到旧实体/模型回调。
• focus tile 边界逐格验证：load/unload 集合、height/attr/water/collision、对象/树/ambience 和实体可见性保持一致。
• 加载成功后的 map-ready/主角放置/GC_MAIN_CHARACTER 顺序，以及失败后重试同图和跨图的状态复位。

Test evidence

• project/gamescene_test.gd：通过，验证缺图 fallback、GameScene 装配、主角定位、world reset 和实体镜像；它不证明 40250 的 Leave/Enter 顺序。
• project/p9_test.gd：通过，验证小地图、昼夜、天气和 warp signal 接收；它不创建真实 world transition。
• project/forest_map_render_test.gd：这是由 script/forest_map_render_test.sh/客户端主循环启动的 Node 脚本，不能用 godot --headless --script 直接当 SceneTree 测试；本轮直接启动会被 Godot 拒绝，故不得计为通过。

Deep audit round 2026-09-20

本轮对 MapManager::LoadMap/UnloadMap/UpdateMap 与 Metin2World::load_map/stream_update/_process/unload_map 做了实现级复核：

1. 40250 的 LoadMap 顺序是当前 map Leave → 设置 map name/加载 Property → CMapOutdoor::Load(x,y,z) → 注册并设置环境 → Enter；当前 load_map() 先无条件 unload_map()，然后同步解析 setting/AssetResolver/Property，再按半径把整个 stream_queue 建完，最后才解析 .msenv。因此当前没有 reference 的 Leave/Enter/ready 边界，且 streaming 初始加载并非真正逐帧。
2. 当前 stream_update() 立即 queue_free 半径外 chunk，并清空再重建待加载队列；40250 Update 通过 3×3 terrain/area 指针窗口和 delete vector 延迟回收。当前在 focus tile 边界快速往返时，旧 chunk 的节点仍可能处于 Godot queue_free 期，同时新 chunk 已入队，资源/碰撞峰值和事件时序不同。
3. 40250 UnloadMap(name) 会校验传入 map name，不匹配时拒绝清理；当前 Metin2World::unload_map() 无 map-name 参数，任何调用都直接清空当前 world。GameScene 的 _reload_map_for_warp() 还会先创建新 world，成功后才对 old world queue_free，形成短暂双 world/双碰撞/双环境窗口。
4. setting 缺失时当前 load_map() 返回 false，但 GameScene::_build_world() 将其降级为 warning 并继续平地运行；这与 40250 LoadMap 失败后由 phase/调用方决定是否继续不同。.msenv 解析失败也使用 fallback lighting，旧 _sun/_env 的释放与新地图失败回滚没有统一 generation/owner。
5. 当前 Metin2World 没有 loader thread/Fetch/Shutdown 对应的请求 token；stream_queue 是主线程 vector。换图或快速 reset 后没有 generation 防止旧队列/旧模型回调回灌新 world，网络 world_reset 的 generation 与 Metin2World 也未共享。

本轮测试结果：gamescene_test.gd、p9_test.gd、environment_test.gd 通过；测试只证明当前场景装配、warp signal 和 .msenv parser 可以运行，不能证明 Leave/Enter、map-name 校验、延迟回收、双 world 窗口或中断加载与 40250 一致。

Active GameLib map-support review

• GameLib/MapBase.cpp 的 Clear/Enter/Leave/SetEnvironmentDataPtr/ResetEnvironmentDataPtr 是地图基类边界；MapType.cpp/MapUtil.cpp 负责 MapProperty、.msenv 的 fog/filter/skybox/lensflare/ambience/dungeon block 解析和插值 helper；AreaLoaderThread.h 描述区域加载线程的 Create/Setup/Destroy 生命周期。
• GameLib/Property.cpp/PropertyLoader.cpp/PropertyManager.cpp 以 pack-backed property、CRC、reserve、注册/替换/删除/清理为地图对象、树、建筑、效果、环境和 dungeon block 提供权威配置；当前 PropertyRegistry/AssetResolver 只做部分文本/路径适配。
• GameLib/MapOutdoor.h/MapManager.h/MapBase.h、GameType/Interface 和 terrain patch/quad 文件的静态核对确认当前 Metin2World 的方形 chunk 队列不是完整 CMapOutdoor::Update/loader-thread/延迟回收链；地图合同继续为 PARTIAL。

Active UserInterface background bridge review

• PythonBackground.h/PythonBackgroundModule.cpp 暴露地图 Load/Destroy/Warp、environment register/get、terrain/object picking、height、shadow level/texture、visible part、splat/view distance、guild area、target/special effect 和 dungeon map name。
• 当前 Metin2World/GameScene 已有 map load、height/attr/water、environment 和目标效果入口，但没有同一套 background bridge 的 environment index、shadow/splat/view-distance/guild-area/特殊效果清理契约；CameraProcedure.cpp 还会通过 terrain-only ray 做多方向相机碰撞调整。
• 本轮完成 Background/CameraProcedure 静态核对，地图合同继续为 PARTIAL，相机碰撞差异同时保留在点击/输入合同中。

Status

PARTIAL。本轮完成了 40250 与当前端地图生命周期、区域窗口、资源释放和失败分支的逐文件审计；发现跨图双 World、失败 fallback、Unload 校验、区域回收和异步中断边界尚未等价。现有回归通过只说明当前路径可运行，不能标记为已修复或 EQUIVALENT。