78 lines
3.4 KiB
Markdown
78 lines
3.4 KiB
Markdown
# ScriptComponent
|
||
|
||
**命名空间**: `XCEngine::Scripting`
|
||
|
||
**类型**: `class`
|
||
|
||
**头文件**: `XCEngine/Scripting/ScriptComponent.h`
|
||
|
||
**描述**: 挂在 `GameObject` 上的脚本绑定组件，负责保存脚本类标识、组件 UUID 和字段覆盖存储。
|
||
|
||
## 概览
|
||
|
||
`ScriptComponent` 是脚本系统的数据入口。它本身不执行托管代码，而是保存三类关键信息：
|
||
|
||
- 这个组件绑定的是哪个程序集、命名空间和类。
|
||
- 这个脚本组件自己的稳定 UUID。
|
||
- 这份脚本实例的可持久化字段缓存 `ScriptFieldStorage`。
|
||
|
||
这和 Unity 场景里挂着的 `MonoBehaviour` 槽位很接近，但当前实现更明确地区分了“原生数据层”和“运行时实例层”。
|
||
|
||
## 生命周期
|
||
|
||
- 构造时会生成一个非零随机 `scriptComponentUUID`。
|
||
- 默认程序集名是 `GameScripts`。
|
||
- 首次绑定脚本类时，会通知 `ScriptEngine::OnScriptComponentEnabled()`。
|
||
- 已绑定脚本类发生变化时，会通知 `ScriptEngine::OnScriptComponentClassChanged()`，触发当前运行时实例停机并按新类重建。
|
||
- `ClearScriptClass()` 会保留当前 `assemblyName`，只清空命名空间和类名。
|
||
- 启用、禁用、销毁回调会直接转发给 `ScriptEngine`。
|
||
- 序列化/反序列化会持久化 UUID、脚本类绑定和字段存储内容。
|
||
|
||
## 所有权
|
||
|
||
- `ScriptComponent` 本身归 `GameObject` 所有。
|
||
- `ScriptFieldStorage` 作为成员对象直接内嵌，不单独分配。
|
||
|
||
## 当前实现边界
|
||
|
||
- 只有 `SetScriptClass()` / `ClearScriptClass()` 会通知 `ScriptEngine`；`SetAssemblyName()`、`SetNamespaceName()`、`SetClassName()` 是纯字段写入，不会自动触发重绑定。
|
||
- 反序列化使用引擎私有的分号分隔文本格式，不是通用 JSON/YAML。
|
||
- `SetFieldStorage()` 直接整体覆盖本地字段缓存，不会自动把活体托管实例同步到同一状态。
|
||
|
||
## 常用访问器
|
||
|
||
- `GetAssemblyName()` / `SetAssemblyName()`
|
||
- `GetNamespaceName()` / `SetNamespaceName()`
|
||
- `GetClassName()` / `SetClassName()`
|
||
- `GetScriptComponentUUID()`
|
||
|
||
这些访问器大多是简单内联函数，因此文档重点放在会影响运行时重建、字段语义或序列化行为的方法上。
|
||
|
||
## 公开方法
|
||
|
||
| 方法 | 说明 |
|
||
|------|------|
|
||
| [Constructor](Constructor.md) | 创建组件并生成 UUID。 |
|
||
| [SetScriptClass](SetScriptClass.md) | 设置脚本类绑定。 |
|
||
| [ClearScriptClass](ClearScriptClass.md) | 清空脚本类绑定。 |
|
||
| [HasScriptClass](HasScriptClass.md) | 判断当前是否已经绑定脚本类。 |
|
||
| [GetFullClassName](GetFullClassName.md) | 返回带命名空间的完整类名。 |
|
||
| [GetFieldStorage](GetFieldStorage.md) | 访问持久化字段缓存。 |
|
||
| [OnEnable](OnEnable.md) | 通知 `ScriptEngine` 组件启用。 |
|
||
| [OnDisable](OnDisable.md) | 通知 `ScriptEngine` 组件禁用。 |
|
||
| [OnDestroy](OnDestroy.md) | 通知 `ScriptEngine` 组件销毁。 |
|
||
| [Serialize](Serialize.md) | 把组件状态写出到文本流。 |
|
||
| [Deserialize](Deserialize.md) | 从文本流恢复组件状态。 |
|
||
|
||
## 真实行为依据
|
||
|
||
- `engine/src/Scripting/ScriptComponent.cpp`
|
||
- `tests/scripting/test_script_component.cpp`
|
||
- `tests/scripting/test_script_engine.cpp`
|
||
|
||
## 相关文档
|
||
|
||
- [ScriptEngine](../ScriptEngine/ScriptEngine.md)
|
||
- [ScriptFieldStorage](../ScriptFieldStorage/ScriptFieldStorage.md)
|
||
- [Scripting Runtime And Field Model](../../../_guides/Scripting/Scripting-Runtime-And-Field-Model.md)
|