XCEngine/docs/api/XCEngine/Scene/SceneRuntime/SceneRuntime.md

SceneRuntime

命名空间: XCEngine::Components

类型: class

头文件: XCEngine/Scene/SceneRuntime.h

描述: 把 Scene 的逐帧更新与 ScriptEngine 的运行时生命周期绑在一起的轻量执行器。

概览

SceneRuntime 不是场景数据本身，而是“让一个 Scene 真正跑起来”的那层对象。当前职责主要有两件：

• 管理“当前正在运行哪一个场景”。
• 在每个帧阶段先驱动脚本，再驱动原生组件更新。

这种拆分和 Unity 里“Scene 是数据容器，PlayerLoop/Runtime 才是执行者”的思路接近。好处是场景对象本身可以继续承担加载、保存和对象组织职责，而运行态切换、脚本启动和帧阶段调度则集中在一个小类里。

生命周期

• Start 会先停止旧运行时，再接管新场景。
• Stop 会通知 ScriptEngine 结束运行，并清空当前场景。
• 运行中 GetScene() 返回当前绑定场景，IsRunning() 表示是否处于运行状态。

线程语义

• 当前实现没有内部同步。
• Start()、Stop() 和三类帧更新函数都应视为主线程 API。

当前实现边界

• 只有场景本身 IsActive() 为真时，帧更新才会继续执行。
• 每个阶段都先调 ScriptEngine，再调 Scene 本体，因此脚本改动会在同一帧被后续原生组件看见。
• SceneRuntime 当前只管理单个活动场景，不负责多场景叠加或异步切换。

公开方法

方法	说明
Start	开始运行一个场景。
Stop	停止当前场景运行。
FixedUpdate	驱动物理步长阶段。
Update	驱动常规逐帧更新阶段。
LateUpdate	驱动后更新阶段。

真实行为依据

• engine/src/Scene/SceneRuntime.cpp
• tests/Scene/test_scene_runtime.cpp

这些测试明确验证了：

• 启停会转发到 ScriptEngine。
• 脚本生命周期调用先于原生组件。
• 非活动场景会跳过帧执行。
• 切到新场景前会先停掉旧场景。

相关文档

• Scene
• ScriptEngine
• Scene Lifecycle And Serialization