mtgodot-poc/docs/GODOT-POC-PLAN.md

Godot 渲染 Demo — 开发计划

内部研究方案，不对外公开。

2026-08-29 更新：并行的 bgfx 自研引擎方案（xrender-poc / reference/PLAN.md） 经中期评审（MIDREVIEW.md）停止开发，本方案成为唯一在研路线。 libgr2 / formats / oracle / tools 已从 xrender-poc vendored 进本仓库 （../libgr2、../formats、../oracle、../tools），不再是 submodule / sibling 引用。 下文中出现的 xrender-poc/xxx 路径按 reference/README.md 的映射表读。 bgfx demo 截图作为交叉核对基线留在 ../test/bgfx-reference/。

状态	已被工作范围超越（2026-09-08 复核）。Phase 1（macOS）完成，见 MIDREVIEW.md；Phase 2 的 iOS / Android 交叉编译与 APK 导出也已完成（BACKLOG.md F1/F2、PLATFORMS.md），故文中「Phase 2 本轮不做」不再成立。§01「明确排除」清单已大面积失效，见该节的复核注。当前工作以 BACKLOG.md、CLIENT-GAP.md、RENDERING-REPAIR-PLAN.md 为准
技术栈	Godot 4.7.1 stable · GDExtension（godot-cpp 精确提交 101ae38，4.7 API）· C++20
目标平台	Phase 1：macOS（当前）→ Phase 2：Android（一加 13 / Vulkan）· iOS（iPhone 16 / Metal）。自用，三台现代设备，不涉及 GLES3 / Compatibility
判定周期	Phase 1 ≈ 3.5–5 周（单人）→ 中期评审；Phase 2 = 三设备各一次 bring-up + 性能留档（自用，无对外 go/no-go）
复用	libgr2（gr2 v6 读取器）· formats/（textscript · msa · msm）· oracle/ golden · bgfx demo 截图
自研	Metin2Model GDExtension 节点（gr2 → Skeleton3D + ArrayMesh + 材质）

---

00 · 阶段划分

阶段	平台	里程碑	回答什么	产出
Phase 1	macOS	M0' · M1 · M2 · M2.5	① gr2 → Godot 场景对象能否正确映射；② 动画运行时（采样 / retarget / 事件）能否移植；③ Metin2 观感能否在 Godot 里还原	中期评审报告：桥接层工作量实测 + 观感对比 + 剩余风险
Phase 2	Android（一加 13）· iOS（iPhone 16）	M3（·M4 可选）	④ 三端渲染一致；⑤ 两台移动设备性能 / 生命周期	三设备 bring-up 报告 + 性能留档

关键澄清：Godot 在 macOS 上渲染一个蒙皮 gr2 几乎不可能失败，Phase 1 的价值是把平台无关的 GDExtension 工程（占工程量大头）做完并确认视觉保真度可达。bgfx 自研引擎方案已于 2026-08-29 停止开发，Godot 是唯一在研路线；本项目自用、不对外发布，没有"押哪条路线"的产品决策。Phase 2 只剩"三台目标设备（Mac / 一加 13 / iPhone 16）上能不能跑 + 性能够不够自己用"。

进入 Phase 2 的前置：M2.5 门禁通过、中期评审确认桥接层与观感可接受即可推进。三台目标设备都是现代硬件，全程不涉及 GLES3 / Compatibility 渲染器，不做中低端 / 老机器。

---

01 · 目标与判定标准

Phase 1 要证明的三件事（macOS）

1. gr2 → Godot 场景对象 — libgr2 读出的骨架 / 蒙皮网格 / 权重能否正确映射到 Skeleton3D + ArrayMesh + Skin，覆盖多种骨架（不止 warrior）。
2. 动画正确 — 每帧从 libgr2::sample_pose 驱动 Skeleton3D，结果与 bgfx demo / Granny oracle 逐帧一致；跨文件 retarget、motion event 成立。
3. 观感可还原 — 多 texture-stage 材质、alpha test、顶点色、additive 混合、fog、方向光阴影在 Godot 里做出来，与原客户端目视接近。

