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。
• 序列化/反序列化会持久化 UUID、脚本类绑定和字段存储内容。

所有权

• ScriptComponent 本身归 GameObject 所有。
• ScriptFieldStorage 作为成员对象直接内嵌，不单独分配。

当前实现边界

• SetScriptClass() 只有在“之前没有脚本类，现在有了”这个转换点，才会主动通知 ScriptEngine::OnScriptComponentEnabled()。
• 单纯修改已有脚本类名，不会自动触发一轮完整的重绑定流程。
• 反序列化使用引擎私有的分号分隔文本格式，不是通用 JSON/YAML。

常用访问器

• GetAssemblyName() / SetAssemblyName()
• GetNamespaceName() / SetNamespaceName()
• GetClassName() / SetClassName()
• GetScriptComponentUUID()

这些访问器大多是简单内联函数，因此当前文档重点放在会改变生命周期或序列化语义的核心方法上。

公开方法

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

真实行为依据

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

相关文档

• ScriptEngine
• ScriptFieldStorage
• Scripting Runtime And Field Model