docs: rebuild Scene API content

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

@@ -6,36 +6,57 @@
 
 **头文件**: `XCEngine/Scene/SceneManager.h`
 
-**描述**: 定义 `XCEngine/Scene` 子目录中的 `SceneManager` public API。
+**描述**: 维护已加载场景集合并提供活动场景入口的全局场景管理器。
 
 ## 概述
 
-`SceneManager.h` 是 `XCEngine/Scene` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`SceneManager` 负责的是“场景注册表”和“当前活动场景指针”，而不是完整的场景调度框架。它内部维护：
 
-## 声明概览
+- `m_scenes`，按字符串 key 保存场景唯一所有权。
+- `m_activeScene`，保存当前活动场景裸指针。
+- 三个场景级事件对象。
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `SceneManager` | `class` | 头文件中的公开声明。 |
+这种设计对应很多商业引擎里的“全局场景入口”思路：上层系统通过一个统一位置拿到活动场景或切换已加载场景，而不是自己持有所有场景集合。
 
-## 公共方法
+## 所有权与 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) | 获取相关状态或对象。 |
-| [GetAllScenes](GetAllScenes.md) | 获取相关状态或对象。 |
-| [OnSceneLoaded](OnSceneLoaded.md) | 公开方法，详见头文件声明。 |
-| [OnSceneUnloaded](OnSceneUnloaded.md) | 公开方法，详见头文件声明。 |
-| [OnActiveSceneChanged](OnActiveSceneChanged.md) | 公开方法，详见头文件声明。 |
+| [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` 平行目录
-- [API 总索引](../../../main.md) - 返回顶层索引
+- [当前模块](../Scene.md)
+- [Scene](../Scene/Scene.md)
+- [Scene Lifecycle And Serialization](../../../_guides/Scene/Scene-Lifecycle-And-Serialization.md)