XCEngine/docs/plan/C#脚本模块下一阶段计划.md

C#脚本模块下一阶段计划

日期：2026-04-03

1. 当前阶段判断

C# 脚本模块已经完成了第一阶段的核心闭环，不再是“从 0 到 1 的原型验证”状态，而是进入了“从可运行走向可长期使用”的第二阶段。

当前已经完成的关键能力包括：

1. ScriptComponent + MonoBehaviour 基本运行时模型已经建立
2. MonoScriptRuntime 已经能加载程序集、发现脚本类、创建托管实例、调用生命周期
3. Awake / OnEnable / Start / FixedUpdate / Update / LateUpdate / OnDisable / OnDestroy 已经打通
4. Debug.Log / LogWarning / LogError 已经打通到 native logger
5. Time、Input、GameObject、Transform、Behaviour.enabled、部分内建组件包装已经可用
6. 脚本字段存储、默认值、覆盖值、运行时值三层模型已经建立
7. Play / Pause / Resume / Step 已经能驱动脚本生命周期
8. editor 已经具备脚本类选择、字段 Inspector 编辑、项目脚本程序集重建与重载入口

这意味着下一阶段的重点，不再是“脚本能不能跑”，而是：

1. Unity 风格 API 是否足够严格一致
2. 项目级脚本工作流是否足够稳定
3. 字段系统是否能支撑真实项目使用

---

2. 下一阶段总目标

下一阶段的总目标是：

把当前“可运行的 C# 脚本运行时”收口成“命名、语义、工作流都更接近 Unity 的第一版可用脚本模块”。

具体聚焦三件事：

1. Unity API 严格对齐
2. 项目脚本程序集链路收口
3. 脚本字段系统扩展

---

3. 第一优先级：Unity API 严格对齐

这是当前最高优先级。

原因：

1. 你已经明确要求 API 命名必须和 Unity C# API 保持严格一致
2. 运行时主链路已经可用，当前最需要尽快收口的是 API 契约
3. 如果 API 名字、属性名、行为语义先发散，后面越做越难回收

本阶段需要重点检查和补齐以下几类接口：

3.1 基础对象层

优先补齐 Unity 风格的基础对象模型：

1. Object
2. Component
3. Behaviour
4. MonoBehaviour

重点不是“再做一套功能”，而是统一 API 入口和语义边界。

3.2 GameObject / Component 常用 API

优先补齐最常用、最影响脚本编写体验的 Unity 接口：

1. GetComponent<T>()
2. TryGetComponent<T>(out T)
3. AddComponent<T>()
4. GetComponents<T>()
5. GetComponentInChildren<T>()
6. GetComponentInParent<T>()
7. CompareTag
8. tag
9. layer

其中前四项优先级最高。

3.3 Object 静态入口

优先补齐 Unity 风格最核心的对象静态方法：

1. Object.Destroy
2. Object.Instantiate

这一层非常关键，因为 Unity 用户的很多使用习惯都是围绕 Object 静态 API 建立的。

3.4 Transform 常用缺口补齐

当前 Transform 已经有较完整的空间变换接口，但还需要继续检查 Unity 一致性，重点看：

1. 属性命名
2. 重载形态
3. childCount / GetChild
4. parent / SetParent
5. Translate / Rotate / LookAt
6. 常用便捷属性是否缺失

原则是：

1. 已有 API 尽量不发散出自定义命名
2. 优先补 Unity 常见重载

---

4. 第二优先级：项目脚本程序集链路收口

当前 editor 已经具备：

1. project/Assets 扫描
2. GameScripts.dll 编译
3. Rebuild Scripts
4. Reload Scripts
5. Inspector 脚本类发现

但这一层还没有完全稳定，尤其是：

1. 项目程序集输出目录依赖当前工作区状态
2. 测试环境下 project/Library/ScriptAssemblies 还不稳定
3. editor / 测试 / 项目目录三者之间还缺少更彻底的收口

这一阶段要完成的目标是：