Phase 2 要证明的两件事（移动端，本轮不做）

4. 三端一致 — 同一 GDExtension + Godot 工程在 iPhone 16（Metal）+ 一加 13（Vulkan）渲染与 Mac 一致。
5. 性能 / 生命周期够自用 — 两台设备单角色 / 多角色帧率可接受（旗舰基线，非发布门槛），后台 / 恢复稳，Godot 节点开销可控。

明确排除（两个阶段都不做）

⚠️ 本清单已失效（2026-09-08 复核）。 下列 9 项中 8 项后来都做了 —— POC 判定通过后项目 继续做成了完整客户端，范围扩张是有意的（SHINSOO-WORLD-RENDERING.md 的「定位」一节最早 记录了 UI 这一条）。逐项现状：

原「不做」项	现状	落点
SpeedTree 植被	🟡 已做 proxy	formats/spt.cpp，BACKLOG E10
地形（Metin2 户外地图）	✅ 已做	Metin2World + formats/terrain_mesh.cpp，BACKLOG E8/E11/E12
UI / Python 脚本层	✅ 已做	project/ui/*（uiscript 装载器 + 多个 1:1 窗口移植）
eterpack	✅ 已做	mtpack + packtool，BACKLOG G1
GPU 蒙皮优化	✅ 已做	MTGODOT_GPUSKIN=1，m2_material SRC_SKIN
LOD 策略	✅ 已做	lod_distances + crossfade，BACKLOG C9
多角色 AI	⬜ 仍不做	——
网络	✅ 已做	mtnet（m2dev + 40250 classic 双后端）
玩法	✅ 大量已做	CLIENT-GAP.md / CLIENT-ROADMAP.md P0–P10

SpeedTree 植被、地形（Metin2 户外地图）、UI / Python 脚本层、eterpack（Phase 1 用散文件）、GPU 蒙皮优化、LOD 策略、多角色 AI、网络、玩法。

地形与 .mse 特效在 Phase 1 也不做，但 M2.5 会做通用 ShaderMaterial + 混合模式的地基，为后续正式移植时的地形 / 特效渲染铺路。

判定口径

• M2.5 门禁通过 + 中期评审"可接受" = 推进 Phase 2。中期评审已判定桥接层工作量与观感均可接受（MIDREVIEW.md）；bgfx route 已停，无「转回」分支。
• Phase 2 若撞上方案性死路（自写蒙皮着色器在 iPhone 16 / 一加 13 上跑不出、Godot 节点开销在自用规模下就卡）——记录清楚、就地想办法（回落 CPU LBS / RenderingServer 直调 / uniform 传骨骼），不再有另一条引擎路线兜底。
• Phase 2 末交付：三设备 bring-up + 性能留档报告（自用参考，不做对外选型结论）。

与 bgfx route 的关系（历史对照，bgfx route 已于 2026-08-29 停止开发）

	bgfx route（PLAN.md）	Godot route（本文件）
渲染器	自研（bgfx 薄封装 + .sc 着色器）	Godot 内置渲染器
平台壳 / 输入 / 音频 / 打包	自己拼（SDL3 / 薄壳 + 各库）	Godot 全包 + 编辑器
gr2 解析	libgr2	libgr2（同一份）
动画运行时	自研（复用 EterGrnLib 逻辑）	映射到 Skeleton3D / AnimationMixer
阴影 / 环境 / sky	自研	Godot 内置（M2.5 直接用）
长期	自己养一个引擎	跟随 Godot 版本（GDExtension ABI 绑 minor）

libgr2 在两条路里都是核心，完整复用。

---

02 · 架构总览

metin2-client/            # 建仓时叫 mtgodot-poc，后更名
  extension/                  GDExtension（C++，godot-cpp 4.7）
    src/
      register_types.cpp      注册 Metin2Model / Metin2AnimPlayer
      metin2_model.{h,cpp}    load_gr2 → Skeleton3D + ArrayMesh + Skin + material
      metin2_anim.{h,cpp}     每帧 libgr2::sample_pose → Skeleton3D bone pose；跨文件 retarget；motion event
      gr2_bridge.{h,cpp}      libgr2 POD 视图 → Godot 数组打包；basis + 单位换算（集中一处）
      dds_loader.{h,cpp}      DDS → Godot Image（散文件路径用；res:// 里的 .dds 交 Godot 原生导入）
      m2_material.{h,cpp}     texture-stage 描述 → ShaderMaterial（M2.5）
    (libgr2 / formats 在仓库根，顶层 CMake add_subdirectory 进来)
    SConstruct / CMakeLists   godot-cpp 构建（Phase 1 只出 macOS arm64）
  project/                    Godot 4.7.1 demo 工程
    main.tscn                 orbit 相机 + DirectionalLight3D(+shadow) + WorldEnvironment(sky) + Metin2Model
    main.gd                   加载资产、切模型 / 动画、截图、性能 HUD
    assets/                   warrior + 另 2 种骨架的 gr2/dds
      .gdignore               ← 让 Godot 不去 import .gr2（见下）
    export_presets.cfg        macOS（Phase 1）
  test/
    golden/                   godot-macos-*.png
    compare.py                与 test/bgfx-reference/ 参考截图 + oracle 对拍
  docs/
    GODOT-POC-PLAN.md         本文件
    steps/                    按需拆

分层（Phase 1）

层	内容
平台 / 窗口 / 输入 / 打包	Godot（macOS）
渲染器	Godot 内置 Forward+（macOS / Metal）
资源运行时	Metin2Model GDExtension：gr2 → Skeleton3D / ArrayMesh / Skin / ShaderMaterial
动画	每帧 libgr2::sample_pose 写 Skeleton3D（B 方案）；A/B 决策推迟到 Phase 2（Mac 上信号不足），M2 只做一次 50 角色压力采样留档
解析	libgr2（复用） · formats/（msa/msm，复用） · DDS
数学 / 坐标	Godot Transform3D / Basis；gr2 art-tool basis → Godot 右手 Y-up + 单位缩放，在 gr2_bridge 一次性处理，约定见 §03

两个实操约定（Phase 1 T1 前定死，写进 gr2_bridge 注释）

• .gr2 不进 import 流程：project/assets/ 放 .gdignore，.gr2 由 Metin2Model 在运行时用绝对路径 / user:// 直接读；.dds 可留在 res:// 交 Godot 原生导入，或也走运行时 dds_loader（二选一，T1.3 决定并记录）。
• 单位缩放：定 M2_TO_GODOT = 0.01（Metin2 约 100 unit ≈ 1 Godot m），相机 near/far、DirectionalLight3D 阴影范围按此设。若与资产实测不符，在 T1.1 调整并记录。

---

03 · 技术选型

项	选择	理由
引擎版本	Godot 4.7.1 stable（本机已装），锁死不随手升	GDExtension ABI 绑 minor；升级作独立任务
扩展机制	godot-cpp 101ae38034304346a46ea9ea84ae156d3e860496，GDExtension（非模块编译）	gitlink 精确锁定，目标 API 4.7；升级作独立任务
构建工具	godot-cpp 的 CMake 路径（本机已有 cmake；不装 SCons）或 brew install scons 二选一	Phase 1 只出 macOS arm64，摩擦最小
gr2 解析	xrender-poc/libgr2 静态库嵌入 extension	与 bgfx route 同一份，已过 9166 fuzz + oracle
动画方案	B（每帧写骨骼）；A（烘 Animation）决策推迟到 Phase 2	B 直接复用 libgr2 采样、最保真；A 的动机（多角色 CPU）在 Mac 上压不出来
骨骼权重	ArrayMesh 4 权重优先；>4 影响则 ARRAY_FLAG_USE_8_BONE_WEIGHTS	M1 T1.2 早验，三种骨架都查
贴图	见 §02 实操约定（.dds 原生导入 vs 运行时 dds_loader，T1.3 定）	两条都留
材质	自定义 ShaderMaterial（light() 自定义着色贴 Metin2 观感）；M1 先 StandardMaterial3D 上屏，M2.5 换	多 stage 只做近似，列差距清单
渲染器	Forward+ / Mobile renderer	三台目标设备（Mac / 一加 13 / iPhone 16）都是现代硬件，全程不涉及 Compatibility(GLES3)
阴影 / sky	Godot 内置 DirectionalLight3D shadow + WorldEnvironment procedural sky，M2.5 接入	成本近零，Mac 观感必要
资产来源	从 assets/ 取 warrior + 另 2 种骨架 的 gr2/dds 到 project/assets/，散文件	不接 eterpack（Phase 2 / M4）
真值源	xrender-poc/oracle golden + bgfx demo 同机位 / pose / t 截图	复用现成对拍基建
仓库	新建 mtgodot-poc/，libgr2 / formats submodule 指向 xrender-poc	隔离，不污染 bgfx route

---

04 · 里程碑

M0' · 脚手架（macOS，1–2 天）

目标：GDExtension 骨架 + libgr2 集成 + Godot 工程能跑，仅 macOS。

任务	完成判据
T0.1 godot-cpp 4.7 GDExtension 骨架，注册空节点 Metin2Model（继承 Node3D）	Godot 4.7.1 编辑器里能添加该节点、无报错
T0.2 构建集成 libgr2 静态库（CMake 或 SCons），仅 macOS arm64	libgr2 符号进 extension，.dylib 加载成功
T0.3 Godot 工程骨架：main.tscn（orbit 相机 + DirectionalLight3D + WorldEnvironment + 空 Metin2Model），main.gd（orbit 控制 + 截图键）	编辑器运行出带 sky 的场景 + 一个 cube，鼠标可轨道
T0.4 project/assets/.gdignore；export_presets.cfg 加 macOS preset	导出一次 macOS .app，空场景能跑

门禁 M0'：macOS 上跑起「Godot 场景 + sky + cube + orbit 相机」，导出的 .app 也能跑。

---

M1 · 静态渲染（1–1.5 周）

目标：warrior + 另 2 种骨架的 bind pose + 贴图在 Godot 里正确显示，多部件组装。

对标 reference/steps/M1-static-render.md T2–T5。

任务	完成判据
T1.1 gr2_bridge：libgr2::Skeleton → Skeleton3D（bone 名 / parent / rest Transform3D）；basis + 单位缩放在此处理，约定写进注释	骨架层级树与 gr2dump --members 一致；三种骨架的骨骼数都正确
T1.2 libgr2::Mesh → ArrayMesh（ARRAY_VERTEX/NORMAL/TANGENT/TEX_UV/BONES/WEIGHTS）+ Skin（bind 矩阵）；处理 >4 权重	白模轮廓 = Blender 里同模型；无破面；三种骨架都过
T1.3 贴图路径决策（.dds 原生导入 vs 运行时 dds_loader），实现选定方案；warrior 贴图（实测 512×512 DXT3 5mip）	UV 无错位 / 无镜像；决策写进 extension/README.md（该文件未产出，2026-09-08 复核；决策实际记录在 MIDREVIEW.md §3「贴图」与 extension/src/dxt.cpp 注释里）
T1.4 材质：StandardMaterial3D（albedo 贴图 + unshaded 先看轮廓），可切白模	贴图目视正确
T1.5 多部件（body / weapon / hair）组装，武器挂 BoneAttachment3D	部件数正确、武器跟手骨
T1.6 test/compare.py：与 bgfx demo 同机位截图	几何一致（允许色彩空间 / 光照差异）

门禁 M1：warrior + 2 种骨架 bind pose 下与 bgfx demo 同机位截图几何像素级接近；顶点数、部件数、骨骼数与 oracle dump 一致。

---

M2 · 骨骼动画（1.5–2 周）

目标：从 GDExtension 每帧驱动 Skeleton3D 播动画，含跨文件 retarget 与 motion event。

对标 reference/steps/M2-anim-skinning.md。

任务	完成判据
T2.1 Metin2AnimPlayer：_process 里 libgr2::sample_pose(t) → 写 Skeleton3D 每骨 local Transform3D	单个动画连续播放、不抖
T2.2 跨文件 retarget：骨架 gr2 + 独立动画 gr2 / .msa 按骨名对齐（必要时 RetargetModifier3D / 骨名映射表）	warrior 骨架播 dance_1（独立文件）姿势正确
T2.3 motion event：.msa/.msm 里的帧事件（放音 / 特效锚点 / 震屏）解析并派发（Phase 1 只需回调打点，不接实际特效）	事件在正确帧触发，日志可见
T2.4 main.gd：idle + 一个动作，按键 / HUD 按钮切换	切换无爆姿势
T2.5 逐帧对拍：同 t 的 Skeleton3D 世界骨骼矩阵 vs bgfx demo / oracle	差值在坐标系 / 单位换算误差内（沿用 M2 的 ~6.5e-5 量级口径）；全程无 NaN
T2.6 全量采样自检：181 个 warrior 动画逐个 load + sample	0 崩溃、0 NaN
T2.7 留档：50 角色同播动画的帧时间 / _process 耗时采样（不作门禁，给 Phase 2 A/B 决策用）	数据写进 test/godot-macos-stress.json

门禁 M2：181 动画全部加载采样无 NaN；选定动作与 bgfx demo 同 t 视觉一致、数值在换算误差内；motion event 触发帧正确。

---

M2.5 · 材质与观感保真（1–1.5 周）★ Phase 1 的核心门禁

目标：把 Metin2 的固定管线材质在 ShaderMaterial 里近似出来，让 Mac 版渲染"看起来做好了"。

任务	完成判据
T2.5.1 m2_material：Metin2 材质描述（texture-stage op / arg / alpha op）→ 自定义 ShaderMaterial（Godot shading language，light() 自定义）	单 stage MODULATE(TEXTURE, DIFFUSE) = tex * vertex_color 与 bgfx demo texture_stage.sh 输出一致
T2.5.2 多 stage 近似：MODULATE2X / ADD / BLENDDIFFUSEALPHA 等常见组合	warrior 全套贴图正确显示，与原客户端目视接近
T2.5.3 alpha test（D3DCMP_*）+ alpha blend + additive（装备发光）	半透明 / 发光部件正确，排序无明显错误
T2.5.4 顶点色 + fog（线性 / exp2）	与 bgfx demo 对拍一致
T2.5.5 接 Godot DirectionalLight3D 阴影 + WorldEnvironment（procedural sky + ambient）	角色有投影、受环境光；整体画面完整
T2.5.6 差距清单：列出无法 1:1 还原的项（排序 corner case、特定 blend op、mip / 各向异性差异）	写进中期评审报告

门禁 M2.5：warrior 完整着装 + 动画，在 Godot 里与原客户端 / bgfx demo 目视接近（结构化对比 + 直方图，不做像素比）；差距清单里没有"方案性死路"项。

---

M3 ·（Phase 2，本轮不做）Android + iOS bring-up + 性能

一加 13（Vulkan）+ iPhone 16（Metal）真机跑起来、三端一致、性能留档、生命周期。iOS 需把 GDExtension 按 arm64 静态库编出来（链进 app 二进制）。不涉及 Compatibility 渲染器。详见后续 steps/M3-mobile.md（届时再写）。

M4 ·（Phase 2 可选拉伸）

接真实 eterpack、试水一个 .mse 特效、多 texture-stage 精确对拍。

---

05 · 工作量（Phase 1，macOS）

里程碑	单人	2 人并行
M0'	1–2 天	1 天
M1	1–1.5 周	1 周（网格 / 骨架分工）
M2	1.5–2 周	1–1.5 周（动画 / 对拍分工）
M2.5	1–1.5 周	1 周（shader / 材质映射分工）
Phase 1 合计	≈ 3.5–5 周	≈ 2.5–3.5 周

前置依赖：xrender-poc 的 libgr2（已完成）、oracle golden（M2 对拍要）、bgfx demo（M1/M2/M2.5 截图对拍要，已可跑）、Godot 4.7.1 export templates（需在编辑器内下载）。

---

06 · 风险登记册

Phase 1（macOS）

风险	触发信号	缓解 / 退路
godot-cpp + libgr2 构建集成摩擦	M0' 链接 / 加载失败	只出 macOS arm64，摩擦面最小；CMake 路径优先，SCons 备选
.gr2 被 Godot import 流程扫到报错	打开工程时一堆 import 错误	project/assets/.gdignore；.gr2 走运行时绝对路径 / user://，T1 前定死
gr2 basis / 单位换算到 Godot（左手 → 右手 Y-up + 缩放）	M1 模型躺 / 镜像 / 骨骼反向 / 大小离谱	gr2_bridge 一次性处理，定 M2_TO_GODOT，用朝向明确资产手校，写注释
Skeleton3D 骨骼数上限 / 8 权重路径行为	M1 T1.2 蒙皮爆开 / 部位错位	三种骨架都查 gr2dump；>4 权重走 8-bone flag
多 stage 固定管线材质无法在 ShaderMaterial 近似到可接受	M2.5 T2.5.2/3 关键装备观感明显错	这是 Phase 1 主要方案性风险；差距清单区分"可延期"vs"死路"。中期评审已判定为可延期（观感打磨，见 MIDREVIEW.md）；bgfx route 已停，无「转回」分支
半透明 / additive 排序 corner case	M2.5 T2.5.3 发光部件穿插	记入差距清单；Godot 的 render_priority / depth_draw 调，不追求 100%
motion event 语义（.msa/.msm 帧事件类型）	M2 T2.3 事件类型没覆盖全	Phase 1 只需打点回调，实际特效 Phase 2；未覆盖类型列清单

Phase 2（移动端，本轮不激活，仅登记）

风险	缓解 / 退路
每帧 CPU LBS 全量重建 mesh 的成本（多角色）	MTGODOT_GPUSKIN=1 自写蒙皮着色器（已实现）；多线程构建 + eterpack 共享资产
自写蒙皮着色器（texelFetch + RGBAF + BONE_INDICES）在 iPhone 16 Metal / 一加 13 Vulkan 上的行为	Phase 2 各跑一次；出问题回落 CPU LBS 或改 uniform 数组传骨骼。三台都是现代设备，无 GLES3 约束
Godot 节点开销（大场景规模）	MultiMesh / RenderingServer 直调兜底
GDExtension ABI 绑 Godot minor	锁 4.7.1，升级作独立任务
iOS：GDExtension 须静态链接进 app 二进制（libgr2 出 iOS arm64 .a），签名 / 模板脾气大	自用免费 provisioning 够用；预留 2–3 天 bring-up

---

07 · 验证方法论

• 真值源：xrender-poc/oracle 的 Granny golden 数据 + xrender-poc bgfx demo（同机位 / pose / t 截图与数值 dump，Metal 后端在同一台 Mac 上跑）。
• 每个门禁存 test/golden/godot-macos-<case>.png + 骨骼矩阵 / 顶点 dump，跑 test/compare.py 与 bgfx route 对拍。
• 资产集：xrender-poc/test/assets.list 里的 warrior 相关文件 + 另选 2 种骨架（记入本仓库 test/assets.list）。
• 对拍容差：几何 / 骨骼矩阵按坐标系 + 单位换算误差内严格比；颜色 / 光照因渲染器不同不做像素比，只做结构化目视 + 直方图。

---

08 · 交付物

Phase 1（本轮）

产物	位置
mtgodot-poc/ 仓库：GDExtension 源 + Godot 4.7.1 demo 工程	新仓库
macOS 导出配置	project/export_presets.cfg
与 bgfx demo 的几何 / 动画对拍报告	test/godot-snapshot.json 未产出（2026-09-08 复核）。实际落地的是 test/compare.py + test/compare-report.json（进程 / 截图 / 结构硬门禁），与 bgfx 的比对停留在 test/bgfx-reference/ 的人工交叉核对
材质差距清单	中期评审报告内
50 角色压力采样（供 Phase 2 A/B 决策）	test/godot-macos-stress.json
中期评审报告	桥接层工作量实测 + 观感对比截图 + 剩余风险 + "是否进入 Phase 2"建议

Phase 2（后续）

产物
iOS .ipa（iPhone 16）+ Android APK（一加 13）+ 两台真机性能 / 生命周期报告
三设备 bring-up 报告：三端渲染一致性截图 + 各设备帧率留档（自用参考，不做对外选型结论）

---

选型变更记录

• 2026-08-29 · 设备范围定死（自用）：目标 = Mac（macOS / Metal）+ 一加 13（Android arm64 / Vulkan）+ iPhone 16（iOS arm64 / Metal），各一台。取消对外 go/no-go 门禁（bgfx route 已停、项目自用）；Phase 2 收敛为「三设备各一次 bring-up + 性能留档」。全程不涉及 GLES3 / Compatibility 渲染器，不做中低端 / 老机器。SHINSOO 的 W0→W1+ 因此无外部门禁。
• 2026-08-29 · 范围收敛为 Phase 1 = macOS only；新增 M2.5 材质与观感保真 作为 Phase 1 核心门禁；动画 A/B 决策推迟到 Phase 2；Godot 版本钉死 4.7.1 / godot-cpp 4.7。
• 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 方案（每帧 gr2::sample_pose 驱动）。两条蒙皮路径，都用 libgr2 的 skin 矩阵完整仿射（shear 保留）：默认 CPU LBS（metin2_anim.cpp → Metin2Model::cpu_skin，每帧重建 ArrayMesh）；MTGODOT_GPUSKIN=1 → 自写蒙皮顶点着色器（m2_material SRC_SKIN，逐骨 4×3 矩阵存 RGBAF 纹理，Metin2Model::gpu_skin 每帧更新，绕过 Skeleton3D）。原因：Godot 内置 GPU 蒙皮 / set_bone_pose 会正交化骨骼矩阵、丢掉 Granny 烘在 rig 骨（bone_front_*/Bone_shoulder_*；warrior 7 / sura 16）上的 shear（tools/anim_probe 定位，非 libgr2 —— world[] 对拍 Granny ≤4.1e-5）。旧 Skeleton3D::set_bone_pose 路径已删。A 方案（烘 Animation）走 Skeleton3D 骨骼、同样丢 shear，不用。
• 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 还原 / 待办项清单

不再单独维护 —— 全部并入 BACKLOG.md B 段（B1–B11）。下表为历史快照。

项	现状	影响	出路
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 未接线 已做（2026-08-29）	gr2_bridge::build_parts() 把一个 gr2 mesh 按 tri_groups 拆成 N 个 RenderPart → N 个 Godot surface，贴图取 Mesh::material_textures[matidx]（mesh-local，非全局 Materials[]）。GPU 和 CPU 蒙皮路径都走 RenderPart。	—
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 打磨）
法线变换	CPU 与 GPU（SRC_SKIN 着色器）两条路径都用混合矩阵的上 3×3、不逆转置 —— 与 Granny runtime 一致（见 docs/reference/steps/M2-anim-skinning.md）。非均匀缩放骨骼下这是 Granny 自己的近似，我们与之一致。	已一致	—