# 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)。

---

## 现状

- [x] **M0'** — 脚手架。GDExtension 加载 + `Metin2Model` 注册 + `libgr2` 链接可调用
  + Godot 4.7 工程经 Metal Forward+ 出画。T0.4 实际 `export` 待装 4.7.1 导出模板。
- [x] **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) 均正确加载渲染。
- [x] **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`](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）。

---

## 构建

```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/` 进本仓库

> ⚠️ 本仓库依赖 `../xrender-poc/libgr2` 里新增的 `dump_materials()`
> （`src/gr2_material.cpp` + `include/gr2/gr2.h` + `CMakeLists.txt` 三处，纯附加）。
> 该改动目前只在 xrender-poc 工作树里，**未提交**（那个仓库无提交历史，保持原样）。
> 需要时由 xrender-poc 的维护者按其流程纳入。

`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 代码。本仓库内部研究用途，不对外公开。