docs: update scripting API docs
This commit is contained in:
@@ -6,7 +6,7 @@
|
||||
|
||||
**头文件**: `XCEngine/Scripting/ScriptEngine.h`
|
||||
|
||||
**描述**: 当前脚本系统的总调度器，负责运行时启停、脚本实例追踪、生命周期调用与字段模型拼装。
|
||||
**描述**: 当前脚本系统的总调度器，负责运行时启停、脚本实例追踪、生命周期调用、脚本类发现和字段模型拼装。
|
||||
|
||||
## 概览
|
||||
|
||||
@@ -19,9 +19,11 @@
|
||||
当前它的核心职责包括：
|
||||
|
||||
- 在运行时开始时收集场景中的脚本组件并建立追踪表。
|
||||
- 订阅 `Scene::OnGameObjectCreated()`，把运行中创建的新对象也纳入脚本追踪。
|
||||
- 根据对象激活状态、组件启用状态和脚本类绑定状态决定脚本是否应当运行。
|
||||
- 按顺序创建实例、调用 `Awake / OnEnable / Start / Update...`。
|
||||
- 在运行时字段、本地字段缓存和类元数据之间建立一致的读取模型。
|
||||
- 在运行时字段、本地字段缓存、类元数据和类默认值之间建立一致的读取模型。
|
||||
- 为编辑器/Inspector 提供脚本类列表、字段模型、批量写入和清除覆盖能力。
|
||||
|
||||
## 生命周期
|
||||
|
||||
@@ -43,6 +45,17 @@
|
||||
|
||||
这说明当前生命周期状态是显式状态机，而不是每次调用都从托管世界反查。
|
||||
|
||||
## 脚本类与字段模型
|
||||
|
||||
除了生命周期调度，`ScriptEngine` 还负责把运行时暴露成编辑器可消费的数据接口：
|
||||
|
||||
- `TryGetAvailableScriptClasses()` 返回排序后的 `ScriptClassDescriptor` 列表，并可按程序集过滤。
|
||||
- `TryGetScriptFieldModel()` 会把类声明字段、运行时默认值、存储覆盖值和活体托管值融合成 `ScriptFieldModel`。
|
||||
- `ApplyScriptFieldWrites()` 会逐项返回 `Applied / UnknownField / TypeMismatch / StoredOnlyField` 等状态。
|
||||
- `ClearScriptFieldOverrides()` 会把声明字段重置回类默认值，并删除本地存储中的覆盖项。
|
||||
|
||||
这也是当前 Inspector 和脚本字段编辑工具最该依赖的 API 面。
|
||||
|
||||
## 线程语义
|
||||
|
||||
- 当前实现没有锁。
|
||||
@@ -53,8 +66,9 @@
|
||||
|
||||
- 只跟踪当前运行场景里的脚本组件。
|
||||
- `Start` 生命周期会在第一次 `OnUpdate()` 前补发一次，而不是在 `OnRuntimeStart()` 里立即调用。
|
||||
- `TrySetScriptFieldValue()` 只有在后端能返回类字段元数据时，才会强校验字段名和类型。
|
||||
- `TryGetScriptFieldModel()` 会把类元数据、运行时值和本地存储值融合成一份快照模型，这对调试和编辑器非常重要。
|
||||
- `TrySetScriptFieldValue()` 只有在后端能返回类字段元数据时，才会强校验字段名和类型；否则会退回到纯本地存储写入。
|
||||
- `TryGetScriptFieldModel()` 会优先使用运行时返回的类默认值，而不是简单地把每种类型置零。
|
||||
- `TryGetScriptFieldSnapshots()` 在模型成功但字段为空时会返回 `false`，调用方不能把“返回 `false`”简单等同于“接口失败”。
|
||||
|
||||
## 常用访问器
|
||||
|
||||
@@ -78,11 +92,15 @@
|
||||
| [OnScriptComponentEnabled](OnScriptComponentEnabled.md) | 处理脚本组件启用事件。 |
|
||||
| [OnScriptComponentDisabled](OnScriptComponentDisabled.md) | 处理脚本组件禁用事件。 |
|
||||
| [OnScriptComponentDestroyed](OnScriptComponentDestroyed.md) | 处理脚本组件销毁事件。 |
|
||||
| [OnScriptComponentClassChanged](OnScriptComponentClassChanged.md) | 处理脚本类绑定变化，销毁旧实例并按新类重建跟踪。 |
|
||||
| [HasTrackedScriptComponent](HasTrackedScriptComponent.md) | 查询某组件是否被跟踪。 |
|
||||
| [HasRuntimeInstance](HasRuntimeInstance.md) | 查询某组件是否已有运行时实例。 |
|
||||
| [GetTrackedScriptCount](GetTrackedScriptCount.md) | 返回当前跟踪脚本数。 |
|
||||
| [TryGetAvailableScriptClasses](TryGetAvailableScriptClasses.md) | 返回可绑定脚本类列表。 |
|
||||
| [TrySetScriptFieldValue](TrySetScriptFieldValue.md) | 写脚本字段。 |
|
||||
| [TryGetScriptFieldValue](TryGetScriptFieldValue.md) | 读脚本字段。 |
|
||||
| [ApplyScriptFieldWrites](ApplyScriptFieldWrites.md) | 批量写脚本字段并返回逐项状态。 |
|
||||
| [ClearScriptFieldOverrides](ClearScriptFieldOverrides.md) | 批量清理字段覆盖并恢复默认值。 |
|
||||
| [TryGetScriptFieldModel](TryGetScriptFieldModel.md) | 构建完整字段模型。 |
|
||||
| [TryGetScriptFieldSnapshots](TryGetScriptFieldSnapshots.md) | 直接返回字段快照数组。 |
|
||||
|
||||
@@ -91,6 +109,7 @@
|
||||
- `engine/src/Scripting/ScriptEngine.cpp`
|
||||
- `tests/scripting/test_script_engine.cpp`
|
||||
- `tests/Scene/test_scene_runtime.cpp`
|
||||
- `tests/scripting/test_mono_script_runtime.cpp`
|
||||
|
||||
## 相关文档
|
||||
|
||||
|
||||
Reference in New Issue
Block a user