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

# SceneManager

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

**类型**: `class (singleton)`

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

**描述**: 维护已加载场景集合并提供活动场景入口的全局场景管理器。

## 概述

`SceneManager` 负责的是“场景注册表”和“当前活动场景指针”，而不是完整的场景调度框架。它内部维护：

- `m_scenes`，按字符串 key 保存场景唯一所有权。
- `m_activeScene`，保存当前活动场景裸指针。
- 三个场景级事件对象。

这种设计对应很多商业引擎里的“全局场景入口”思路：上层系统通过一个统一位置拿到活动场景或切换已加载场景，而不是自己持有所有场景集合。

## 所有权与 key 规则

- [CreateScene](CreateScene.md) 创建的场景以传入 `name` 作为 map key。
- [LoadScene](LoadScene.md) 加载的场景以“文件名 stem”作为 map key，而不是文件内部保存的 `scene=` 名称。
- `GetScene()`、`UnloadScene(const std::string&)` 和 `SetActiveScene(const std::string&)` 都使用这个内部 key。
- 如果场景对象后续调用 `Scene::SetName()` 改名，当前 key 不会自动重建。

## 当前实现边界

- 当前没有锁；不适合并发加载或并发卸载。
- [LoadSceneAsync](LoadSceneAsync.md) 目前不是异步，只是同步调用再执行回调。
- [LoadSceneAsync](LoadSceneAsync.md) 的回调查找使用原始 `filePath` 做 key，常见情况下会得到 `nullptr`。
- `SceneManager` 的活动场景指针，与 `Scene::IsActive()` / `SetActive()` 当前没有自动同步关系。
- [SetActiveScene](SetActiveScene.md) 的指针重载不会校验传入场景是否真的来自 `m_scenes`。
- 如果使用相同 key 重复创建或加载场景，旧场景会被新场景替换；这可能让先前缓存的裸指针失效。

## 线程语义

- 当前没有内部同步；应把它当作主线程系统使用。

## 公开方法

| 方法 | 说明 |
|------|------|
| [Get](Get.md) | 获取单例。 |
| [CreateScene](CreateScene.md) | 创建并登记场景。 |
| [LoadScene](LoadScene.md) | 从文件加载并登记场景。 |
| [LoadSceneAsync](LoadSceneAsync.md) | 当前的同步包装“异步”加载接口。 |
| [UnloadScene](UnloadScene.md) | 卸载场景。 |
| [SetActiveScene](SetActiveScene.md) | 设置活动场景。 |
| [GetActiveScene](GetActiveScene.md) | 获取活动场景。 |
| [GetScene](GetScene.md) | 按 key 获取场景。 |
| [GetAllScenes](GetAllScenes.md) | 获取全部已登记场景。 |
| [OnSceneLoaded](OnSceneLoaded.md) | 访问场景加载事件。 |
| [OnSceneUnloaded](OnSceneUnloaded.md) | 访问场景卸载事件。 |
| [OnActiveSceneChanged](OnActiveSceneChanged.md) | 访问活动场景切换事件。 |

## 相关文档

- [当前模块](../Scene.md)
- [Scene](../Scene/Scene.md)
- [Scene Lifecycle And Serialization](../../../_guides/Scene/Scene-Lifecycle-And-Serialization.md)