chore(build): 搭建并验证 C# / C++(GDExtension) 原生构建环境（4.7.1 Mono）

为「GDScript→C#→C++」性能逃生梯备好可随时启用的工具链，运行时仍 100% GDScript。 C#：新增根 Rogue.csproj（Godot.NET.Sdk/4.7.1，net8.0，程序集名 Rogue）； csharp/ 下既有 3 个骨架 .cs 现可编译，dotnet build 与编辑器 --build-solutions 均 0 错通过。 C++：gdextension/ 下加 godot-cpp 子模块（master，因无 4.6/4.7 分支，配合本工程 dump 的 4.7.1 extension_api.json + gdextension_interface.h 经 custom_api_file 精确匹配 ABI）； SConstruct + 示例扩展 SpellforgeNative（含 PackedFloat32Array 零拷贝热路径写法）； SCons 自动探测 MSVC 构建出 debug .dll，headless 冒烟验证类注册/调用通过（CLASS_EXISTS=true / multiply=42 / scale_inplace 正确）。配套：.gitignore 忽略编译中间产物、保留 debug .dll 开箱即用；gdextension/README.md 记录构建/激活/升级流程； CLAUDE.md 修正引擎版本 4.6→4.7.1 并更新「环境已就绪但休眠」现状。 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-23 15:53:39 +08:00
parent 0561377492
commit aa69c0e2d4
16 changed files with 360365 additions and 5 deletions
@@ -0,0 +1,91 @@
+# 原生环境（C# / C++）搭建说明
+
+本工程为 **Godot 4.7.1-stable (Mono/.NET)** 工程，性能优化采用逐级逃生梯
+**GDScript（默认）→ C#（热路径逃生舱）→ C++（极限内核）**。语言定位与使用门槛见
+[`CLAUDE.md`](../CLAUDE.md)「编程语言规范」。
+
+> 现状：**运行时仍 100% GDScript**。C#/C++ 环境已搭好并冒烟验证通过，属「就绪但休眠」的逃生舱，
+> 仅当 profile 证明瓶颈时才按 `ADR-L1` 启用。
+
+---
+
+## C#（.NET）
+
+已就绪，无需额外步骤：
+
+- 工程文件 `Rogue.csproj`（根目录，`Godot.NET.Sdk/4.7.1`，`net8.0`，程序集名 `Rogue` 对齐
+  `project.godot [dotnet] project/assembly_name`）。
+- C# 源码放 `csharp/`，由 SDK 默认 `**/*.cs` glob 自动纳入编译。现有
+  `csharp/{autoloads,systems}/*.cs` 为休眠骨架。
+- 依赖：.NET SDK 8/9/10（本机已装）。
+
+**构建 / 验证：**
+
+```bash
+dotnet build Rogue.csproj -c Debug          # 命令行构建
+# 或在 Godot 编辑器内点「构建」；headless：
+Godot_v4.7.1-stable_mono_win64.exe --headless --build-solutions --quit
+```
+
+产物在 `.godot/mono/temp/bin/<Config>/Rogue.dll`（已被 `.gitignore` 忽略）。
+
+**新增 C# 类**：在 `csharp/` 下建 `.cs`，`public partial class Foo : Node/RefCounted`，重新构建即可
+attach 到节点或注册为 autoload。
+
+---
+
+## C++（GDExtension）
+
+**目录结构：**
+
+```
+gdextension/
+  godot-cpp/     子模块（master + 本工程 4.7.1 API 覆盖）
+  api/           从 4.7.1 编辑器 dump 的 extension_api.json + gdextension_interface.h
+  src/           扩展源码（register_types + 示例类 SpellforgeNative）
+  SConstruct     构建脚本（custom_api_file 指向 api/extension_api.json）
+  bin/           产物：*.gdextension + 已构建的 debug .dll
+  verify_native.gd  headless 冒烟脚本
+```
+
+**首次准备（克隆后）：**
+
+```bash
+git submodule update --init --recursive       # 拉取 godot-cpp
+python -m pip install scons                    # 若未装
+```
+
+**构建：**
+
+```bash
+cd gdextension
+scons target=template_debug -j8                # 或 python -m SCons ...
+scons target=template_release -j8              # 发布版
+```
+
+- Windows 由 SCons 自动探测 MSVC（VS 2022），无需手动 vcvars。
+- 产物：`gdextension/bin/libspellforge_native.windows.template_debug.x86_64.dll`。
+  为开箱即用，**debug .dll 已提交**；中间产物（`*.obj/*.lib/*.exp/.sconsign.dblite`）已忽略。
+
+**激活 / 验证：**
+
+`bin/spellforge_native.gdextension` 描述库路径与入口符号。Godot 编辑器扫描 `res://` 时自动发现并
+写入 `.godot/extension_list.cfg`（该文件在 `.godot/` 内、被忽略）。**若编辑器已在运行，需重启编辑器**
+才能加载新扩展。
+
+```bash
+# headless 冒烟：断言类已注册且可调用
+Godot_v4.7.1-stable_mono_win64.exe --headless --path . -s res://gdextension/verify_native.gd
+# 预期输出：CLASS_EXISTS=true / MULTIPLY_6x7=42.0 / SCALE_INPLACE_x10=[10,20,30]
+```
+
+**新增 C++ 类**：在 `src/` 下建 `.h/.cpp`（`GDCLASS` 宏），在 `register_types.cpp` 的
+`initialize_spellforge_module` 里 `GDREGISTER_CLASS(YourClass);`，重新 `scons` 即可。
+
+**升级引擎版本时**：重新 dump API 覆盖 `api/`，并 `git submodule update --remote gdextension/godot-cpp` 后重建。
+
+```bash
+Godot_....exe --headless --dump-extension-api extension_api.json --quit
+Godot_....exe --headless --dump-gdextension-interface --quit
+# 将产物移入 gdextension/api/ 覆盖旧文件
+```