1. project/Assets/*.cs -> Library/ScriptAssemblies/*.dll 变成稳定链路
2. editor 重建后总能看到最新脚本类
3. 对应测试不依赖手工残留文件
4. 项目程序集相关测试可以稳定进入常规回归集

这部分的目标不是继续扩 API，而是把工程化链路做稳。

---

5. 第三优先级：脚本字段系统扩展

当前字段系统已经支持：

1. float
2. double
3. bool
4. int32
5. uint64
6. string
7. Vector2
8. Vector3
9. Vector4
10. GameObject 引用

下一阶段应继续向 Unity 常用字段模型推进，优先顺序建议如下：

1. enum
2. SerializeField 支持
3. private 可序列化字段
4. 组件引用字段
5. 数组 / List
6. 资源引用字段

其中最优先的是：

1. enum
2. [SerializeField]
3. 组件引用字段

因为这三项最直接决定脚本是否能进入“真实可写”阶段。

---

6. editor 集成边界

这一阶段 editor 不再是完全不碰，但仍然不是主战场。

原则是：

1. 只做支撑脚本模块使用所必需的 editor 收口
2. 不把主要精力放在复杂编辑器体验优化上
3. 继续优先保证 runtime、程序集链路、字段模型稳定

本阶段 editor 侧只建议继续做以下范围：

1. 脚本类发现与重建流程稳定性
2. Inspector 字段编辑最小闭环
3. 类型新增后对应字段控件补齐

以下内容暂时不进入主线：

1. 热重载
2. 托管调试器
3. 完整 Console/Exception 调试体验
4. 高级脚本模板与自动生成工具

---

7. 本阶段不做的内容

为避免范围继续膨胀，下一阶段先明确不做：

1. 域重载 / 热重载
2. CoreCLR 切换
3. IL2CPP / AOT
4. 完整 Unity 级别资源 API
5. 复杂序列化对象图
6. 完整调试器接入

这些都可以进入后续阶段，但不应抢占当前优先级。

---

8. 建议执行顺序

建议严格按下面顺序推进：

1. 先做 Unity API 命名与契约收口
2. 再做 项目脚本程序集链路稳定化
3. 再做 字段系统扩展
4. 再做 新增字段类型对应的 Inspector 支持
5. 最后再评估热重载、调试器、异常体验

原因很简单：

1. API 契约不先收口，后面所有脚本都会建立在不稳定接口上
2. 程序集链路不稳定，项目脚本工作流就不可靠
3. 字段系统是把脚本从“可跑”推进到“可用”的关键

---

9. 验收标准

本阶段完成后，至少应满足：

1. 核心托管 API 的命名与 Unity 保持一致，不再出现明显自定义发散
2. Object / GameObject / Component / Behaviour / MonoBehaviour / Transform 的主干接口基本齐全
3. 项目脚本程序集能稳定重建、重载、发现
4. 项目级脚本程序集测试可以稳定跑通
5. Inspector 能编辑扩展后的核心字段类型
6. 脚本模块可以支撑真实项目写出第一批常规 gameplay 脚本

---

10. 当前结论

脚本模块现在已经完成了“第一阶段：核心运行时落地”。

下一阶段不应该再围绕“能不能跑”展开，而应该围绕：

1. Unity API 严格一致
2. 项目工作流稳定
3. 字段系统可用于真实开发

后续执行时，默认按这个优先级推进。

阶段进展 2026-04-03

• 已完成第一步 Unity API 对齐收口：

• 新增 XCEngine.Object 基类。

• 新增 Object.Destroy(Object) 静态销毁入口。

• 新增 GameObject / Component.GetComponentInChildren<T>()。

• 新增 GameObject / Component.GetComponentInParent<T>()。

• 已补齐对应 Mono internal call 与 native 销毁路径。

• 已新增运行时回归用例，验证层级查找、自身命中、组件销毁、GameObject 销毁。

• 已通过 MonoScriptRuntimeTest.* 与 ProjectScriptAssemblyTest.* 相关整组验证。

• 已完成第二步第一小项：GetComponents<T>()

• 已完成第二步第二小项：tag / CompareTag / layer

• GameObject、Component 与 MonoBehaviour 已提供 Unity 风格 tag、layer、CompareTag(string) 入口。

• native GameObject、场景查找、序列化与反序列化已同步收口，FindGameObjectWithTag / FindGameObjectsWithTag 已改为基于 tag。

• 已新增 TagLayerProbe 与对应 C++ / Mono 回归测试，覆盖默认 tag、layer 裁剪、脚本侧读写与场景 roundtrip。

• 相关定向测试全部通过；完整 MonoScriptRuntimeTest.*:ProjectScriptAssemblyTest.* 输出全绿，当前仍存在历史性的 exit code 3 异常，需后续单独跟踪。

• 下一步建议继续做第三小项：Object.Instantiate

• 已完成字段系统第一小项：enum 字段支持

• MonoScriptRuntime 现已支持把常见整数底层的 C# enum 字段纳入脚本字段模型，并按 Int32 进入默认值、存储值、运行时值三层同步链路。

• 已新增 FieldMetadataProbeState / EnumFieldProbeState 探针，覆盖枚举字段发现、默认值提取、运行时写回与场景 roundtrip。

• 已通过新增定向测试，以及完整 ScriptFieldStorage_Test.*:MonoScriptRuntimeTest.*:ProjectScriptAssemblyTest.* 整组验证；输出全绿，exit code 3 仍为既有历史现象。

• 已完成字段系统第二小项：[SerializeField] private 字段支持

• 新增 XCEngine.SerializeField attribute，命名与 Unity 对齐；runtime 字段发现现已支持“public 字段”与“带 [SerializeField] 的 private 字段”双通路。

• 字段筛选已同步排除 static / const / readonly，并新增 SerializeFieldProbe、FieldMetadataProbe 扩展与对应 C++ 回归测试，覆盖默认值提取、存储覆盖、运行时写回与场景 roundtrip。

• ProjectScriptAssemblyTest.* 现改为使用独立的测试项目程序集输出目录，不再依赖真实 project/Library/ScriptAssemblies，避免与 editor / Mono 持有的文件锁互相干扰。

• 已通过完整 ScriptFieldStorage_Test.*:MonoScriptRuntimeTest.*:ProjectScriptAssemblyTest.* 验证；输出全绿，exit code 3 仍为既有历史现象。

• 字段系统下一步建议切到：组件引用字段支持

• 已完成字段系统第三小项：具体组件引用字段支持

• MonoScriptRuntime 现已支持把常用具体组件字段纳入脚本字段模型，包括 Transform、Camera、Light、MeshFilter、MeshRenderer，以及具体脚本类字段（MonoBehaviour 子类）。

• 字段存储层已新增 ScriptFieldType::Component 与 ComponentReference，序列化格式同时保存 gameObjectUUID 与 scriptComponentUUID，从而能区分内建组件引用与脚本组件引用。

• 当前刻意暂不支持抽象基类字段：Component、Behaviour、MonoBehaviour；这样先保证字段定位与场景 roundtrip 语义稳定，不把抽象匹配和 editor 复杂度提前拉进主线。

• 已新增 ComponentFieldMetadataProbe / ComponentFieldProbe 与对应 C++ 回归测试，覆盖字段发现、默认空引用、存储值应用、运行时写回，以及场景 roundtrip 恢复。

• 本步定向测试 ScriptFieldStorage_Test.*:ScriptComponent_Test.*:MonoScriptRuntimeTest.ClassFieldMetadataListsConcreteComponentReferenceFields:MonoScriptRuntimeTest.ClassFieldDefaultValueQueryReturnsNullComponentReferences:MonoScriptRuntimeTest.ComponentReferenceFieldsApplyStoredValuesAndPersistAcrossSceneRoundTrip 全部通过。

• 扩大回归 ScriptFieldStorage_Test.*:MonoScriptRuntimeTest.*:ProjectScriptAssemblyTest.* 日志层面全绿；当前测试进程仍存在历史性的异常退出码现象，需要后续单独跟踪，不是本步引入的问题。

• 字段系统下一步建议切到：资源引用字段，或等 editor Inspector 重构稳定后，再补组件字段的可视化选择器。