mtgodot-poc/audit/contracts/world.terrain-water-collision.md

# world.terrain-water-collision

## Scope

比较 40250 的户外地图高度、对象高度、属性阻挡、水面层、地形/对象拾取射线、桥梁和地面贴合调用链；同时核对加载失败、区块边界、地图切换、资源清理以及水面动画时序。

## Reference call chain

- `GameLib/MapOutdoor.cpp::GetTerrainHeight` / `GetHeight`
  - 以 200cm `CELLSCALE` 在 `height.raw` 的 131×131 样本上按 TL-BR 对角线做三角插值。
  - `GetHeight` 在非 terrain-only 模式下通过 culling 的 `CAttributeInstance::GetHeight` 合并桥梁、楼梯和平台等 `.mdatr` 对象高度，取对象/地形最大值。
- `GameLib/AreaTerrain.cpp::CTerrain::GetHeight`
  - 使用 `HeightScale`、跨区块边界高度样本和固定的左/右三角分支；地图外返回 0。
- `GameLib/MapOutdoor.cpp::isAttrOn` / `GetAttr` / `CMapManager::isPhysicalCollision`
  - 世界厘米坐标转换为 100cm 属性格；bit flag 使用按位判断，16 以上的属性值使用高半字节相等规则。
  - `isPhysicalCollision` 只判断 `ATTRIBUTE_BLOCK`，并把 Metin2 的 Y 取反后交给地图属性查询。
- `PRTerrainLib/Terrain.cpp::LoadWaterMapFile` / `GameLib/AreaTerrain.cpp::GetWaterHeight`
  - 读取 magic=5426、128×128 水区块、layer count 和 u16/u32 水高；水 id 映射到具体层高，错误加载会清空水图并返回失败。
  - `MapOutdoorWater.cpp` 按水深计算顶点 alpha，并以 70ms/帧循环 30 张水纹理；水面共享 0 到 -15cm 的 1000~3000ms 高度扰动。
- `GameLib/MapOutdoor.cpp::GetPickingPointWithRay`
  - 先在 culling 对象上做 `CAttributeInstance::Picking`，再以 5/10/100cm 自适应步长和 5000/10000/100000cm 上限探测地形，返回离射线起点更近的对象或地形命中。
- `EterLib/AttributeInstance.cpp::GetHeight` / `Picking`
  - 对 `.mdatr` 高度三角形做 2D 包围盒、三角形和法向求交；对象命中包含可拾取的静态桥梁/平台，而不是只有网络角色。

## Current call chain

- `formats/terrain_files.cpp::load_height_map` / `load_attr_map` / `load_water_map`
  - 读取 `height.raw`、`attr.atr` 和 `water.wtr`，验证尺寸、magic、数据长度并支持 u16/u32 水高。
- `formats/terrain_mesh.cpp::terrain_height_at` / `build_terrain_mesh`
  - 已按 200cm 格、TL-BR 三角形和 `HeightScale` 生成 Godot 高度网格；`Metin2World::sample_height` 对已加载区块插值。
- `extension/src/metin2_world.cpp::build_chunk`
  - 为每区块建立地形 Mesh/HeightMapShape3D、属性对象 `.mdatr` 碰撞体、对象高度三角形和水面 Mesh；区块根节点统一卸载。
- `extension/src/metin2_world.cpp::sample_height`
  - 合并裸地形和已加载对象 `.mdatr` 高度，桥梁/平台命中时取更高表面；边界支持邻接区块的已加载对象查询。
- `extension/src/metin2_world.cpp::sample_attribute` / `is_blocked`
  - 读取 100cm 属性格；当前调用方主要使用 `ATTRIBUTE_BLOCK` 和 `ATTRIBUTE_WATER` 的 bit0/bit1。
- `extension/src/water_builder.cpp::build_chunk_water` / `water_depth.h` / `water_motion.h`
  - 每个水格保留四角深度 alpha，使用 400×HeightScale 的透明度公式、30 帧 shader 和共享高度扰动。
- `project/player_controller.gd::_ray_ground`
  - 通过每 1m 采样加二分寻找 `sample_height` 地表；实体点击单独使用网络实体 AABB/胶囊近似。
- `project/net_world.gd::_ground_world` / `_blocked` / `_pushed_position`
  - 网络实体和主角贴 `sample_height`；移动/击退通过 `is_blocked` 截断。

## Audit findings (2026-09-20)

### 已对齐的部分

- `terrain_height_at` 的厘米单位、200cm 格、TL-BR 对角线、`xdist <= ydist` 三角分支和 `HeightScale` 已与 `CTerrain::GetHeight` 对齐；真实 A1/C1 桥面测试证明 `.mdatr` 高度会优先于河床。
- `attr.atr` 的 2634 magic、256×256 数据、100cm 属性格和 bit0 阻挡/bit1 水面查询已有实现；移动、击退和钓鱼入口都使用同一属性读取路径。
- `water.wtr` 的 5426 magic、128×128 id、layer count、u16/u32 高度兼容和失败尺寸检查已有实现；水面四角深度、浅滩透明度、动画纹理与共享高度扰动已有回归。
- 桥梁、平台等 `.mdatr` 高度三角形已进入 `sample_height`，区块卸载由根节点统一回收；A1/C1 全地图高度探针未发现桥面掉到河床的回归。

