Claude
0ecdca821e
The dump_materials() addition this repo needs lives uncommitted in the sibling xrender-poc working tree (that repo has no commit history; left as-is). Documented in README. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WaHYEY9rwLWt21PULiYjeJ
135 lines
5.8 KiB
Markdown
135 lines
5.8 KiB
Markdown
# 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 代码。本仓库内部研究用途，不对外公开。
|