mtgodot-poc/README.md

mtgodot-poc

「Godot 4 + 自研资源 loader」跨平台方案的渲染 Demo（route ①）。 用一个 C++ GDExtension 复用 xrender-poc 的 libgr2，把 Metin2 的 .gr2 骨骼资源渲染进 Godot，用 Godot 内置渲染器。

与 xrender-poc（自研引擎 + bgfx RHI）是两条并行的跨平台基座候选，共用 libgr2。

判定分两阶段：

阶段	平台	里程碑	产出
Phase 1（当前）	macOS	M0' · M1 · M2 · M2.5	中期评审（不下 go/no-go）
Phase 2	iOS · Android	M3	go / no-go

完整计划见 docs/GODOT-POC-PLAN.md。

---

现状

• M0' — 脚手架。GDExtension 加载 + Metin2Model 注册 + libgr2 链接可调用
  • Godot 4.7 工程经 Metal Forward+ 出画。T0.4 实际 export 待装 4.7.1 导出模板。
• M1 — 静态渲染。gr2 → Skeleton3D + ArrayMesh + Skin + 材质。 warrior_cheongrin（75 骨 / 5 表面 / 3324 顶点）正立、朝 +Z、贴图正确 （test/golden/m1-bindpose.png）。多骨架：warrior_lord(v6,74)、assassin(v6,95,17 表面)、 shaman_lord(v7,93) 均正确加载渲染。
• M2 — 骨骼动画。Metin2AnimPlayer _process 里 gr2::sample_pose（跨文件） → Skeleton3D.set_bone_global_pose，Godot GPU 蒙皮。dance01（28.3s / 74 track） 播放，selfcheck 25 采样 0 NaN，t=2/9/16/23 姿势各异（test/golden/m2c-*.png）。
• [~] M2.5 — 材质与观感保真。ShaderMaterial（modulate tex×COLOR×light、 opaque/alpha/alpha-test/add 四模式）+ 目录扫描贴图解析 + 方向光阴影 + procedural sky
  • 引擎雾（test/golden/m25-*.png）。门禁未闭：多材质槽 → 贴图/混合的精确映射需 给 libgr2 加材质 API（见 docs/GODOT-POC-PLAN.md §M2.5 T2.5.6 差距清单）。
• [~] 中期评审 — docs/MIDREVIEW.md。结论：桥接层工程量小、 风险基本出清，建议进入 Phase 2。收尾 3 项：compare.py 对拍、dump_materials Granny 对拍闭合 M2.5 门禁、前台/真机性能重测。

50 角色压力采样：test/godot-macos-stress.json（后台窗口 30fps 节流，仅构建成本 ~165ms/角色 和 100 角色破顶到 52ms 是可信信号）。

---

环境

组件	版本 / 位置	说明
Godot	4.7.1（/opt/homebrew/bin/godot，Homebrew cask）	编辑器 + headless
godot-cpp	submodule extension/godot-cpp @ master（pin 101ae38）	master 默认 targets Godot 4.7 API（GODOTCPP_DEFAULT_API_VERSION=4.7）；无 4.6/4.7 分支，只有 bundled extension_api-4-7.json
Xcode	26.4.1	macOS 构建
CMake	已装；不需要 SCons	godot-cpp 走 CMake 路径
libgr2	../xrender-poc/libgr2（sibling-dir 引用）	见下「libgr2 依赖」

导出模板（M0' T0.4 / 真正 export 才需要）：编辑器内 Editor → Manage Export Templates → Download，或 godot --headless --install-export-templates。~600MB，版本须与编辑器一致（4.7.1）。

---

构建

git submodule update --init --recursive     # 拉 godot-cpp（首次）
./build.sh                                   # Debug；产物 → project/bin/libmtgodot.macos.template_debug.dylib
./build.sh Release                           # template_release

首次会编译 godot-cpp（几分钟）。

运行

# 编辑器打开
godot -e --path project

# headless 冒烟测试（验证 GDExtension 加载 + 类注册）
godot --headless --path project --quit-after 3

# 跑一个真实 gr2 过 libgr2（可选）
MTGODOT_PROBE_GR2="$PWD/../m2dev-client-main/assets/PC/ymir work/pc/warrior/warrior_cheongrin.gr2" \
  godot --headless --path project --quit-after 3

控制台出现 [mtgodot] Metin2Model registered OK — libgr2 linked; ... = M0' 的 T0.1/T0.2 通过。

窗口内：拖拽 = 轨道，滚轮 = 缩放，F2 = 截图（→ user://）。

---

libgr2 依赖

M0' 直接用 sibling-directory 引用：extension/CMakeLists.txt 里 XRENDER_POC_DIR 默认 ../../xrender-poc，add_subdirectory 进 libgr2。 两个 repo 都在 .../mt/ 下时开箱即用。

换机 / CI 时二选一：

• git submodule add <xrender-poc url> third_party/xrender-poc 后传 -DXRENDER_POC_DIR=third_party/xrender-poc
• vendor 一份 libgr2/ 进本仓库

formats/（msa/msm）到 M2 才需要，届时同样方式接入。

---

目录

mtgodot-poc/
  CMakeLists.txt              顶层（macOS only 守卫）
  build.sh                   便捷构建
  extension/
    CMakeLists.txt           mtgodot SHARED + godot-cpp + libgr2
    godot-cpp/               submodule @ master
    src/
      register_types.{h,cpp} GDExtension 入口，注册 Metin2Model
      metin2_model.{h,cpp}   M0' 占位节点（证明类注册 + libgr2 链接）
  project/                    Godot 4.7 工程
    project.godot
    main.tscn                根 Node3D + main.gd
    main.gd                  M0' harness：建 env/light/cam/cube + 探测扩展
    assets/.gdignore         让 Godot 不 import .gr2/.dds
    bin/mtgodot.gdextension  扩展描述符（dylib 构建产物落这里）
    export_presets.cfg       macOS preset
  docs/
    GODOT-POC-PLAN.md        开发计划（M0'–M4 + 风险 + 验收）
    steps/                   （按需）
  test/golden/               对拍截图（M1 起）

授权

libgr2 全自研，不含 Granny SDK 代码。本仓库内部研究用途，不对外公开。