docs: add C# scripting design and editor issues

2026-03-26 17:23:30 +08:00
parent 93de4199d1
commit 7a814c724d
2 changed files with 1120 additions and 0 deletions
--- a/docs/plan/C#脚本模块的设计与实现.md
+++ b/docs/plan/C#脚本模块的设计与实现.md
@@ -0,0 +1,756 @@
+# C#脚本模块的设计与实现
+
+## 1. 背景
+
+XCEngine 的整体方向是模仿传统 Unity 引擎架构，而不是 DOTS/ECS-first 路线。
+在这一目标下，脚本系统应当满足以下基本预期：
+
+- 脚本语言使用 `C#`
+- 脚本以“挂载到 `GameObject` 上的组件”形式工作
+- 脚本与引擎核心解耦，支持独立编译和运行时加载
+- 脚本可以逐步扩展到 Inspector、场景序列化、Play/Simulate 工作流
+
+当前 `editor` 仍处于基础阶段，因此脚本系统第一阶段不应依赖 editor 完整落地。
+第一阶段的目标应当收敛为：
+
+- 先完成原生运行时与托管运行时之间的桥接
+- 先完成 `ScriptComponent + C# MonoBehaviour` 的基本执行链路
+- 先完成单元测试和最小场景级验证
+- 将 editor 集成需求单独列为 issue，后续补齐
+
+---
+
+## 2. 设计目标
+
+### 2.1 总体目标
+
+脚本系统应当提供一条接近 Unity 的开发路径：
+
+1. 用户在独立的 C# 项目中编写脚本
+2. C# 脚本编译为程序集
+3. Engine Core 在运行时加载程序集
+4. `GameObject` 上挂载 `ScriptComponent`
+5. `ScriptComponent` 驱动一个对应的 C# `MonoBehaviour` 实例
+6. 脚本通过引擎暴露的 API 调用原生功能
+
+### 2.2 第一阶段目标
+
+第一阶段只覆盖以下内容：
+
+- `engine` 内部的脚本运行时抽象
+- 第一套 C# 运行时实现
+- `ScriptComponent` 原生组件
+- `ScriptCore` 托管基础库
+- 最小可用的 `InternalCall` 绑定
+- 单元测试与最小运行时测试
+
+### 2.3 第一阶段非目标
+
+第一阶段明确不做以下内容：
+
+- editor Inspector 脚本字段编辑
+- editor 中的脚本类选择器
+- editor 的 Play/Simulate 集成
+- 自动编译、文件监听、热重载
+- 调试器接入
+- 发布态 AOT / IL2CPP
+- 大而全的引擎 API 暴露
+
+---
+
+## 3. 三方对比结论
+
+### 3.1 Unity
+
+Unity 的典型脚本模型有几个关键特征：
+
+- 用户脚本通常继承 `MonoBehaviour`
+- 一段脚本本质上就是一个组件实例
+- 脚本字段可序列化、可在 Inspector 中编辑
+- 生命周期完整，且与 `GameObject active` / `Component enabled` 语义一致
+- Play 模式运行的是运行时场景副本，而不是直接修改编辑场景
+
+### 3.2 参考项目 Fermion
+
+参考项目已经实现了一套 C# 脚本模块，优点主要在于：
+
+- 已经证明了 `Mono embedding + InternalCall + C# 程序集加载` 这条路线可行
+- 已经具备脚本类发现、脚本实例创建、字段反射、运行时调用
+- 已经有托管侧 API 包装层和原生侧 `ScriptGlue`
+
+但它的对象模型并不是 Unity 风格：
+
+- 托管脚本类继承的是 `Entity`
+- 原生挂载结构是 `ScriptContainerComponent`
+- 更像“一个实体挂多个脚本类名”，而不是“每个脚本本身就是一个组件”
+- 生命周期目前主要聚焦 `OnCreate/OnUpdate`
+
+结论：
+
+- Fermion 适合借鉴运行时技术路线
+- Fermion 不适合作为最终 API 形态的直接模板
+
+### 3.3 XCEngine 当前情况
+
+XCEngine 当前已经具备以下基础：
+
+- 已有 `GameObject + Component + Scene` 模型
+- `Component` 已定义 Unity 风格生命周期接口
+- `Scene` 和 `GameObject` 已有序列化入口
+- `ComponentFactoryRegistry` 已支持按类型名恢复组件
+
+但当前也存在会直接影响脚本系统设计的现实约束：
+
+- `Scene::Update/FixedUpdate/LateUpdate` 目前只遍历根对象
+- `GameObject::Update/FixedUpdate/LateUpdate` 目前不递归子对象
+- `Start` 的场景级一次性调度路径还未完整建立
+- `SetActive` 尚未真正驱动 `OnEnable/OnDisable`
+- editor 的 Play/Simulate 工作流仍未落地
+- `GameObject UUID` 当前未进入场景序列化主路径
+
+结论：
+
+- XCEngine 适合走 Unity 风格脚本模型
+- 但脚本系统第一阶段必须连同一部分运行时地基一起建设
+
+---
+
+## 4. 总体设计结论
+
+XCEngine 的 C# 脚本模块采用以下路线：
+
+- **脚本语言**：C#
+- **脚本挂载模型**：原生 `ScriptComponent` 对应托管 `MonoBehaviour`
+- **程序集模型**：`ScriptCore` 与 `GameScripts` 分离
+- **运行时加载模式**：独立编译，运行时加载
+- **桥接方式**：`InternalCall`
+- **运行时抽象策略**：先抽象接口，再优先落 Mono 实现
+- **第一阶段验证方式**：单元测试优先，不依赖 editor
+
+这条路线有两个核心原则：
+
+1. API 形态尽量接近 Unity
+2. 第一阶段严格控制范围，只做运行时闭环和测试闭环
+
+---
+
+## 5. 运行时选型
+
+### 5.1 第一阶段选型：Mono
+
+第一阶段建议使用 `Mono` 作为第一套 C# 运行时实现，原因如下：
+
+- 与现有规划文档保持一致
+- 参考项目已经证明这条技术路线可落地
+- `InternalCall` 路线成熟，适合快速建立最小可用系统
+- 便于在 Windows 环境中先做出可运行结果
+
+### 5.2 选型边界
+
+本设计不把 `Mono` 写死为脚本系统唯一实现，而是将其作为第一实现：
+
+- 对外暴露 `IScriptRuntime` / `ScriptEngine` 抽象
+- `MonoScriptRuntime` 作为第一套后端
+- 后续如有需要，可以演进到 `CoreCLR` 或其他运行时
+
+### 5.3 第一阶段不做的运行时能力
+
+Mono 相关的以下复杂能力不进入第一阶段：
+
+- 域热重载
+- 编辑器内自动重编译后重载
+- 托管调试器接入
+- 发布态 AOT
+
+第一阶段仅要求：
+
+- 初始化运行时
+- 加载核心程序集
+- 加载用户程序集
+- 发现脚本类
+- 实例化对象
+- 调用生命周期
+- 读写托管字段
+
+---
+
+## 6. 模块划分
+
+### 6.1 原生侧模块
+
+建议在 `engine` 内新增 `Scripting` 模块：
+
+```text
+engine/
+├── include/XCEngine/Scripting/
+│   ├── ScriptEngine.h
+│   ├── IScriptRuntime.h
+│   ├── ScriptAssembly.h
+│   ├── ScriptClass.h
+│   ├── ScriptInstance.h
+│   ├── ScriptField.h
+│   ├── ScriptFieldStorage.h
+│   ├── ScriptGlue.h
+│   └── ScriptComponent.h
+└── src/Scripting/
+    ├── ScriptEngine.cpp
+    ├── ScriptGlue.cpp
+    ├── ScriptComponent.cpp
+    └── Mono/
+        ├── MonoScriptRuntime.cpp
+        ├── MonoScriptClass.cpp
+        └── MonoScriptAssembly.cpp
+```
+
+### 6.2 托管侧模块
+
+建议新增托管核心库 `ScriptCore`：
+
+```text
+managed/
+├── XCEngine.ScriptCore/
+│   ├── XCEngine.ScriptCore.csproj
+│   ├── Object.cs
+│   ├── Component.cs
+│   ├── Behaviour.cs
+│   ├── MonoBehaviour.cs
+│   ├── GameObject.cs
+│   ├── Transform.cs
+│   ├── Debug.cs
+│   ├── Time.cs
+│   └── InternalCalls.cs
+└── GameScripts/
+    ├── GameScripts.csproj
+    └── Scripts/*.cs
+```
+
+### 6.3 程序集分层
+
+程序集分为两层：
+
+- `XCEngine.ScriptCore.dll`
+  - 由引擎维护
+  - 提供托管基类和引擎 API 包装
+- `GameScripts.dll`
+  - 由项目侧维护
+  - 编写具体游戏脚本
+
+关系如下：
+
+```text
+GameScripts.dll
+    └── 引用 XCEngine.ScriptCore.dll
+
+Engine Core
+    ├── 先加载 XCEngine.ScriptCore.dll
+    └── 再加载 GameScripts.dll
+```
+
+---
+
+## 7. 对象模型
+
+### 7.1 托管侧模型
+
+托管侧应当采用接近 Unity 的对象层次：
+
+```text
+Object
+└── Component
+    └── Behaviour
+        └── MonoBehaviour
+```
+
+其中：
+
+- `Object`：基础托管对象
+- `Component`：挂载到 `GameObject` 上的托管组件基类
+- `Behaviour`：带 `enabled` 语义的组件
+- `MonoBehaviour`：用户脚本直接继承的基类
+
+### 7.2 原生挂载模型
+
+原生侧脚本挂载使用 `ScriptComponent`，而不是 `ScriptContainerComponent`。
+
+原因如下：
+
+- 更符合 Unity 认知模型
+- 更容易与现有 `GameObject::AddComponent<T>` 思路对齐
+- 更容易在未来做 Inspector 级脚本组件显示
+- 更容易把字段序列化与组件实例对应起来
+
+建议 `ScriptComponent` 至少包含：
+
+- `scriptComponentUUID`
+- `assemblyName`
+- `namespaceName`
+- `className`
+- `enabled`
+- `fieldStorage`
+
+推荐接口示意：
+
+```cpp
+class ScriptComponent : public Component {
+public:
+    std::string GetName() const override { return "Script"; }
+
+    const std::string& GetAssemblyName() const;
+    const std::string& GetNamespaceName() const;
+    const std::string& GetClassName() const;
+    std::string GetFullClassName() const;
+
+    uint64_t GetScriptComponentUUID() const;
+    bool IsRuntimeValid() const;
+
+    void Serialize(std::ostream& os) const override;
+    void Deserialize(std::istream& is) override;
+
+private:
+    uint64_t m_scriptComponentUUID = 0;
+    std::string m_assemblyName = "GameScripts";
+    std::string m_namespaceName;
+    std::string m_className;
+    ScriptFieldStorage m_fieldStorage;
+};
+```
+
+### 7.3 多脚本挂载
+
+一个 `GameObject` 应允许挂载多个 `ScriptComponent`。
+
+这与 Unity 保持一致：
+
+- 同一个对象可以挂多个不同脚本
+- 同一个脚本是否允许重复挂载，由后续属性或规则控制
+- 第一阶段不做“禁止重复挂载”的复杂策略
+
+---
+
+## 8. 身份模型与序列化要求
+
+### 8.1 必须使用 UUID，而不是运行时 ID
+
+脚本系统中，托管实例与原生对象的稳定绑定必须建立在 `UUID` 之上，而不是当前的自增 `ID`。
+
+原因如下：
+
+- 运行时场景复制不能依赖自增 ID 稳定
+- 脚本字段里的对象引用必须有稳定键
+- editor 与 runtime 之间的对象映射必须有稳定键
+- 单元测试和场景恢复也需要稳定身份
+
+因此需要补齐以下要求：
+
+- `GameObject UUID` 进入场景序列化
+- 场景反序列化时恢复 `UUID`
+- `ScriptComponent` 自身也应有持久化 UUID
+
+### 8.2 第一阶段字段序列化策略
+
+第一阶段的脚本字段序列化原则如下：
+
+- 只序列化 `ScriptComponent` 的字段缓存
+- 只序列化脚本作者显式设置的字段值
+- 运行时脚本执行过程中修改的值，不自动回写场景
+
+这与 Unity 的 Play 模式行为一致：
+
+- Play 中的运行时改动不应直接污染编辑数据
+
+### 8.3 第一阶段字段支持范围
+
+建议第一阶段先支持：
+
+- `float`
+- `double`
+- `bool`
+- `int32`
+- `uint64`
+- `string`
+- `Vector2`
+- `Vector3`
+- `Vector4`
+- `GameObject` 引用
+
+第一阶段不要求支持：
+
+- `List<T>`
+- 自定义托管结构体
+- 嵌套对象图
+- 泛型容器
+- 资源引用对象选择器
+
+---
+
+## 9. 生命周期设计
+
+### 9.1 目标生命周期
+
+脚本系统最终应支持以下 Unity 风格生命周期：
+
+- `Awake`
+- `OnEnable`
+- `Start`
+- `FixedUpdate`
+- `Update`
+- `LateUpdate`
+- `OnDisable`
+- `OnDestroy`
+
+### 9.2 第一阶段生命周期闭环
+
+第一阶段就应当把上述生命周期的原生调度链路设计好，哪怕 editor 尚未接入。
+
+建议运行时流程如下：
+
+#### `Scene` 运行时启动
+
+1. `ScriptEngine::OnRuntimeStart(scene)`
+2. 遍历场景中全部激活对象
+3. 找到所有 `ScriptComponent`
+4. 为每个组件创建托管 `MonoBehaviour` 实例
+5. 写入原生对象 UUID / 组件 UUID / 基础上下文
+6. 应用序列化字段缓存
+7. 调用 `Awake`
+8. 若对象激活且组件启用，调用 `OnEnable`
+9. 标记“等待 Start”
+
+#### 每帧执行
+
+- 物理阶段：`FixedUpdate`
+- 普通阶段：`Update`
+- 后处理阶段：`LateUpdate`
+- 对于尚未执行 `Start` 的脚本，在第一次普通帧前先调用 `Start`
+
+#### 运行时停止
+
+1. 对仍处于启用状态的脚本调用 `OnDisable`
+2. 对所有脚本调用 `OnDestroy`
+3. 清理托管实例表
+4. 清理运行时场景上下文
+
+### 9.3 对现有引擎的前置要求
+
+为了让脚本生命周期符合预期，现有引擎需要补齐以下地基：
+
+- `Scene` 更新必须递归整个层级，而不是只更新根对象
+- `Start` 必须具备“一次且仅一次”语义
+- `SetActive` 必须驱动 `OnEnable/OnDisable`
+- 运行时场景启动与停止必须显式化
+- 创建对象时不应直接把“编辑态创建”与“运行态 Awake”混为一谈
+
+这些工作虽然不都属于脚本模块，但它们是脚本模块的直接运行前提。
+
+---
+
+## 10. 原生与托管之间的桥接
+
+### 10.1 桥接方式
+
+第一阶段使用 `InternalCall`：
+
+- 托管侧通过 `MethodImplOptions.InternalCall` 声明方法
+- 原生侧通过 `mono_add_internal_call` 注册
+
+### 10.2 第一阶段最小 API 集
+
+第一阶段建议只暴露最小必需 API：
+
+- `Debug.Log / LogWarning / LogError`
+- `Time.deltaTime`
+- `GameObject.GetName / SetName`
+- `GameObject.GetTransform`
+- `Component.GetGameObject`
+- `GameObject.HasComponent<T>`
+- `GameObject.GetComponent<T>`
+- `Transform` 的本地位置 / 旋转 / 缩放
+
+这套 API 足够覆盖以下测试与最小演示：
+
+- 变换脚本
+- 旋转/移动脚本
+- 生命周期日志验证
+- 组件访问验证
+
+第一阶段不建议优先暴露：
+
+- 物理 API
+- 渲染 API
+- 音频 API
+- 输入系统
+- 资源系统
+
+原因很简单：
+
+- 第一阶段以单元测试闭环为主
+- 暴露面越大，绑定维护成本越高
+- 当前这些系统本身仍在演进
+
+---
+
+## 11. 类发现与实例管理
+
+### 11.1 脚本类发现规则
+
+用户脚本类应满足以下条件才被视为可挂载脚本：
+
+- 定义在 `GameScripts.dll`
+- 非抽象类
+- 继承 `XCEngine.MonoBehaviour`
+
+### 11.2 缓存结构
+
+原生运行时需要缓存以下信息：
+
+- 程序集表
+- 脚本类表
+- 方法句柄表
+- 字段元数据表
+- 运行时实例表
+
+建议实例表键使用：
+
+- `GameObjectUUID + ScriptComponentUUID`
+
+而不是：
+
+- 内存地址
+- 组件在容器中的索引
+- 自增 ID
+
+### 11.3 方法缓存
+
+每个脚本类应缓存常用生命周期方法句柄：
+
+- `Awake`
+- `OnEnable`
+- `Start`
+- `FixedUpdate`
+- `Update`
+- `LateUpdate`
+- `OnDisable`
+- `OnDestroy`
+
+这样可以避免每帧按字符串查找方法。
+
+---
+
+## 12. 单元测试优先策略
+
+### 12.1 原则
+
+第一阶段脚本模块不依赖 editor，因此验证策略以单元测试和最小运行时测试为主。
+
+### 12.2 测试目录建议
+
+```text
+tests/
+└── Scripting/
+    ├── unit/
+    │   ├── test_script_runtime.cpp
+    │   ├── test_script_metadata.cpp
+    │   ├── test_script_component.cpp
+    │   ├── test_script_fields.cpp
+    │   └── CMakeLists.txt
+    └── managed/
+        ├── XCEngine.ScriptCore/
+        └── TestScripts/
+```
+
+### 12.3 第一阶段必须覆盖的测试
+
+#### 运行时初始化
+
+- 能初始化脚本运行时
+- 能加载 `ScriptCore`
+- 能加载测试脚本程序集
+
+#### 类发现
+
+- 只发现继承 `MonoBehaviour` 的类
+- 忽略抽象类
+- 忽略普通工具类
+
+#### 生命周期
+
+- 能创建托管实例
+- 能按顺序触发 `Awake -> OnEnable -> Start -> Update`
+- 能在停止时触发 `OnDisable -> OnDestroy`
+
+#### 组件桥接
+
+- 脚本能访问 `GameObject`
+- 脚本能访问 `Transform`
+- 脚本能访问最小组件 API
+
+#### 字段系统
+
+- 能发现公共字段
+- 能读写字段
+- 字段缓存可回填到托管实例
+- 场景序列化后字段值不丢失
+
+#### 多脚本对象
+
+- 同一 `GameObject` 上多个 `ScriptComponent` 都可实例化
+- 不同脚本实例之间不会串字段
+
+#### UUID 绑定
+
+- 运行时复制或反序列化后仍可稳定恢复脚本绑定键
+
+### 12.4 第一阶段不要求的测试
+
+- editor Inspector UI
+- 热重载
+- 编译器输出面板
+- 文件监听
+- 资源拖拽
+
+---
+
+## 13. 建议的实现顺序
+
+### 阶段 A：补运行时地基
+
+先补以下基础能力：
+
+- `GameObject UUID` 序列化
+- 层级递归更新
+- `Start` 一次性语义
+- `SetActive` 对生命周期的影响
+- `Scene` 运行时启动/停止接口
+
+### 阶段 B：脚本最小闭环
+
+完成：
+
+- `Scripting` 模块骨架
+- `ScriptComponent`
+- `MonoScriptRuntime`
+- `XCEngine.ScriptCore.dll`
+- `GameScripts.dll`
+- 最小 `InternalCall`
+
+### 阶段 C：字段与序列化
+
+完成：
+
+- 脚本字段元数据
+- 字段缓存
+- `ScriptComponent` 序列化/反序列化
+- 字段相关单元测试
+
+### 阶段 D：最小运行时演示
+
+在不依赖 editor 的前提下完成：
+
+- 纯运行时测试场景
+- 一个或两个最小脚本示例
+- Play 级别运行验证
+
+### 阶段 E：editor 集成
+
+后续再做：
+
+- 脚本组件 Inspector
+- 类选择器
+- 编译按钮
+- 错误输出
+- 重载流程
+
+---
+
+## 14. 与 editor 的关系
+
+第一阶段文档明确规定：
+
+- C# 脚本模块**不依赖 editor 完整落地**
+- editor 相关工作全部后置
+- editor 相关缺口统一记录在 `docs/issues`
+
+第一阶段唯一允许与 editor 共用的内容是：
+
+- 场景序列化格式
+- `GameObject UUID` 语义
+- 运行时场景副本的总体设计方向
+
+除此之外，不应把脚本模块第一阶段实现建立在 editor 已具备以下能力的假设上：
+
+- Play/Simulate 控制条
+- Inspector 自定义字段绘制
+- 项目内脚本自动编译
+- 脚本异常面板
+
+---
+
+## 15. 风险与权衡
+
+### 15.1 Mono 依赖
+
+风险：
+
+- Windows 环境需要显式安装或打包 Mono
+- CMake 配置与发布路径管理会变复杂
+
+权衡：
+
+- 第一阶段优先解决“能跑起来”的问题
+- 运行时抽象保留未来替换空间
+
+### 15.2 生命周期与现有引擎实现的偏差
+
+风险：
+
+- 如果继续保留当前“创建对象就立即 `Awake`”的行为，脚本生命周期会混乱
+
+权衡：
+
+- 脚本系统建设必须带动运行时生命周期整理
+
+### 15.3 字段系统范围
+
+风险：
+
+- 一开始就追求完整序列化会让范围失控
+
+权衡：
+
+- 第一阶段只做基础类型与少量引用类型
+- 复杂容器和高级序列化后置
+
+### 15.4 editor 后置
+
+风险：
+
+- 第一阶段用户体验不完整
+
+权衡：
+
+- 可以显著降低实现风险
+- 可以先通过单测和运行时样例把底层做稳
+
+---
+
+## 16. 最终结论
+
+XCEngine 的 C# 脚本系统应当采用：
+
+- `ScriptComponent + MonoBehaviour`
+- `ScriptCore + GameScripts` 双程序集结构
+- `InternalCall` 桥接
+- `Mono` 作为第一套运行时实现
+- `UUID` 作为绑定与序列化的稳定身份
+- 第一阶段只做运行时与单元测试，不依赖 editor
+
+这条路线既保留了 Unity 风格的一致性，也能适配当前工程实际进度。
+
+第一阶段的成功标准不是“Inspector 能编辑脚本字段”，而是：
+
+- 能加载脚本程序集
+- 能发现脚本类
+- 能在场景运行时驱动 `MonoBehaviour`
+- 能通过单元测试验证生命周期、字段和绑定语义
+
+达到这一点后，再进入 editor 集成阶段，工程风险会显著更低。