M2.5: ShaderMaterial + texture resolution + fog; multi-skeleton verified

- m2_material: Metin2-style ShaderMaterial. blend_mix shader (opaque /
  alpha-blend / alpha-test-cutout via `mode` uniform) + blend_add shader
  (additive glow). modulate(tex, COORD) * COLOR, diffuse_lambert.
- Metin2Model: material_mode prop ("metin2" ShaderMaterial | "standard");
  _resolve_texture does filename-convention + case-insensitive dir scan of
  *.dds (face/hair keyword slots, stem match, fallback); set_surface_texture
  override; guess_blend heuristic (hair->cutout, cape->alpha, effect->add).
  Texture cache. Fixed opaque path to NOT alpha-discard (was hiding bodies).
- harness: AABB-based camera framing, engine depth fog (MTGODOT_FOG=1),
  MTGODOT_ANIM_T fixed-pose capture (needs explicit anim reload first),
  MTGODOT_AUTOSHOT batch screenshot.

Verified: warrior 5/5 surfaces textured under the shader (t=9 dance pose,
lit, fogged). assassin 17/17 textured via dir scan. shaman_lord (gr2 v7)
renders. Screenshots test/golden/m25-*.png, m2c-t*.png.

Gap (M2.5 gate not closed): libgr2 POD API exposes no material/texture-name/
blend data, so multi-slot -> texture/blend mapping is heuristic only. Needs
a libgr2 material API (gr2_material.cpp walking the type tree) — same gap as
xrender-poc M1 T5. Documented in docs/GODOT-POC-PLAN.md §M2.5 T2.5.6.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WaHYEY9rwLWt21PULiYjeJ

docs/GODOT-POC-PLAN.md

@@ -294,5 +294,17 @@ mtgodot-poc/
 ## 选型变更记录
 
 - 2026-08-29 · 范围收敛为 **Phase 1 = macOS only**；新增 **M2.5 材质与观感保真** 作为 Phase 1 核心门禁；动画 A/B 决策推迟到 Phase 2；Godot 版本钉死 4.7.1 / godot-cpp 4.7。
-- *(待 M1 T1.3 填写：贴图走 `.dds` 原生导入 还是运行时 `dds_loader`)*
-- *(待 M2.5 T2.5.6 填写：材质无法 1:1 还原项清单)*
+- 2026-08-29 · **M1 T1.3**：贴图走 **运行时 `dds_loader`**（`src/dxt.cpp`，端口自 xrender-poc）。理由：Godot 4 的 `Image.load()` 不支持 `.dds`，且资产从 `res://` 外的绝对路径加载（`.gr2` 走 `.gdignore` 同理）。DXT1/3/5 + BGRA8，level 0 + `generate_mipmaps()`。
+- 2026-08-29 · **动画方案**：确认走 **B 方案** —— `_process` 里 `gr2::sample_pose` → `Skeleton3D.set_bone_global_pose(i, gr2_to_godot(world[i]))`，Godot GPU 蒙皮 `skin_matrix = global_pose(i) * bind_pose(i)` 恒等于 gr2 deformer 矩阵（`gr2_bridge.h` 有推导）。A 方案（烘 `Animation`）仍推迟到 Phase 2 按多角色 CPU 采样决定。
+- 2026-08-29 · **坐标/单位**：`gr2_to_godot()` = gr2 行主序 Mat4 的 4×4 转置 → Godot `Transform3D`；Z-up cm → Y-up m（`rotate(-90°,X)` + `scale(0.01)`）放在 `Metin2Model` 节点自身 transform（`make_conv`）。warrior/warrior_lord/assassin/shaman_lord 实测 `flip_z=false`、`flip_winding=false`、`unit_scale=0.01` 正立、朝 +Z、无镜像。
+
+### M2.5 T2.5.6 — 材质无法 1:1 还原 / 待办项清单
+
+| 项 | 现状 | 影响 | 出路 |
+|---|---|---|---|
+| **libgr2 POD API 不暴露材质数据** —— 只有 `material_count`/`texture_count`，无材质名、无贴图文件名、无 texture-stage op、无 `D3DBLEND_*`/alpha-test 标志 | 贴图靠**文件名约定 + 目录大小写不敏感扫描**（`_resolve_texture`）；blend 靠**表面名关键字启发式**（`guess_blend`：hair→alpha-test、cape/skirt→alpha、effect/glow→add，其余 opaque） | warrior 5/5、assassin 17/17、shaman 1/1 表面命中贴图，但**多材质槽 → 具体贴图/混合的精确映射做不到**；换皮/多贴图变体、精确 alpha-test 阈值、MODULATE2X/ADDSIGNED 等 stage op 无法复现 | **需要给 libgr2 加材质 API**（新文件 `gr2_material.cpp`，走类型树取 `Materials[].Name` + `Maps[].Texture.FromFileName` + shader/blend hint）。这也正是 xrender-poc M1 T5「多 stage 材质对拍待 oracle」的同一缺口，两条 route 共用修法。 |
+| **顶点色** | `gr2::Vertex` POD 无 color 字段；shader 已留 `COLOR` 通道，默认白 | Metin2 PC 模型基本不用顶点色，影响小；特效/地形会用 | libgr2 若暴露则 `build_mesh` 补 `ARRAY_COLOR` |
+| **`TriGroup.material_index` 未接线** | libgr2 已解析每个三角组的 material_index，但 `build_mesh` 目前一个 gr2 mesh = 一个 surface（未按 material_index 再拆分） | 单 mesh 内多材质的模型会用同一张贴图 | `build_mesh` 按 `tri_groups` 的 material_index 分 surface（有材质 API 后一起做） |
+| **ShaderMaterial 静态 `Shader` 退出泄漏** | `shader_for()` 用 function-static `Ref<Shader>`，Godot 退出时报 "1 shader never freed" | 仅退出时一条 warning，无功能影响 | 改成每材质自持 Shader，或注册 cleanup |
+| **alpha 排序 corner case** | 半透明/additive 用 `render_priority` 粗排，未做逐三角/OIT | 多层半透明部件可能穿插 | 记录，不追求 100%（Phase 2 M2.5 打磨） |
+| **法线未做逆转置** | 走 Godot GPU 蒙皮，其法线处理与 Granny runtime 的「上 3×3 不逆转置」近似不完全一致 | 非均匀缩放骨骼下法线略有差异；warrior 类资产无明显问题 | Phase 2 逐帧对拍时量化 |