# SceneRuntime

**命名空间**: `XCEngine::Components`

**类型**: `class`

**头文件**: `XCEngine/Scene/SceneRuntime.h`

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

## 概览

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

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

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

## 生命周期

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

## 线程语义

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

## 当前实现边界

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

## 公开方法

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

## 真实行为依据

- `engine/src/Scene/SceneRuntime.cpp`
- `tests/Scene/test_scene_runtime.cpp`

这些测试明确验证了：

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

## 相关文档

- [Scene](../Scene/Scene.md)
- [ScriptEngine](../../Scripting/ScriptEngine/ScriptEngine.md)
- [Scene Lifecycle And Serialization](../../../_guides/Scene/Scene-Lifecycle-And-Serialization.md)