### 材料差异

- 40250 的 `GetPickingPointWithRay` 同时比较静态对象 `CAttributeInstance::Picking` 和地形，并采用 5/10/100cm 自适应步长；当前 `PlayerController::_ray_ground` 只比较 `sample_height`，静态建筑/桥梁的射线命中没有进入点击结果。网络实体点击也只是节点 AABB/胶囊近似，尚未复用统一的世界拾取合同。
- 40250 暴露 `GetWaterHeight(int,int)`，钓鱼抛竿会把 600cm 目标点的 Z 设置为具体水层高；当前端 `get_fishing_rotation` 只验证 `ATTRIBUTE_WATER`，`_new_fishing` 没有读取水层高来生成等价的鱼钩目标位置。水面可见且钓鱼方向可判定，不代表抛竿位置已等价。
- `CTerrain::isAttrOn` 对 `byAttr >= 16` 使用高半字节相等规则；当前 `sample_attribute` 只返回原始字节、`is_blocked` 只支持 bit0，尚没有通用的 `is_attr_on` 兼容接口，因此 `BANPK` 以外的高半字节调用方缺少等价证据。
- 40250 的 `GetHeight` 会根据 `m_bEnableTerrainOnlyForHeight` 选择是否合并 culling 对象，并且对象高度查询、地形加载状态、地图坐标边界有明确返回分支；当前 `sample_height` 依赖区块已被实际加载以及 `objects_enabled/registry_ok`，资源未加载或 streaming 队列中时会暂时回退为裸地形，缺少“查询触发加载/延迟重试”的同等状态契约。
- Godot `HeightMapShape3D`/`.mdatr` 碰撞体和逻辑 `is_blocked` 是两套并行碰撞来源；当前角色移动主要走属性逻辑，静态对象物理体主要服务射线/弹道，尚没有证明两者在斜坡、对象边缘、跨区块和卸载帧的结果与 40250 `isPhysicalCollision`/`CAttributeInstance` 顺序一致。
- 当前水面视觉测试覆盖 geometry/material 和真实 A1 水深，但没有验证 `water id -> layer height -> fishing target Z` 的运行时链，也没有覆盖缺失水图后水状态清零、边界水格和地图切换期间 shader/motion 状态的完整清理矩阵。
- `TerrainDecal` 的高度贴花三角选择、`MapOutdoor` 的 normal/shadow/visibility 依赖和当前地形 patch 视锥剔除尚未形成可执行的功能合同；它们不阻塞当前移动主链，但不能因地形网格测试通过而宣称渲染/拾取完全一致。

## Equivalence matrix

| 项目 | 状态 | 备注 |
|---|---|---|
| Preconditions | PARTIAL | 资源尺寸/magic/区块加载已有检查；对象拾取、水层目标、高半字节属性和 streaming 未闭合 |
| Branch structure | PARTIAL | 高度、属性、水面主分支已映射；对象/地形射线选择、地图外、延迟加载和水失败分支未全等价 |
| Algorithms/formulas | PARTIAL | 高度插值、桥面取高、水深 alpha 已对齐；拾取步长、对象 picking 和水高接口不同 |
| State transition order | PARTIAL | 区块构建→地形/碰撞/水面→对象高度基本一致；加载队列、点击命中优先级、钓鱼目标 Z 顺序未闭合 |
| Constants/units | PARTIAL | 200cm terrain cell、100cm attr cell、600cm fishing probe、水深/动画常量已记录；射线 5/10/100cm 与当前 1m 采样不同 |
| Timing/event sources | PARTIAL | 水纹 70ms 和扰动时序已有实现；streaming、地图卸载、拾取/钓鱼事件的端到端时序证据不足 |
| Resource/data sources | PARTIAL | height/attr/water/mdatr 可读取；对象 culling、water layer 查询、terrain normal/decal/shadow 统一资源入口未完成 |
| Protocol side effects | PARTIAL | 属性阻挡/钓鱼方向会影响移动和发包；水层高度未进入抛竿副作用，静态对象点击也未统一 |
| Interruption/failure/cleanup | PARTIAL | 区块根节点卸载和基本加载失败已有路径；水状态、待处理拾取、streaming 中断和地图切换边界仍缺完整矩阵 |

## Regression evidence

