XCEngine/docs/api/XCEngine/Scripting/ScriptEngine/ScriptEngine.md

ScriptEngine

命名空间: XCEngine::Scripting

类型: class (singleton)

头文件: XCEngine/Scripting/ScriptEngine.h

描述: 当前脚本系统的总调度器，负责运行时启停、脚本实例追踪、生命周期调用与字段模型拼装。

概览

ScriptEngine 是当前脚本模块里最重要的原生协调者。它自己不执行脚本字节码，也不保存场景数据，而是负责把下面几层真正串起来：

• SceneRuntime 提供“场景开始运行/停止运行/每帧更新”的入口。
• ScriptComponent 提供脚本绑定与字段缓存。
• IScriptRuntime 提供具体脚本后端能力。

当前它的核心职责包括：

• 在运行时开始时收集场景中的脚本组件并建立追踪表。
• 根据对象激活状态、组件启用状态和脚本类绑定状态决定脚本是否应当运行。
• 按顺序创建实例、调用 Awake / OnEnable / Start / Update...。
• 在运行时字段、本地字段缓存和类元数据之间建立一致的读取模型。

生命周期

• Get 返回进程级单例。
• 默认运行时是内部持有的 NullScriptRuntime。
• SetRuntime 可替换具体后端；传 nullptr 时回退到空运行时。
• OnRuntimeStart / OnRuntimeStop 管理整条脚本运行链路。

内部追踪模型

当前 ScriptEngine 通过 (gameObjectUUID, scriptComponentUUID) 唯一标识一个脚本实例状态，并保存：

• context
• instanceCreated
• awakeCalled
• enabled
• startCalled
• startPending

这说明当前生命周期状态是显式状态机，而不是每次调用都从托管世界反查。

线程语义

• 当前实现没有锁。
• 应视为主线程运行时服务。
• 不应该在并发线程里同时改脚本组件集合和驱动脚本生命周期。

当前实现边界

• 只跟踪当前运行场景里的脚本组件。
• Start 生命周期会在第一次 OnUpdate() 前补发一次，而不是在 OnRuntimeStart() 里立即调用。
• TrySetScriptFieldValue() 只有在后端能返回类字段元数据时，才会强校验字段名和类型。
• TryGetScriptFieldModel() 会把类元数据、运行时值和本地存储值融合成一份快照模型，这对调试和编辑器非常重要。

常用访问器

• GetRuntime()
• IsRuntimeRunning()
• GetRuntimeScene()

这些是简单内联访问器，当前文档重点放在影响状态机和运行行为的核心方法上。

公开方法

方法	说明
Get	获取全局脚本引擎实例。
SetRuntime	设置具体脚本后端。
OnRuntimeStart	启动脚本运行时。
OnRuntimeStop	停止脚本运行时。
OnFixedUpdate	驱动固定步长脚本更新。
OnUpdate	驱动常规逐帧更新，并补发 Start。
OnLateUpdate	驱动后更新。
OnScriptComponentEnabled	处理脚本组件启用事件。
OnScriptComponentDisabled	处理脚本组件禁用事件。
OnScriptComponentDestroyed	处理脚本组件销毁事件。
HasTrackedScriptComponent	查询某组件是否被跟踪。
HasRuntimeInstance	查询某组件是否已有运行时实例。
GetTrackedScriptCount	返回当前跟踪脚本数。
TrySetScriptFieldValue	写脚本字段。
TryGetScriptFieldValue	读脚本字段。
TryGetScriptFieldModel	构建完整字段模型。
TryGetScriptFieldSnapshots	直接返回字段快照数组。

真实行为依据

• engine/src/Scripting/ScriptEngine.cpp
• tests/scripting/test_script_engine.cpp
• tests/Scene/test_scene_runtime.cpp

相关文档

• IScriptRuntime
• ScriptComponent
• ScriptFieldStorage
• Scripting Runtime And Field Model