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

Scene

命名空间: XCEngine::Components

类型: module

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

概览

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

• Scene 负责对象树、场景级更新和场景序列化。
• SceneManager 负责多场景注册与活动场景入口。
• SceneRuntime 负责把某个场景真正“跑起来”，并和脚本系统衔接。
• RuntimeLoop 则在 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.h
• Scene - Scene.h
• SceneManager - SceneManager.h
• SceneRuntime - SceneRuntime.h

相关指南

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

相关文档

• GameObject
• Component
• TransformComponent
• Scripting
• 上级目录
• API 总索引