XCEngine/docs/api/XCEngine/Scripting/ScriptComponent/ScriptComponent.md

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	创建组件并生成 UUID。
SetScriptClass	设置脚本类绑定。
ClearScriptClass	清空脚本类绑定。
HasScriptClass	判断当前是否已经绑定脚本类。
GetFullClassName	返回带命名空间的完整类名。
GetFieldStorage	访问持久化字段缓存。
OnEnable	通知 ScriptEngine 组件启用。
OnDisable	通知 ScriptEngine 组件禁用。
OnDestroy	通知 ScriptEngine 组件销毁。
Serialize	把组件状态写出到文本流。
Deserialize	从文本流恢复组件状态。

真实行为依据

• engine/src/Scripting/ScriptComponent.cpp
• tests/scripting/test_script_component.cpp
• tests/scripting/test_script_engine.cpp

相关文档

• ScriptEngine
• ScriptFieldStorage
• Scripting Runtime And Field Model