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

ScriptEngine::OnRuntimeStart

命名空间: XCEngine::Scripting

类型: method

头文件: XCEngine/Scripting/ScriptEngine.h

签名

void OnRuntimeStart(Components::Scene* scene);

当前实现流程

按 engine/src/Scripting/ScriptEngine.cpp：

1. 先暂存当前 m_runtimeFixedDeltaTime 配置值。
2. 调用 OnRuntimeStop 清理旧运行时。
3. 把暂存的 fixed delta 配置恢复回 m_runtimeFixedDeltaTime。
4. 如果 scene == nullptr，直接返回。
5. 记录 m_runtimeScene，置 m_runtimeRunning = true。
6. 调用当前运行时 m_runtime->OnRuntimeStart(scene)。
7. 订阅 scene->OnGameObjectCreated()，保证运行中创建的新对象也会被脚本系统追踪。
8. 递归收集场景现有的所有 ScriptComponent。
9. 对满足 ShouldScriptRun() 的组件调用 EnsureScriptReady(..., true)，从而创建实例并触发 Awake / OnEnable。

关键语义

• 这一步不会直接触发 Start；Start 留到第一次 OnUpdate 再补发。
• 启动前通过 SetRuntimeFixedDeltaTime 配好的 fixed delta，不会被这次内部 OnRuntimeStop 清掉。
• 订阅场景创建事件，保证 runtime-spawn 出来的对象不会漏掉脚本初始化。
• 这里只会对当前已经满足运行条件的脚本调用 EnsureScriptReady()；未激活对象、禁用组件或未绑定类的组件不会在这里被强行创建实例。

为什么要先 stop 再 start

这种写法看上去有点“重”，但它解决的是工程上一致性问题：

• 避免旧场景残留跟踪状态带进新运行态。
• 保证 fixed delta、场景订阅和实例缓存都回到干净起点。
• 让“重新开始运行”与“第一次开始运行”共享同一条启动路径。

这和商业引擎里 Play 模式切换常见的“全量重建运行时态”思路一致。

真实行为依据

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

相关文档

• SetRuntimeFixedDeltaTime
• OnRuntimeStop
• OnUpdate