M0' scaffold: Godot 4.7 + GDExtension + libgr2 wired up (macOS)

- extension/: godot-cpp submodule (master, API 4.7), Metin2Model node registered, links xrender-poc/libgr2 via sibling-dir reference. - project/: Godot 4.7 project — orbit camera + DirectionalLight3D (shadows) + WorldEnvironment/procedural sky + placeholder cube; main.gd probes the extension and can run libgr2 on a real .gr2 (MTGODOT_PROBE_GR2). - build.sh one-shot build into project/bin/. - docs/GODOT-POC-PLAN.md (phased: Phase 1 macOS -> M0'/M1/M2/M2.5). Verified on this machine: [mtgodot] Metin2Model registered OK — libgr2 linked probe_gr2(warrior_cheongrin.gr2) -> gr2 OK: format_version=6 sections=8 Metal Forward+ renders the scene (test/golden/m0-scaffold.png). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WaHYEY9rwLWt21PULiYjeJ
2026-08-29 09:09:55 +09:00
commit c52b8657c4
21 changed files with 839 additions and 0 deletions
@@ -0,0 +1,111 @@
+# mtgodot-poc
+
+「**Godot 4 + 自研资源 loader**」跨平台方案的渲染 Demo（route ①）。
+用一个 C++ GDExtension 复用 [`xrender-poc`](../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`](docs/GODOT-POC-PLAN.md)。
+
+---
+
+## 现状
+
+- [~] **M0'** — 脚手架。GDExtension 骨架（`Metin2Model` 空节点）+ `libgr2` 静态库集成 + Godot 4.7 工程（orbit 相机 + 方向光阴影 + sky + 占位 cube）。macOS only。
+
+---
+
+## 环境
+
+| 组件 | 版本 / 位置 | 说明 |
+|---|---|---|
+| 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）。
+
+---
+
+## 构建
+
+```bash
+git submodule update --init --recursive     # 拉 godot-cpp（首次）
+./build.sh                                   # Debug；产物 → project/bin/libmtgodot.macos.template_debug.dylib
+./build.sh Release                           # template_release
+```
+
+首次会编译 godot-cpp（几分钟）。
+
+## 运行
+
+```bash
+# 编辑器打开
+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 代码。本仓库内部研究用途，不对外公开。