- `build/formats/formats_map_test`：高度插值、地形网格、地图格式和资源边界；当前无 `M2_ASSETS` 时跳过 live A1 断言。
- `project/test_bridge_height_parity.gd`：真实 A1 两座桥的 `.mdatr` 桥面高度、河床回退和跨度采样。
- `project/test_all_map_height_probe.gd`：A1/C1 真实地图桥面高度、地形回退、属性阻挡和跨跨度采样。
- `project/water_reference_test.gd`：真实 A1 水格、四角深度 alpha、浅滩和水材质/动画结构。
- `project/fishing_water_test.gd`：真实 A1 `ATTRIBUTE_WATER`、600cm 方向扫描和地图外拒绝。
- `project/test_click_target_effect_parity.gd`：地面命中信号、网络实体点选和静态弹道障碍；该测试的地面段使用 mock world，不能替代 40250 静态对象 ray picking。
- `project/player_move_test.gd`、`project/test_skill_ground_fix.gd`：移动阻挡和角色/技能贴地回归。

## Deep audit round 2026-09-21

### Fresh regression results

- `test_bridge_height_parity.gd`、`test_all_map_height_probe.gd`、`water_reference_test.gd`、`fishing_water_test.gd`、`player_move_test.gd`、`test_skill_ground_fix.gd` 的断言均通过；A1 水面为 `failures=0`，15 pieces、212587 vertices。
- `test_click_target_effect_parity.gd` 断言通过，但进程报告 3 个 ObjectDB 和 1 个资源未释放；`fly_target_bounds_test.gd` 断言通过但 exit 139，并泄漏 48 个 ObjectDB。
- `formats_map_test`、`net_bounds_test`、`net_entity_test`、`net_classic_session_test`、`net_classic_wire_test` 均退出码 0；formats live A1 断言因未设置 `M2_ASSETS` 跳过。

### Static parity conclusion

- 高度插值、桥面取高、属性 bit0/bit1、水图读取和局部水面渲染结构继续与参考接近；这部分测试不能证明完整拾取/碰撞等价。
- 当前 `_ray_ground` 主要走 1m 采样的 `sample_height`，没有实现 40250 对静态 `.mdatr` 对象先做 `Picking`、再以 5/10/100cm 自适应步长比较对象与地形命中的统一射线链。
- 水面方向检测尚未把 `water id -> layer height -> fishing target Z` 接入抛竿副作用；高半字节属性规则、streaming 中延迟重试和对象/地形双碰撞源也未闭合。
- 点击/飞行和真实地图测试的泄漏/exit 139 表明跨图、区块卸载和特效/目标清理仍不能视为稳定等价。

### Active GameLib/PRTerrainLib terrain-core review

- `GameLib/MapOutdoor.cpp` 除高度/水面外还负责 terrain/area 初始化、environment 绑定、视锥、对象和地形 ray picking；`MapOutdoorQuadtree.cpp` 建立/销毁四叉树，`MapOutdoorIndexBuffer.cpp` 为不同 patch/warp 方向生成索引，`TerrainPatch.cpp` 同时维护硬件/软件地形顶点、水顶点、光照和 patch proxy。
- `MapOutdoorCharacterShadow.cpp` 创建角色 shadow render target/depth surface、切换 viewport/render target 后恢复旧状态；当前 Godot terrain/splat/WorldEnvironment 有视觉替代，但没有同一设备资源、patch LOD、四叉树和 shadow pass 生命周期。
- `PRTerrainLib/Terrain.h`/`TerrainType.h`/`TextureSet.cpp`/`TextureSet.h` 补充 height/normal/water/texture-set 的底层数据和纹理层状态。当前格式测试与 A1 水面测试覆盖读取结果，但未证明 TextureSet、patch、quadtree、shadow 与 streaming 卸载保持同一资源边界。
- 本轮完成上述 GameLib/PRTerrainLib 活跃地图源码静态核对；静态网格与水面测试不能替代对象 picking、patch/culling、shadow 和资源清理等价性。

## Status

`PARTIAL`。地形插值、桥面高度、属性阻挡、水面渲染和钓鱼方向已经有较强实现与真实地图证据；静态对象射线优先级、具体水层高度、高半字节属性、streaming 边界和统一碰撞/清理时序仍未达到 40250 的一致实现。

### Active EterLib collision-core review

- `EterLib/AttributeData.cpp`/`AttributeInstance.h`/`CollisionData.cpp`/`CollisionData.h` 提供静态属性数据、碰撞形状、法线/命中信息和实例级查询；`CullingManager.cpp` 负责范围、射线、可见性注册和对象集合维护；`Decal.cpp` 还参与地表贴花的对象/高度依赖。
- 这些源码确认参考端的碰撞/拾取不是单纯高度采样：对象注册、射线、属性实例和清理顺序共同决定桥梁/平台/遮挡结果。当前端的 `sample_height`、Godot `HeightMapShape3D`、逻辑 `is_blocked` 和对象 AABB/胶囊是并行近似，未统一成同一 culling/attribute query 链。
- 因此本轮完成 `AttributeData`、`CollisionData`、`CullingManager`、`Decal` 的活跃源码静态核对，但没有把静态符号存在误记为 parity 通过；静态对象优先级、跨区块卸载和碰撞/贴花清理仍是 `PARTIAL`。