docs: update scripting API docs

This commit is contained in:
2026-04-02 22:23:29 +08:00
parent ec2891b16b
commit 3f9e286637
25 changed files with 776 additions and 76 deletions

View File

@@ -10,7 +10,7 @@
- `IScriptRuntime`
- `MonoScriptRuntime`
这份指南的目标,是把它们放回同一条真实运行链路里解释清楚。
这份指南的目标,是把它们放回同一条真实运行链路里解释清楚,并明确“类默认值、存储覆盖值、活体托管值”这三层数据是怎么叠加的
## 一句话理解当前架构
@@ -48,12 +48,25 @@
这和 Unity Inspector 里的“脚本字段序列化层”在理念上很接近,但当前实现更轻量,也更直接。
## 运行时里字段值到底有几层
当前字段值至少可能来自三层:
1. 类默认值
来自运行时 `TryGetClassFieldDefaultValues()`Mono 实现会真实构造一个托管对象并读取字段初始化结果。
2. 存储覆盖值
来自 `ScriptFieldStorage`;它会在场景序列化、运行前编辑和生命周期回写之间持续存在。
3. 活体托管值
来自当前运行中的托管实例;`ScriptEngine::TryGetScriptFieldModel()``TryGetScriptFieldValue()` 会优先读这一层。
`ScriptFieldSnapshot` 里的 `valueSource` 就是在说明当前展示值到底来自哪一层。
## 当前生命周期是怎么串起来的
真实顺序如下:
1. `SceneRuntime::Start()` 调用 `ScriptEngine::OnRuntimeStart(scene)`
2. `ScriptEngine` 收集场景里的 `ScriptComponent`
2. `ScriptEngine` 收集场景里的 `ScriptComponent`,并订阅 `Scene::OnGameObjectCreated()`,保证运行中生成的新对象也会被继续追踪
3. 对满足运行条件的组件,调用运行时 `CreateScriptInstance()`
4. 然后按顺序补发 `Awake``OnEnable`
5. 第一次 `OnUpdate()` 前,会先补发一次 `Start`
@@ -85,7 +98,7 @@
- 初始化 Mono 域并加载核心/游戏程序集。
- 发现继承 `MonoBehaviour` 的非抽象脚本类。
- 枚举支持类型的公共实例字段。
- 枚举支持类型的公共实例字段,并读取字段默认值
- 创建托管实例,并注入 `GameObject` / `ScriptComponent` 上下文。
- 通过 internal call 桥接基础引擎 API。
- 生命周期调用后把已存储字段同步回本地缓存。
@@ -112,6 +125,16 @@
这是一种更偏工程安全的选择。
## 类切换为什么要走 `SetScriptClass()`
当前运行时重绑定逻辑并不是“任意改三个字符串都能触发”。
- `ScriptComponent::SetScriptClass()` / `ClearScriptClass()` 会通知 `ScriptEngine`
- 运行时中的 `ScriptEngine::OnScriptComponentClassChanged()` 会停掉旧实例,再按新类重新创建和跟踪。
- `SetAssemblyName()` / `SetNamespaceName()` / `SetClassName()` 只是原始字段 setter不会触发这条流程。
也就是说,真正要做脚本类切换时,必须走显式重绑定 API。
## 推荐阅读顺序
如果你第一次接触这个模块,建议按下面顺序看:
@@ -123,6 +146,7 @@
5. [ScriptEngine](../../XCEngine/Scripting/ScriptEngine/ScriptEngine.md)
6. [IScriptRuntime](../../XCEngine/Scripting/IScriptRuntime/IScriptRuntime.md)
7. [MonoScriptRuntime](../../XCEngine/Scripting/Mono/MonoScriptRuntime/MonoScriptRuntime.md)
8. [Project Script Assembly And Field Sync](Project-Script-Assembly-And-Field-Sync.md)
## 相关 API