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' — 脚手架（macOS）。本机已验证：
  • T0.1 GDExtension 加载、Metin2Model 注册成功 （[mtgodot] Metin2Model registered OK）。
  • T0.2 libgr2 链接进扩展且可调用：probe_gr2(warrior_cheongrin.gr2) → gr2 OK: format_version=6 sections=8。
  • T0.3 Godot 4.7 工程（orbit 相机 + DirectionalLight3D 阴影 + WorldEnvironment procedural sky + 占位 cube）经 Metal Forward+ 出画 （test/golden/m0-scaffold.png）。
  • T0.4 export_presets.cfg（macOS）就位；实际 export 待安装 4.7.1 导出模板（godot --headless --install-export-templates）。

---

环境

组件	版本 / 位置	说明
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 代码。本仓库内部研究用途，不对外公开。