288 lines
11 KiB
Markdown
288 lines
11 KiB
Markdown
# 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 重构稳定后，再补组件字段的可视化选择器。
|