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

# Scene

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

**类型**: `module`

**描述**: 提供场景容器、多场景管理入口以及场景运行时调度器。

## 概览

当前 `XCEngine/Scene` 目录里的 public API 主要分成三层：

- [Scene](Scene/Scene.md) 负责对象树、场景级更新和场景序列化。
- [SceneManager](SceneManager/SceneManager.md) 负责多场景注册与活动场景入口。
- [SceneRuntime](SceneRuntime/SceneRuntime.md) 负责把某个场景真正“跑起来”，并和脚本系统衔接。
- [RuntimeLoop](RuntimeLoop/RuntimeLoop.md) 则在 `SceneRuntime` 之上补上 fixed step、暂停和单帧步进这一层时间控制。

这种分层和商业引擎里常见的思路接近：`Scene` 是数据与对象容器，`SceneManager` 负责更高层的场景切换，`SceneRuntime` 负责运行态语义，而 `RuntimeLoop` 则进一步提供可供 editor play mode 复用的时间推进策略。

## 设计要点

- `Scene` 专注对象拥有权、查询和序列化，不直接变成庞大的运行时调度中心。
- `SceneRuntime` 把脚本生命周期和场景更新顺序集中管理，避免脚本系统散落到 `Scene` 内部。
- `RuntimeLoop` 把 fixed/update/late-update 的时间控制从 `SceneRuntime` 再剥出来，便于 pause、step 和 editor play session 复用。
- `SceneManager` 让多场景入口和单个场景数据模型解耦，便于以后扩展更复杂的场景切换策略。
- 场景序列化会尊重组件自己的资源协议；对 mesh / material 项目资产，当前正式持久化身份是 `AssetRef`，而 `builtin://` 这类 virtual resource 才长期依赖显式路径。

## 当前实现边界

- 当前公开类型都位于 `XCEngine::Components` 命名空间，而不是单独的 `XCEngine::Scene` 命名空间，这反映了引擎当前建模历史。
- `SceneRuntime` 目前只管理单个运行中的场景。
- `RuntimeLoop` 当前只是 `SceneRuntime` 的时间控制包装，不是全引擎级 player loop。
- `SceneManager::LoadSceneAsync()` 仍是同步包装，不是完整异步加载系统。
- 场景序列化使用引擎私有文本格式，强调可落地而不是通用交换格式。

## 头文件

- [RuntimeLoop](RuntimeLoop/RuntimeLoop.md) - `RuntimeLoop.h`
- [Scene](Scene/Scene.md) - `Scene.h`
- [SceneManager](SceneManager/SceneManager.md) - `SceneManager.h`
- [SceneRuntime](SceneRuntime/SceneRuntime.md) - `SceneRuntime.h`

## 相关指南

- [Scene Lifecycle And Serialization](../../_guides/Scene/Scene-Lifecycle-And-Serialization.md) - 解释场景容器、运行时调度和序列化之间的关系，以及当前实现的真实限制。

## 相关文档

- [GameObject](../Components/GameObject/GameObject.md)
- [Component](../Components/Component/Component.md)
- [TransformComponent](../Components/TransformComponent/TransformComponent.md)
- [Scripting](../Scripting/Scripting.md)
- [上级目录](../XCEngine.md)
- [API 总索引](../../main.md)