joywayerandClaude Opus 4.8
0fb2cf6646
aa69c0e 误将构建生成物纳入版本控制，其中编辑器 ~ 前缀临时交换 DLL 会被运行中的
Godot 锁定，导致切分支/合并时反复冲突（本次合并即因它中断）。改为：
- .gitignore 新增 gdextension/**/~* 与 gdextension/**/*.obj.import 规则；
- git rm --cached 三个生成物（保留本地文件）：
bin/~libspellforge_native...dll、src/*.obj.import ×2。
保留已构建的 debug .dll（bin/libspellforge_native...dll）——按原 .gitignore 注释
「开箱即用」的既定意图，其内容稳定、不引发反复冲突。
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>原生环境（C# / C++）搭建说明
本工程为 Godot 4.7.1-stable (Mono/.NET) 工程，性能优化采用逐级逃生梯
GDScript（默认）→ C#（热路径逃生舱）→ C++（极限内核）。语言定位与使用门槛见
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 默认**/*.csglob 自动纳入编译。现有csharp/{autoloads,systems}/*.cs为休眠骨架。 - 依赖：.NET SDK 8/9/10（本机已装）。
构建 / 验证：
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 冒烟脚本
首次准备（克隆后）：
git submodule update --init --recursive # 拉取 godot-cpp
python -m pip install scons # 若未装
构建：
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/ 内、被忽略）。若编辑器已在运行，需重启编辑器
才能加载新扩展。
# 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 后重建。
Godot_....exe --headless --dump-extension-api extension_api.json --quit
Godot_....exe --headless --dump-gdextension-interface --quit
# 将产物移入 gdextension/api/ 覆盖旧文件