docs: rebuild Scene API content

docs/api/XCEngine/Scene/Scene.md

@@ -1,21 +1,50 @@
 # Scene
 
-**命名空间**: `XCEngine::Scene`
+**命名空间**: `XCEngine::Components`
 
 **类型**: `module`
 
-**描述**: 场景与场景管理器 API。
+**描述**: 提供场景容器 `Scene` 与多场景入口 `SceneManager`，负责组织 `GameObject` 层级、场景级更新与自定义文本序列化。
 
-## 概览
+## 概述
 
-该目录与 `XCEngine/Scene` 对应的 public headers 保持平行，用于承载唯一的 canonical API 文档入口。
+`XCEngine/Scene` 这组头文件位于 `Scene` 目录下，但公开类型实际放在 `XCEngine::Components` 命名空间中。这反映了当前引擎的建模方式：
+
+- `Scene` 负责持有一组 `GameObject`。
+- `GameObject` 负责父子层级、`TransformComponent` 和其它组件。
+- `SceneManager` 负责持有多个已加载场景，并暴露“当前活动场景”入口。
+
+这和商业引擎里常见的 Unity 风格思路接近：场景是对象集合与生命周期边界，真正可组合的行为仍然落在对象与组件层。
+
+## 当前实现成熟度
+
+这一组 API 已经能支撑基础场景树、更新和保存/加载，但需要对当前边界保持诚实：
+
+- `Scene::IsActive()` / `SetActive()` 当前只是存储一个标志位，不会阻止 `Update()`、`FixedUpdate()` 或 `LateUpdate()` 运行。
+- `FindGameObjectWithTag()` 当前并没有真正的 tag 系统支持，实际按对象名称匹配。
+- `Scene::~Scene()` 不会逐个调用 `DestroyGameObject()`，因此不会触发场景销毁事件，也不会为组件调用 `OnDestroy()`。
+- `SceneManager::LoadSceneAsync()` 当前不是异步加载，只是同步包装。
+- `SceneManager` 的活动场景指针，与 `Scene` 自身的 active 标志当前是两套彼此独立的状态。
+
+## 设计要点
+
+- `Scene` 采用“所有权集中、访问返回裸指针”的模式：内部由 `std::unique_ptr<GameObject>` 持有对象，API 对外返回非拥有指针。
+- 根对象列表与父子层级分开维护，这让“遍历根对象”和“对象挂接到父节点”可以各自保持简单。
+- 序列化走的是引擎私有文本格式，而不是通用 JSON。这样实现成本低、易于直接落地组件自定义序列化，但兼容性和健壮性也相对有限。
 
 ## 头文件
 
-- [Scene](Scene/Scene.md) - `Scene.h`
-- [SceneManager](SceneManager/SceneManager.md) - `SceneManager.h`
+- [Scene](Scene/Scene.md) - `Scene.h`，单个场景容器、更新入口和序列化接口。
+- [SceneManager](SceneManager/SceneManager.md) - `SceneManager.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)
 - [上级目录](../XCEngine.md)
 - [API 总索引](../../main.md)

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

@@ -1,41 +1,30 @@
-# Scene::Scene()
+# Scene::Constructor
 
-构造对象。
-
-该方法在 `XCEngine/Scene/Scene.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
+构造一个场景对象。
 
 ```cpp
 Scene();
-```
-
-**参数：** 无。
-
-**返回：** `void` - 无返回值。
-
-## 重载 2: 声明
-
-```cpp
 explicit Scene(const std::string& name);
 ```
 
-**参数：**
-- `name` - 参数语义详见头文件声明。
+## 行为说明
 
-**返回：** `void` - 无返回值。
+当前有两个重载：
 
-**示例：**
+- `Scene()` 会把场景名初始化为 `"Untitled"`。
+- `Scene(const std::string& name)` 会把场景名初始化为传入值。
 
-```cpp
-#include <XCEngine/Scene/Scene.h>
+无论哪个重载，`m_active` 都会保留成员默认值 `true`，并从空的对象集合开始。
 
-void Example() {
-    XCEngine::Components::Scene object;
-}
-```
+## 参数
+
+- `name` - 仅命名构造重载使用的场景名称。
+
+## 返回值
+
+- 无。
 
 ## 相关文档
 
-- [返回类总览](Scene.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](Scene.md)
+- [SetName](SetName.md)

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

@@ -1,32 +1,40 @@
 # Scene::CreateGameObject
 
-创建新对象或资源。
+在当前场景中创建一个新对象。
 
 ```cpp
 GameObject* CreateGameObject(const std::string& name, GameObject* parent = nullptr);
 ```
 
-该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `name` - 参数语义详见头文件声明。
-- `parent` - 参数语义详见头文件声明。
+当前实现按以下顺序执行：
 
-**返回：** `GameObject*` - 返回值语义详见头文件声明。
+1. 构造一个 `GameObject(name)`。
+2. 把对象登记到 `GameObject` 全局注册表。
+3. 把对象登记到当前场景的 `m_gameObjects`、`m_gameObjectIDs`。
+4. 写入 `ptr->m_scene = this`。
+5. 如果提供 `parent`，调用 `ptr->SetParent(parent)`；否则把对象记为根对象。
+6. 调用 `ptr->Awake()`。
+7. 触发 [OnGameObjectCreated](OnGameObjectCreated.md) 事件。
 
-**示例：**
+## 参数
 
-```cpp
-#include <XCEngine/Scene/Scene.h>
+- `name` - 新对象名称。
+- `parent` - 可选父对象；为空时对象会成为根对象。
 
-void Example() {
-    XCEngine::Components::Scene object;
-    // 根据上下文补齐参数后调用 Scene::CreateGameObject(...)。
-    (void)object;
-}
-```
+## 返回值
+
+- `GameObject*` - 新对象的非拥有指针；所有权仍然属于当前 `Scene`。
+
+## 注意事项
+
+- 当前不会校验 `parent` 是否也属于当前场景；跨场景挂接可能制造不一致状态。
+- 返回指针在对象被 [DestroyGameObject](DestroyGameObject.md) 销毁或场景销毁后失效。
+- `Awake()` 在事件触发前调用。
 
 ## 相关文档
 
-- [返回类总览](Scene.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](Scene.md)
+- [DestroyGameObject](DestroyGameObject.md)
+- [OnGameObjectCreated](OnGameObjectCreated.md)

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

@@ -1,31 +1,38 @@
 # Scene::DeserializeFromString
 
-公开方法，详见头文件声明。
+从字符串重建当前场景内容。
 
 ```cpp
 void DeserializeFromString(const std::string& data);
 ```
 
-该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `data` - 参数语义详见头文件声明。
+当前实现会先清空 `m_gameObjects`、`m_rootGameObjects` 和 `m_gameObjectIDs`，然后解析自定义文本格式，分两阶段重建场景：
 
-**返回：** `void` - 无返回值。
+1. 先读取所有 `gameobject_begin` / `gameobject_end` 块，收集待创建对象、父子关系、Transform 数据和组件 payload。
+2. 再创建所有 `GameObject` 实例，恢复 ID、UUID、active、自定义组件和层级关系。
 
-**示例：**
+解析完成后，如果文件中的最大对象 ID 大于等于 `GameObject::s_nextID`，当前实现还会把全局自增 ID 推进到 `maxId + 1`。
 
-```cpp
-#include <XCEngine/Scene/Scene.h>
+## 参数
 
-void Example() {
-    XCEngine::Components::Scene object;
-    // 根据上下文补齐参数后调用 Scene::DeserializeFromString(...)。
-    (void)object;
-}
-```
+- `data` - 序列化后的场景文本。
+
+## 返回值
+
+- 无。
+
+## 当前实现限制
+
+- 旧对象被清空时不会逐个调用 [DestroyGameObject](DestroyGameObject.md)，因此不会触发销毁事件，也不会对组件调用 `OnDestroy()`。
+- 新对象是直接构建出来的，不会触发 [OnGameObjectCreated](OnGameObjectCreated.md)，也不会调用 `Awake()` / `Start()`。
+- 组件创建依赖 `ComponentFactoryRegistry`；未注册的组件类型会被跳过。
+- 对于损坏的数字字段，`std::stoull` 抛出的异常当前不会在这里捕获。
+- 如果父对象 ID 缺失或找不到，对象会被回退为根对象。
 
 ## 相关文档
 
-- [返回类总览](Scene.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](Scene.md)
+- [SerializeToString](SerializeToString.md)
+- [Load](Load.md)

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

@@ -1,31 +1,38 @@
 # Scene::DestroyGameObject
 
-公开方法，详见头文件声明。
+从当前场景中递归销毁一个对象。
 
 ```cpp
 void DestroyGameObject(GameObject* gameObject);
 ```
 
-该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `gameObject` - 参数语义详见头文件声明。
+当前实现会：
 
-**返回：** `void` - 无返回值。
+1. 在 `gameObject == nullptr` 或对象不属于当前场景时直接返回。
+2. 先递归销毁所有子对象。
+3. 把对象从父对象子列表或根对象列表中移除。
+4. 触发 [OnGameObjectDestroyed](OnGameObjectDestroyed.md)。
+5. 调用 `gameObject->OnDestroy()`。
+6. 从 ID 集合和 `m_gameObjects` 中移除对象。
 
-**示例：**
+## 参数
 
-```cpp
-#include <XCEngine/Scene/Scene.h>
+- `gameObject` - 待销毁对象。
 
-void Example() {
-    XCEngine::Components::Scene object;
-    // 根据上下文补齐参数后调用 Scene::DestroyGameObject(...)。
-    (void)object;
-}
-```
+## 返回值
+
+- 无。
+
+## 注意事项
+
+- 销毁事件当前先于 `GameObject::OnDestroy()` 触发。
+- 删除 `m_gameObjects` 中的 `unique_ptr` 后，对象指针会立即失效。
+- 场景析构当前不会逐个走这个入口。
 
 ## 相关文档
 
-- [返回类总览](Scene.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](Scene.md)
+- [CreateGameObject](CreateGameObject.md)
+- [OnGameObjectDestroyed](OnGameObjectDestroyed.md)

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

@@ -1,29 +1,34 @@
-# Scene::~Scene()
+# Scene::Destructor
 
-销毁对象并释放相关资源。
+销毁场景对象。
 
 ```cpp
 ~Scene();
 ```
 
-该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
-
-**返回：** `void` - 无返回值。
-
-**示例：**
+当前实现只有一行：
 
 ```cpp
-#include <XCEngine/Scene/Scene.h>
-
-void Example() {
-    XCEngine::Components::Scene object;
-    // 对象离开作用域时会自动触发析构。
-}
+m_gameObjects.clear();
 ```
 
+也就是说，场景析构只是让内部 `unique_ptr<GameObject>` 容器整体释放。
+
+## 返回值
+
+- 无。
+
+## 当前实现限制
+
+- 不会逐个调用 [DestroyGameObject](DestroyGameObject.md)。
+- 不会触发 [OnGameObjectDestroyed](OnGameObjectDestroyed.md)。
+- 不会为组件调用 `OnDestroy()`。
+
+如果你的清理逻辑依赖显式销毁事件或组件销毁回调，应在场景析构前主动销毁对象，而不是依赖 `~Scene()`。
+
 ## 相关文档
 
-- [返回类总览](Scene.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](Scene.md)
+- [DestroyGameObject](DestroyGameObject.md)

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

@@ -1,31 +1,28 @@
 # Scene::Find
 
-查找并返回匹配对象。
+按对象名称查找场景中的第一个匹配对象。
 
 ```cpp
 GameObject* Find(const std::string& name) const;
 ```
 
-该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `name` - 参数语义详见头文件声明。
+当前实现从根对象开始做深度优先递归查找：
 
-**返回：** `GameObject*` - 返回值语义详见头文件声明。
+1. 先检查每个根对象自身名称。
+2. 再递归检查其子对象。
+3. 找到第一个匹配项后立即返回。
 
-**示例：**
+## 参数
 
-```cpp
-#include <XCEngine/Scene/Scene.h>
+- `name` - 目标对象名称。
 
-void Example() {
-    XCEngine::Components::Scene object;
-    // 根据上下文补齐参数后调用 Scene::Find(...)。
-    (void)object;
-}
-```
+## 返回值
+
+- `GameObject*` - 第一个匹配对象；找不到时返回 `nullptr`。
 
 ## 相关文档
 
-- [返回类总览](Scene.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](Scene.md)
+- [FindByID](FindByID.md)

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

@@ -1,31 +1,24 @@
 # Scene::FindByID
 
-查找并返回匹配对象。
+按对象 ID 查找场景中的对象。
 
 ```cpp
 GameObject* FindByID(GameObjectID id) const;
 ```
 
-该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `id` - 参数语义详见头文件声明。
+当前实现直接对 `m_gameObjects` 做哈希表查找。
 
-**返回：** `GameObject*` - 返回值语义详见头文件声明。
+## 参数
 
-**示例：**
+- `id` - 目标对象 ID。
 
-```cpp
-#include <XCEngine/Scene/Scene.h>
+## 返回值
 
-void Example() {
-    XCEngine::Components::Scene object;
-    // 根据上下文补齐参数后调用 Scene::FindByID(...)。
-    (void)object;
-}
-```
+- `GameObject*` - 找到时返回对象指针；找不到时返回 `nullptr`。
 
 ## 相关文档
 
-- [返回类总览](Scene.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](Scene.md)
+- [Find](Find.md)

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

@@ -1,31 +1,30 @@
 # Scene::FindGameObjectWithTag
 
-查找并返回匹配对象。
+查找带指定“tag”的对象。
 
 ```cpp
 GameObject* FindGameObjectWithTag(const std::string& tag) const;
 ```
 
-该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `tag` - 参数语义详见头文件声明。
-
-**返回：** `GameObject*` - 返回值语义详见头文件声明。
-
-**示例：**
+接口名称里写的是 tag，但当前实现实际比较的是：
 
 ```cpp
-#include <XCEngine/Scene/Scene.h>
-
-void Example() {
-    XCEngine::Components::Scene object;
-    // 根据上下文补齐参数后调用 Scene::FindGameObjectWithTag(...)。
-    (void)object;
-}
+go->GetName() == tag
 ```
 
+也就是说，它现在的行为与“按名称递归查找第一个匹配对象”更接近，而不是使用独立 tag 字段。
+
+## 参数
+
+- `tag` - 当前实现下实际被当作对象名称使用的字符串。
+
+## 返回值
+
+- `GameObject*` - 第一个匹配对象；找不到时返回 `nullptr`。
+
 ## 相关文档
 
-- [返回类总览](Scene.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](Scene.md)
+- [Find](Find.md)

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

@@ -1,30 +1,30 @@
 # Scene::FindObjectOfType
 
-查找并返回匹配对象。
+查找场景中的第一个指定类型组件。
 
 ```cpp
-template<typename T> T* FindObjectOfType() const;
+template<typename T>
+T* FindObjectOfType() const;
 ```
 
-该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前模板实现会：
 
-**返回：** `template<typename T> T*` - 返回值语义详见头文件声明。
+1. 遍历所有根对象。
+2. 先检查根对象自身的 `GetComponent<T>()`。
+3. 再递归检查子对象。
+4. 返回第一个命中的组件指针。
 
-**示例：**
+## 模板参数
 
-```cpp
-#include <XCEngine/Scene/Scene.h>
+- `T` - 目标组件类型。
 
-void Example() {
-    XCEngine::Components::Scene object;
-    // 根据上下文补齐参数后调用 Scene::FindObjectOfType(...)。
-    (void)object;
-}
-```
+## 返回值
+
+- `T*` - 第一个匹配组件；找不到时返回 `nullptr`。
 
 ## 相关文档
 
-- [返回类总览](Scene.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](Scene.md)
+- [FindObjectsOfType](FindObjectsOfType.md)

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

@@ -1,30 +1,29 @@
 # Scene::FindObjectsOfType
 
-查找并返回匹配对象。
+查找场景中的所有指定类型组件。
 
 ```cpp
-template<typename T> std::vector<T*> FindObjectsOfType() const;
+template<typename T>
+std::vector<T*> FindObjectsOfType() const;
 ```
 
-该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前模板实现会从所有根对象开始做深度优先遍历：
 
-**返回：** `template<typename T> std::vector<T*>` - 返回值语义详见头文件声明。
+- 根对象自身匹配时先加入结果。
+- 再递归扫描全部子对象。
+- 返回收集到的所有 `T*`。
 
-**示例：**
+## 模板参数
 
-```cpp
-#include <XCEngine/Scene/Scene.h>
+- `T` - 目标组件类型。
 
-void Example() {
-    XCEngine::Components::Scene object;
-    // 根据上下文补齐参数后调用 Scene::FindObjectsOfType(...)。
-    (void)object;
-}
-```
+## 返回值
+
+- `std::vector<T*>` - 所有匹配组件组成的数组；找不到时返回空数组。
 
 ## 相关文档
 
-- [返回类总览](Scene.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](Scene.md)
+- [FindObjectOfType](FindObjectOfType.md)

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

@@ -1,31 +1,30 @@
 # Scene::FixedUpdate
 
-公开方法，详见头文件声明。
+驱动场景的固定步长更新。
 
 ```cpp
 void FixedUpdate(float fixedDeltaTime);
 ```
 
-该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `fixedDeltaTime` - 参数语义详见头文件声明。
+当前实现会遍历根对象，并对处于 `IsActiveInHierarchy()` 状态的对象调用 `go->FixedUpdate()`。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `fixedDeltaTime` - 固定步长参数。
 
-```cpp
-#include <XCEngine/Scene/Scene.h>
+## 返回值
 
-void Example() {
-    XCEngine::Components::Scene object;
-    // 根据上下文补齐参数后调用 Scene::FixedUpdate(...)。
-    (void)object;
-}
-```
+- 无。
+
+## 当前实现限制
+
+- `fixedDeltaTime` 当前没有被向下传递，`GameObject::FixedUpdate()` 也不接收这个参数。
+- `Scene::m_active` 当前不会阻止这条更新链运行。
 
 ## 相关文档
 
-- [返回类总览](Scene.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](Scene.md)
+- [Update](Update.md)
+- [LateUpdate](LateUpdate.md)

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

@@ -1,30 +1,20 @@
 # Scene::GetName
 
-获取相关状态或对象。
+查询场景名称。
 
 ```cpp
 const std::string& GetName() const;
 ```
 
-该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现直接返回 `m_name` 的常量引用。
 
-**返回：** `const std::string&` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
-
-```cpp
-#include <XCEngine/Scene/Scene.h>
-
-void Example() {
-    XCEngine::Components::Scene object;
-    // 根据上下文补齐参数后调用 Scene::GetName(...)。
-    (void)object;
-}
-```
+- `const std::string&` - 当前场景名称。
 
 ## 相关文档
 
-- [返回类总览](Scene.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](Scene.md)
+- [SetName](SetName.md)

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

@@ -1,30 +1,25 @@
 # Scene::GetRootGameObjects
 
-获取相关状态或对象。
+获取当前场景的根对象列表。
 
 ```cpp
 std::vector<GameObject*> GetRootGameObjects() const;
 ```
 
-该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现会按 `m_rootGameObjects` 中保存的 ID 顺序重新组装结果数组，并跳过已经不存在于 `m_gameObjects` 中的条目。
 
-**返回：** `std::vector<GameObject*>` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `std::vector<GameObject*>` - 当前根对象指针数组。
 
-```cpp
-#include <XCEngine/Scene/Scene.h>
+## 注意事项
 
-void Example() {
-    XCEngine::Components::Scene object;
-    // 根据上下文补齐参数后调用 Scene::GetRootGameObjects(...)。
-    (void)object;
-}
-```
+- 返回的是值复制后的数组，不是内部存储引用。
+- 指针本身仍由 `Scene` 拥有。
 
 ## 相关文档
 
-- [返回类总览](Scene.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](Scene.md)
+- [CreateGameObject](CreateGameObject.md)

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

@@ -1,30 +1,25 @@
 # Scene::IsActive
 
-查询当前状态。
+查询场景 active 标志。
 
 ```cpp
 bool IsActive() const;
 ```
 
-该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现直接返回 `m_active`。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `bool` - 场景的 active 标志值。
 
-```cpp
-#include <XCEngine/Scene/Scene.h>
+## 注意事项
 
-void Example() {
-    XCEngine::Components::Scene object;
-    // 根据上下文补齐参数后调用 Scene::IsActive(...)。
-    (void)object;
-}
-```
+- 这个标志当前不会阻止 [Update](Update.md)、[FixedUpdate](FixedUpdate.md) 或 [LateUpdate](LateUpdate.md) 执行。
+- `SceneManager` 的活动场景指针也不会自动同步这个值。
 
 ## 相关文档
 
-- [返回类总览](Scene.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](Scene.md)
+- [SetActive](SetActive.md)

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

@@ -1,31 +1,28 @@
 # Scene::LateUpdate
 
-公开方法，详见头文件声明。
+驱动场景的晚更新。
 
 ```cpp
 void LateUpdate(float deltaTime);
 ```
 
-该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `deltaTime` - 参数语义详见头文件声明。
+当前实现会遍历根对象，并对处于 `IsActiveInHierarchy()` 状态的对象调用 `go->LateUpdate(deltaTime)`。子对象递归更新由 `GameObject::LateUpdate()` 负责。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `deltaTime` - 当前帧时间步长。
 
-```cpp
-#include <XCEngine/Scene/Scene.h>
+## 返回值
 
-void Example() {
-    XCEngine::Components::Scene object;
-    // 根据上下文补齐参数后调用 Scene::LateUpdate(...)。
-    (void)object;
-}
-```
+- 无。
+
+## 注意事项
+
+- `Scene::m_active` 当前不会阻止这条更新链运行。
 
 ## 相关文档
 
-- [返回类总览](Scene.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](Scene.md)
+- [Update](Update.md)

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

@@ -1,31 +1,30 @@
 # Scene::Load
 
-加载资源或数据。
+从文件加载场景内容。
 
 ```cpp
 void Load(const std::string& filePath);
 ```
 
-该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `filePath` - 参数语义详见头文件声明。
+当前实现会尝试打开 `filePath`，然后把整个文件内容读入字符串并传给 [DeserializeFromString](DeserializeFromString.md)。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `filePath` - 场景文件路径。
 
-```cpp
-#include <XCEngine/Scene/Scene.h>
+## 返回值
 
-void Example() {
-    XCEngine::Components::Scene object;
-    // 根据上下文补齐参数后调用 Scene::Load(...)。
-    (void)object;
-}
-```
+- 无。
+
+## 当前实现限制
+
+- 文件打开失败时会静默返回，不会抛出异常，也不会返回错误码。
+- 加载过程沿用 [DeserializeFromString](DeserializeFromString.md) 的所有限制：不会触发生命周期事件、依赖组件工厂注册等。
 
 ## 相关文档
 
-- [返回类总览](Scene.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](Scene.md)
+- [Save](Save.md)
+- [DeserializeFromString](DeserializeFromString.md)

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

@@ -1,30 +1,23 @@
 # Scene::OnGameObjectCreated
 
-公开方法，详见头文件声明。
+访问对象创建事件。
 
 ```cpp
 Core::Event<GameObject*>& OnGameObjectCreated();
 ```
 
-该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现直接返回内部事件对象 `m_onGameObjectCreated` 的引用。
 
-**返回：** `Core::Event<GameObject*>&` - 返回值语义详见头文件声明。
+该事件在 [CreateGameObject](CreateGameObject.md) 成功创建并调用 `Awake()` 之后触发。
 
-**示例：**
+## 返回值
 
-```cpp
-#include <XCEngine/Scene/Scene.h>
-
-void Example() {
-    XCEngine::Components::Scene object;
-    // 根据上下文补齐参数后调用 Scene::OnGameObjectCreated(...)。
-    (void)object;
-}
-```
+- `Core::Event<GameObject*>&` - 创建事件对象引用。
 
 ## 相关文档
 
-- [返回类总览](Scene.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](Scene.md)
+- [CreateGameObject](CreateGameObject.md)
+- [Event](../../Core/Event/Event.md)

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

@@ -1,30 +1,23 @@
 # Scene::OnGameObjectDestroyed
 
-公开方法，详见头文件声明。
+访问对象销毁事件。
 
 ```cpp
 Core::Event<GameObject*>& OnGameObjectDestroyed();
 ```
 
-该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现直接返回内部事件对象 `m_onGameObjectDestroyed` 的引用。
 
-**返回：** `Core::Event<GameObject*>&` - 返回值语义详见头文件声明。
+该事件在 [DestroyGameObject](DestroyGameObject.md) 中先于 `gameObject->OnDestroy()` 触发。
 
-**示例：**
+## 返回值
 
-```cpp
-#include <XCEngine/Scene/Scene.h>
-
-void Example() {
-    XCEngine::Components::Scene object;
-    // 根据上下文补齐参数后调用 Scene::OnGameObjectDestroyed(...)。
-    (void)object;
-}
-```
+- `Core::Event<GameObject*>&` - 销毁事件对象引用。
 
 ## 相关文档
 
-- [返回类总览](Scene.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](Scene.md)
+- [DestroyGameObject](DestroyGameObject.md)
+- [Event](../../Core/Event/Event.md)

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

@@ -1,31 +1,30 @@
 # Scene::Save
 
-公开方法，详见头文件声明。
+把当前场景保存到文件。
 
 ```cpp
 void Save(const std::string& filePath);
 ```
 
-该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `filePath` - 参数语义详见头文件声明。
+当前实现会尝试打开输出文件，并把 [SerializeToString](SerializeToString.md) 的结果直接写入文件。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `filePath` - 输出文件路径。
 
-```cpp
-#include <XCEngine/Scene/Scene.h>
+## 返回值
 
-void Example() {
-    XCEngine::Components::Scene object;
-    // 根据上下文补齐参数后调用 Scene::Save(...)。
-    (void)object;
-}
-```
+- 无。
+
+## 当前实现限制
+
+- 文件打开失败时会静默返回。
+- 采用的是引擎私有文本格式，而不是带版本控制的通用交换格式。
 
 ## 相关文档
 
-- [返回类总览](Scene.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](Scene.md)
+- [Load](Load.md)
+- [SerializeToString](SerializeToString.md)

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

@@ -6,47 +6,72 @@
 
 **头文件**: `XCEngine/Scene/Scene.h`
 
-**描述**: 定义 `XCEngine/Scene` 子目录中的 `Scene` public API。
+**描述**: 持有一组 `GameObject`、驱动场景级更新，并提供场景保存/加载能力的场景容器。
 
 ## 概述
 
-`Scene.h` 是 `XCEngine/Scene` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`Scene` 是当前引擎里“对象集合”的所有权边界。它内部同时维护：
 
-## 声明概览
+- `m_gameObjects`，按 ID 保存 `GameObject` 的唯一所有权。
+- `m_rootGameObjects`，保存根对象 ID 列表。
+- `m_gameObjectIDs`，保存当前场景内出现过的对象 ID 集合。
+- 两个创建/销毁事件入口。
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `Scene` | `class` | 头文件中的公开声明。 |
+这类结构在商业引擎里很常见：场景负责对象集合、根节点入口和存档边界；对象本身再负责组件与层级递归。
 
-## 公共方法
+## 生命周期与所有权
 
-| 方法 | 描述 |
+- [Constructor](Constructor.md) 创建空场景，默认激活状态为 `true`。
+- [CreateGameObject](CreateGameObject.md) 分配并登记一个新对象。
+- [DestroyGameObject](DestroyGameObject.md) 从当前场景树中递归移除对象。
+- [Destructor](Destructor.md) 当前直接清空内部 `unique_ptr` 容器。
+
+`Scene` 对对象有所有权，但绝大多数查询接口都返回裸指针。因此调用方必须把这些指针看成“场景拥有、只在场景存活且对象未被销毁时有效”的观察指针。
+
+## 当前实现边界
+
+- `m_active` 当前不会参与更新门控；即使场景 inactive，`Update()` 系列接口照样执行。
+- [FindGameObjectWithTag](FindGameObjectWithTag.md) 名字里是 tag，实际实现里比较的是 `GameObject::GetName()`。
+- [Destructor](Destructor.md) 不会触发 `OnGameObjectDestroyed()`，也不会为组件调用 `OnDestroy()`。
+- [DeserializeFromString](DeserializeFromString.md) 直接重建内部状态，不经过 [CreateGameObject](CreateGameObject.md)，因此不会触发生命周期和创建事件。
+- [Save](Save.md) / [Load](Load.md) 打开文件失败时当前静默返回。
+- [SetName](SetName.md) 只会修改场景对象内部名称；如果场景由 `SceneManager` 管理，管理器的 key 不会随之更新。
+
+## 线程语义
+
+- 当前没有锁；应在主线程或外部同步前提下使用。
+
+## 公开方法
+
+| 方法 | 说明 |
 |------|------|
-| [Scene()](Constructor.md) | 构造对象。 |
-| [~Scene()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [GetName](GetName.md) | 获取相关状态或对象。 |
-| [SetName](SetName.md) | 设置相关状态或配置。 |
-| [IsActive](IsActive.md) | 查询当前状态。 |
-| [SetActive](SetActive.md) | 设置相关状态或配置。 |
-| [CreateGameObject](CreateGameObject.md) | 创建新对象或资源。 |
-| [DestroyGameObject](DestroyGameObject.md) | 公开方法，详见头文件声明。 |
-| [Find](Find.md) | 查找并返回匹配对象。 |
-| [FindByID](FindByID.md) | 查找并返回匹配对象。 |
-| [FindGameObjectWithTag](FindGameObjectWithTag.md) | 查找并返回匹配对象。 |
-| [FindObjectOfType](FindObjectOfType.md) | 查找并返回匹配对象。 |
-| [FindObjectsOfType](FindObjectsOfType.md) | 查找并返回匹配对象。 |
-| [GetRootGameObjects](GetRootGameObjects.md) | 获取相关状态或对象。 |
-| [Update](Update.md) | 更新运行时状态。 |
-| [FixedUpdate](FixedUpdate.md) | 公开方法，详见头文件声明。 |
-| [LateUpdate](LateUpdate.md) | 公开方法，详见头文件声明。 |
-| [Save](Save.md) | 公开方法，详见头文件声明。 |
-| [Load](Load.md) | 加载资源或数据。 |
-| [SerializeToString](SerializeToString.md) | 公开方法，详见头文件声明。 |
-| [DeserializeFromString](DeserializeFromString.md) | 公开方法，详见头文件声明。 |
-| [OnGameObjectCreated](OnGameObjectCreated.md) | 公开方法，详见头文件声明。 |
-| [OnGameObjectDestroyed](OnGameObjectDestroyed.md) | 公开方法，详见头文件声明。 |
+| [Constructor](Constructor.md) | 构造空场景。 |
+| [Destructor](Destructor.md) | 销毁场景。 |
+| [GetName](GetName.md) | 查询场景名称。 |
+| [SetName](SetName.md) | 设置场景名称。 |
+| [IsActive](IsActive.md) | 查询场景 active 标志。 |
+| [SetActive](SetActive.md) | 设置场景 active 标志。 |
+| [CreateGameObject](CreateGameObject.md) | 创建场景对象。 |
+| [DestroyGameObject](DestroyGameObject.md) | 销毁场景对象。 |
+| [Find](Find.md) | 按名称查找对象。 |
+| [FindByID](FindByID.md) | 按 ID 查找对象。 |
+| [FindGameObjectWithTag](FindGameObjectWithTag.md) | 按“tag”查找；当前实际按名称匹配。 |
+| [FindObjectOfType](FindObjectOfType.md) | 查找第一个匹配组件。 |
+| [FindObjectsOfType](FindObjectsOfType.md) | 查找所有匹配组件。 |
+| [GetRootGameObjects](GetRootGameObjects.md) | 获取根对象列表。 |
+| [Update](Update.md) | 驱动每帧更新。 |
+| [FixedUpdate](FixedUpdate.md) | 驱动固定步长更新。 |
+| [LateUpdate](LateUpdate.md) | 驱动晚更新。 |
+| [Save](Save.md) | 保存到文件。 |
+| [Load](Load.md) | 从文件加载。 |
+| [SerializeToString](SerializeToString.md) | 序列化为字符串。 |
+| [DeserializeFromString](DeserializeFromString.md) | 从字符串反序列化。 |
+| [OnGameObjectCreated](OnGameObjectCreated.md) | 访问对象创建事件。 |
+| [OnGameObjectDestroyed](OnGameObjectDestroyed.md) | 访问对象销毁事件。 |
 
 ## 相关文档
 
-- [当前目录](../Scene.md) - 返回 `Scene` 平行目录
-- [API 总索引](../../../main.md) - 返回顶层索引
+- [当前模块](../Scene.md)
+- [GameObject](../../Components/GameObject/GameObject.md)
+- [TransformComponent](../../Components/TransformComponent/TransformComponent.md)
+- [Scene Lifecycle And Serialization](../../../_guides/Scene/Scene-Lifecycle-And-Serialization.md)

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

@@ -1,30 +1,33 @@
 # Scene::SerializeToString
 
-公开方法，详见头文件声明。
+把当前场景序列化为字符串。
 
 ```cpp
 std::string SerializeToString() const;
 ```
 
-该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现生成的是自定义文本格式，内容大致包括：
 
-**返回：** `std::string` - 返回值语义详见头文件声明。
+- 文件头 `# XCEngine Scene File`
+- `scene=...`
+- `active=...`
+- 每个对象的 `gameobject_begin` / `gameobject_end` 块
+- 对象 ID、UUID、名称、父对象 ID、Transform 数据和组件数据
 
-**示例：**
+对象输出顺序是“根对象顺序 + 深度优先递归子树”。
 
-```cpp
-#include <XCEngine/Scene/Scene.h>
+## 返回值
 
-void Example() {
-    XCEngine::Components::Scene object;
-    // 根据上下文补齐参数后调用 Scene::SerializeToString(...)。
-    (void)object;
-}
-```
+- `std::string` - 序列化后的场景文本。
+
+## 注意事项
+
+- 这不是 JSON、YAML 或 glTF 一类的通用格式。
+- 名称字段会经过简单转义；组件内容如何写入，取决于各组件自己的 `Serialize()` 实现。
 
 ## 相关文档
 
-- [返回类总览](Scene.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](Scene.md)
+- [DeserializeFromString](DeserializeFromString.md)

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

@@ -1,31 +1,34 @@
 # Scene::SetActive
 
-设置相关状态或配置。
+设置场景 active 标志。
 
 ```cpp
 void SetActive(bool active);
 ```
 
-该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `active` - 参数语义详见头文件声明。
-
-**返回：** `void` - 无返回值。
-
-**示例：**
+当前头文件内联实现只有一行：
 
 ```cpp
-#include <XCEngine/Scene/Scene.h>
-
-void Example() {
-    XCEngine::Components::Scene object;
-    // 根据上下文补齐参数后调用 Scene::SetActive(...)。
-    (void)object;
-}
+m_active = active;
 ```
 
+## 参数
+
+- `active` - 要写入的标志值。
+
+## 返回值
+
+- 无。
+
+## 当前实现限制
+
+- 不会同步到 `SceneManager::GetActiveScene()`。
+- 不会自动启停对象更新链。
+- 更适合把它当作可序列化的场景状态位，而不是完整的运行时调度开关。
+
 ## 相关文档
 
-- [返回类总览](Scene.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](Scene.md)
+- [IsActive](IsActive.md)

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

@@ -1,31 +1,29 @@
 # Scene::SetName
 
-设置相关状态或配置。
+设置场景名称。
 
 ```cpp
 void SetName(const std::string& name);
 ```
 
-该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `name` - 参数语义详见头文件声明。
+当前头文件内联实现直接执行 `m_name = name`。
 
-**返回：** `void` - 无返回值。
+## 参数
 
-**示例：**
+- `name` - 新场景名称。
 
-```cpp
-#include <XCEngine/Scene/Scene.h>
+## 返回值
 
-void Example() {
-    XCEngine::Components::Scene object;
-    // 根据上下文补齐参数后调用 Scene::SetName(...)。
-    (void)object;
-}
-```
+- 无。
+
+## 注意事项
+
+- 如果当前场景已经由 `SceneManager` 按某个 key 保存到 `m_scenes` 中，这个调用不会同步修改那个 key。
+- 因此 `Scene::GetName()` 与 `SceneManager::GetScene(...)` 使用的查找字符串，后续可能出现不一致。
 
 ## 相关文档
 
-- [返回类总览](Scene.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](Scene.md)
+- [GetName](GetName.md)

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

@@ -1,31 +1,35 @@
 # Scene::Update
 
-更新运行时状态。
+驱动场景的每帧更新。
 
 ```cpp
 void Update(float deltaTime);
 ```
 
-该方法声明于 `XCEngine/Scene/Scene.h`，当前页面用于固定 `Scene` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `deltaTime` - 参数语义详见头文件声明。
+当前实现会遍历根对象，并对处于 `IsActiveInHierarchy()` 状态的根对象执行：
 
-**返回：** `void` - 无返回值。
+1. `go->Start()`
+2. `go->Update(deltaTime)`
 
-**示例：**
+对象树的递归传播由 `GameObject::Start()` 和 `GameObject::Update()` 自己完成。
 
-```cpp
-#include <XCEngine/Scene/Scene.h>
+## 参数
 
-void Example() {
-    XCEngine::Components::Scene object;
-    // 根据上下文补齐参数后调用 Scene::Update(...)。
-    (void)object;
-}
-```
+- `deltaTime` - 当前帧时间步长。
+
+## 返回值
+
+- 无。
+
+## 注意事项
+
+- `Start()` 每帧都会被调用到根对象入口，但 `GameObject` 内部会用 `m_started` 保证组件 `Start()` 只真正执行一次。
+- `Scene::m_active` 当前不会阻止这条更新链运行。
 
 ## 相关文档
 
-- [返回类总览](Scene.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](Scene.md)
+- [FixedUpdate](FixedUpdate.md)
+- [LateUpdate](LateUpdate.md)

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

@@ -1,31 +1,35 @@
 # SceneManager::CreateScene
 
-创建新对象或资源。
+创建并登记一个新场景。
 
 ```cpp
 Scene* CreateScene(const std::string& name);
 ```
 
-该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `name` - 参数语义详见头文件声明。
+当前实现会：
 
-**返回：** `Scene*` - 返回值语义详见头文件声明。
+1. 构造 `std::make_unique<Scene>(name)`。
+2. 把场景存入 `m_scenes[name]`。
+3. 如果当前没有活动场景，则把 `m_activeScene` 设为新场景。
+4. 触发 [OnSceneLoaded](OnSceneLoaded.md)。
 
-**示例：**
+## 参数
 
-```cpp
-#include <XCEngine/Scene/SceneManager.h>
+- `name` - 新场景名称，同时也是 `m_scenes` 的 key。
 
-void Example() {
-    XCEngine::Components::SceneManager object;
-    // 根据上下文补齐参数后调用 SceneManager::CreateScene(...)。
-    (void)object;
-}
-```
+## 返回值
+
+- `Scene*` - 新场景的非拥有指针。
+
+## 当前实现限制
+
+- 如果同名 key 已存在，旧场景会被替换；先前拿到的裸指针可能失效。
+- 当它成为第一个活动场景时，当前不会额外触发 [OnActiveSceneChanged](OnActiveSceneChanged.md)。
 
 ## 相关文档
 
-- [返回类总览](SceneManager.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](SceneManager.md)
+- [GetScene](GetScene.md)
+- [OnSceneLoaded](OnSceneLoaded.md)

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

@@ -1,29 +1,23 @@
 # SceneManager::Get
 
-获取相关状态或对象。
+获取全局 `SceneManager` 单例。
 
 ```cpp
 static SceneManager& Get();
 ```
 
-该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
-
-**返回：** `SceneManager&` - 返回值语义详见头文件声明。
-
-**示例：**
+当前实现通过函数内静态对象返回进程级单例：
 
 ```cpp
-#include <XCEngine/Scene/SceneManager.h>
-
-void Example() {
-    auto& instance = XCEngine::Components::SceneManager::Get();
-    (void)instance;
-}
+static SceneManager instance;
 ```
 
+## 返回值
+
+- `SceneManager&` - 全局场景管理器实例引用。
+
 ## 相关文档
 
-- [返回类总览](SceneManager.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](SceneManager.md)

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

@@ -1,30 +1,25 @@
 # SceneManager::GetActiveScene
 
-获取相关状态或对象。
+获取当前活动场景。
 
 ```cpp
 Scene* GetActiveScene() const;
 ```
 
-该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现直接返回 `m_activeScene`。
 
-**返回：** `Scene*` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `Scene*` - 当前活动场景指针；没有活动场景时返回 `nullptr`。
 
-```cpp
-#include <XCEngine/Scene/SceneManager.h>
+## 注意事项
 
-void Example() {
-    XCEngine::Components::SceneManager object;
-    // 根据上下文补齐参数后调用 SceneManager::GetActiveScene(...)。
-    (void)object;
-}
-```
+- 这是非拥有指针。
+- 它与 `Scene::IsActive()` 当前不是同一个概念，也不会自动同步。
 
 ## 相关文档
 
-- [返回类总览](SceneManager.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](SceneManager.md)
+- [SetActiveScene](SetActiveScene.md)

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

@@ -1,30 +1,24 @@
 # SceneManager::GetAllScenes
 
-获取相关状态或对象。
+获取全部已登记场景。
 
 ```cpp
 std::vector<Scene*> GetAllScenes() const;
 ```
 
-该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现会遍历 `m_scenes`，把每个 `unique_ptr<Scene>` 的裸指针收集到结果数组中返回。
 
-**返回：** `std::vector<Scene*>` - 返回值语义详见头文件声明。
+## 返回值
 
-**示例：**
+- `std::vector<Scene*>` - 所有已登记场景的非拥有指针数组。
 
-```cpp
-#include <XCEngine/Scene/SceneManager.h>
+## 注意事项
 
-void Example() {
-    XCEngine::Components::SceneManager object;
-    // 根据上下文补齐参数后调用 SceneManager::GetAllScenes(...)。
-    (void)object;
-}
-```
+- 返回顺序取决于 `std::unordered_map` 的迭代顺序，不应把它当作稳定顺序。
 
 ## 相关文档
 
-- [返回类总览](SceneManager.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](SceneManager.md)
+- [GetScene](GetScene.md)

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

@@ -1,31 +1,29 @@
 # SceneManager::GetScene
 
-获取相关状态或对象。
+按内部 key 获取场景。
 
 ```cpp
 Scene* GetScene(const std::string& name) const;
 ```
 
-该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `name` - 参数语义详见头文件声明。
+当前实现直接用 `name` 在 `m_scenes` 里做哈希表查找。
 
-**返回：** `Scene*` - 返回值语义详见头文件声明。
+## 参数
 
-**示例：**
+- `name` - 场景 key。
 
-```cpp
-#include <XCEngine/Scene/SceneManager.h>
+## 返回值
 
-void Example() {
-    XCEngine::Components::SceneManager object;
-    // 根据上下文补齐参数后调用 SceneManager::GetScene(...)。
-    (void)object;
-}
-```
+- `Scene*` - 找到时返回场景指针；找不到时返回 `nullptr`。
+
+## 注意事项
+
+- 这个 `name` 对于 [CreateScene](CreateScene.md) 来说是创建时传入的名称。
+- 对于 [LoadScene](LoadScene.md) 来说，它是文件名 stem，而不一定等于场景内部的 `Scene::GetName()`。
 
 ## 相关文档
 
-- [返回类总览](SceneManager.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](SceneManager.md)
+- [LoadScene](LoadScene.md)

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

@@ -1,31 +1,37 @@
 # SceneManager::LoadScene
 
-加载资源或数据。
+从文件加载并登记一个场景。
 
 ```cpp
 void LoadScene(const std::string& filePath);
 ```
 
-该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `filePath` - 参数语义详见头文件声明。
+当前实现会：
 
-**返回：** `void` - 无返回值。
+1. 构造一个默认 `Scene`。
+2. 调用 `scene->Load(filePath)`。
+3. 从 `filePath` 中提取“文件名去扩展名”的字符串作为 map key。
+4. 把场景存入 `m_scenes[key]`。
+5. 触发 [OnSceneLoaded](OnSceneLoaded.md)。
 
-**示例：**
+## 参数
 
-```cpp
-#include <XCEngine/Scene/SceneManager.h>
+- `filePath` - 场景文件路径。
 
-void Example() {
-    XCEngine::Components::SceneManager object;
-    // 根据上下文补齐参数后调用 SceneManager::LoadScene(...)。
-    (void)object;
-}
-```
+## 返回值
+
+- 无。
+
+## 当前实现限制
+
+- 当前不会在首次加载时自动设置 `m_activeScene`。
+- 如果同 key 场景已存在，旧场景会被替换。
+- `Scene::GetName()` 可能来自文件内部内容，而 `SceneManager` 保存的 key 来自文件名，两者可能不同。
 
 ## 相关文档
 
-- [返回类总览](SceneManager.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](SceneManager.md)
+- [LoadSceneAsync](LoadSceneAsync.md)
+- [GetScene](GetScene.md)

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

@@ -1,32 +1,33 @@
 # SceneManager::LoadSceneAsync
 
-加载资源或数据。
+异步加载场景。
 
 ```cpp
 void LoadSceneAsync(const std::string& filePath, std::function<void(Scene*)> callback);
 ```
 
-该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `filePath` - 参数语义详见头文件声明。
-- `callback` - 参数语义详见头文件声明。
+当前实现实际上并没有启动后台任务，而是：
 
-**返回：** `void` - 无返回值。
+1. 直接调用 [LoadScene](LoadScene.md)。
+2. 如果 `callback` 非空，再执行 `callback(GetScene(filePath))`。
 
-**示例：**
+## 参数
 
-```cpp
-#include <XCEngine/Scene/SceneManager.h>
+- `filePath` - 场景文件路径。
+- `callback` - 加载结束后调用的回调。
 
-void Example() {
-    XCEngine::Components::SceneManager object;
-    // 根据上下文补齐参数后调用 SceneManager::LoadSceneAsync(...)。
-    (void)object;
-}
-```
+## 返回值
+
+- 无。
+
+## 当前实现限制
+
+- 当前完全是同步执行，不是线程化或任务系统驱动的异步加载。
+- 回调查找使用的是原始 `filePath`，而 [LoadScene](LoadScene.md) 存储使用的是文件名 stem。对于常见的 `assets/scenes/Main.xc` 这类输入，`GetScene(filePath)` 通常会返回 `nullptr`。
 
 ## 相关文档
 
-- [返回类总览](SceneManager.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](SceneManager.md)
+- [LoadScene](LoadScene.md)

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

@@ -1,30 +1,26 @@
 # SceneManager::OnActiveSceneChanged
 
-公开方法，详见头文件声明。
+访问活动场景切换事件。
 
 ```cpp
 Core::Event<Scene*>& OnActiveSceneChanged();
 ```
 
-该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现直接返回 `m_onActiveSceneChanged` 的引用。
 
-**返回：** `Core::Event<Scene*>&` - 返回值语义详见头文件声明。
+这个事件会在：
 
-**示例：**
+- [SetActiveScene](SetActiveScene.md) 真正改变 `m_activeScene` 时触发。
+- [UnloadScene](UnloadScene.md) 卸载当前活动场景并自动选择新的后备场景时触发。
 
-```cpp
-#include <XCEngine/Scene/SceneManager.h>
+## 返回值
 
-void Example() {
-    XCEngine::Components::SceneManager object;
-    // 根据上下文补齐参数后调用 SceneManager::OnActiveSceneChanged(...)。
-    (void)object;
-}
-```
+- `Core::Event<Scene*>&` - 活动场景切换事件对象引用。
 
 ## 相关文档
 
-- [返回类总览](SceneManager.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](SceneManager.md)
+- [SetActiveScene](SetActiveScene.md)
+- [Event](../../Core/Event/Event.md)

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

@@ -1,30 +1,23 @@
 # SceneManager::OnSceneLoaded
 
-公开方法，详见头文件声明。
+访问场景加载事件。
 
 ```cpp
 Core::Event<Scene*>& OnSceneLoaded();
 ```
 
-该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现直接返回 `m_onSceneLoaded` 的引用。
 
-**返回：** `Core::Event<Scene*>&` - 返回值语义详见头文件声明。
+这个事件在 [CreateScene](CreateScene.md) 和 [LoadScene](LoadScene.md) 中都会触发。
 
-**示例：**
+## 返回值
 
-```cpp
-#include <XCEngine/Scene/SceneManager.h>
-
-void Example() {
-    XCEngine::Components::SceneManager object;
-    // 根据上下文补齐参数后调用 SceneManager::OnSceneLoaded(...)。
-    (void)object;
-}
-```
+- `Core::Event<Scene*>&` - 场景加载事件对象引用。
 
 ## 相关文档
 
-- [返回类总览](SceneManager.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](SceneManager.md)
+- [CreateScene](CreateScene.md)
+- [LoadScene](LoadScene.md)

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

@@ -1,30 +1,22 @@
 # SceneManager::OnSceneUnloaded
 
-公开方法，详见头文件声明。
+访问场景卸载事件。
 
 ```cpp
 Core::Event<Scene*>& OnSceneUnloaded();
 ```
 
-该方法声明于 `XCEngine/Scene/SceneManager.h`，当前页面用于固定 `SceneManager` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前头文件内联实现直接返回 `m_onSceneUnloaded` 的引用。
 
-**返回：** `Core::Event<Scene*>&` - 返回值语义详见头文件声明。
+该事件在 [UnloadScene](UnloadScene.md) 找到并真正移除场景时触发。
 
-**示例：**
+## 返回值
 
-```cpp
-#include <XCEngine/Scene/SceneManager.h>
-
-void Example() {
-    XCEngine::Components::SceneManager object;
-    // 根据上下文补齐参数后调用 SceneManager::OnSceneUnloaded(...)。
-    (void)object;
-}
-```
+- `Core::Event<Scene*>&` - 场景卸载事件对象引用。
 
 ## 相关文档
 
-- [返回类总览](SceneManager.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](SceneManager.md)
+- [UnloadScene](UnloadScene.md)

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)

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

@@ -1,44 +1,36 @@
 # SceneManager::SetActiveScene
 
-设置相关状态或配置。
-
-该方法在 `XCEngine/Scene/SceneManager.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
+设置活动场景。
 
 ```cpp
 void SetActiveScene(Scene* scene);
-```
-
-**参数：**
-- `scene` - 参数语义详见头文件声明。
-
-**返回：** `void` - 无返回值。
-
-## 重载 2: 声明
-
-```cpp
 void SetActiveScene(const std::string& sceneName);
 ```
 
-**参数：**
-- `sceneName` - 参数语义详见头文件声明。
+## 行为说明
 
-**返回：** `void` - 无返回值。
+当前有两个重载：
 
-**示例：**
+- 指针重载会在 `m_activeScene != scene` 时直接写入 `m_activeScene = scene`，然后触发 [OnActiveSceneChanged](OnActiveSceneChanged.md)。
+- 字符串重载会先在 `m_scenes` 中查找 key，找到后再调用指针重载。
 
-```cpp
-#include <XCEngine/Scene/SceneManager.h>
+## 参数
 
-void Example() {
-    XCEngine::Components::SceneManager object;
-    // 根据上下文补齐参数后调用 SceneManager::SetActiveScene(...)。
-    (void)object;
-}
-```
+- `scene` - 目标活动场景指针。
+- `sceneName` - 目标场景 key。
+
+## 返回值
+
+- 无。
+
+## 当前实现限制
+
+- 指针重载不会校验 `scene` 是否真的来自 `SceneManager` 当前持有的场景集合。
+- 当前不会同步 `Scene::SetActive()`。
+- 如果传入的指针就是当前活动场景，不会触发事件。
+- 传入 `nullptr` 时，如果当前活动场景非空，会把活动场景清空并触发切换事件。
 
 ## 相关文档
 
-- [返回类总览](SceneManager.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](SceneManager.md)
+- [GetActiveScene](GetActiveScene.md)

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

@@ -1,44 +1,41 @@
 # SceneManager::UnloadScene
 
-卸载资源或释放缓存。
-
-该方法在 `XCEngine/Scene/SceneManager.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
+卸载一个已登记场景。
 
 ```cpp
 void UnloadScene(Scene* scene);
-```
-
-**参数：**
-- `scene` - 参数语义详见头文件声明。
-
-**返回：** `void` - 无返回值。
-
-## 重载 2: 声明
-
-```cpp
 void UnloadScene(const std::string& sceneName);
 ```
 
-**参数：**
-- `sceneName` - 参数语义详见头文件声明。
+## 行为说明
 
-**返回：** `void` - 无返回值。
+当前有两个重载：
 
-**示例：**
+- 指针重载：
+  1. `scene == nullptr` 时直接返回。
+  2. 如果它正好是 `m_activeScene`，先把活动场景清空。
+  3. 在 `m_scenes` 里线性查找匹配指针。
+  4. 找到后触发 [OnSceneUnloaded](OnSceneUnloaded.md)，然后擦除。
+  5. 如果活动场景为空且仍有剩余场景，选择 `m_scenes.begin()` 作为新的活动场景，并触发 [OnActiveSceneChanged](OnActiveSceneChanged.md)。
+- 字符串重载：先按 key 查找，再转到指针重载。
 
-```cpp
-#include <XCEngine/Scene/SceneManager.h>
+## 参数
 
-void Example() {
-    XCEngine::Components::SceneManager object;
-    // 根据上下文补齐参数后调用 SceneManager::UnloadScene(...)。
-    (void)object;
-}
-```
+- `scene` - 待卸载场景指针。
+- `sceneName` - 待卸载场景 key。
+
+## 返回值
+
+- 无。
+
+## 当前实现限制
+
+- 后备活动场景来自 `unordered_map` 首元素，选择顺序不稳定。
+- 如果卸载的是最后一个活动场景，当前不会额外发出“活动场景变为 `nullptr`”的切换事件。
+- 指针重载内部需要线性扫描 map 找到匹配场景。
 
 ## 相关文档
 
-- [返回类总览](SceneManager.md)
-- [返回模块目录](../Scene.md)
+- [返回类型总览](SceneManager.md)
+- [OnSceneUnloaded](OnSceneUnloaded.md)
+- [OnActiveSceneChanged](OnActiveSceneChanged.md)

docs/api/_guides/Scene/Scene-Lifecycle-And-Serialization.md

@@ -0,0 +1,85 @@
+# Scene Lifecycle And Serialization
+
+## 为什么场景系统通常这样分层
+
+商业级游戏引擎很少把“场景”“对象”“组件”揉成一个类。更常见的拆法是：
+
+- 场景负责对象集合、根节点入口和存档边界。
+- 对象负责层级关系与生命周期转发。
+- 组件负责真正的可组合行为。
+
+`XCEngine` 当前的 `Scene` / `GameObject` / `Component` 关系基本就是这个思路，所以它看上去会比较像 Unity 风格的设计，而不是传统单一 Entity 容器。
+
+## `Scene` 真正负责什么
+
+当前 `Scene` 最核心的职责有三件事：
+
+1. 持有 `GameObject` 的唯一所有权。
+2. 从根对象入口驱动 `Update` / `FixedUpdate` / `LateUpdate`。
+3. 作为保存和加载的边界，把一整棵对象树序列化出去或重新建回来。
+
+这样做的好处是，场景可以被理解成“一个可整体保存、整体切换的运行时世界片段”。
+
+## 为什么要有根对象列表
+
+场景里既有对象树，又单独保存 `m_rootGameObjects`，这不是重复设计，而是为了让两件事都变简单：
+
+- 查“从哪里开始遍历场景”时，不用扫描全体对象找没有父节点的项。
+- 对象挂接和脱离父节点时，只要同步更新根列表即可。
+
+这是很多商用引擎场景树都会采用的做法，因为“根入口”和“局部子树”是两种不同维度的查询。
+
+## 当前 active 状态有两层，但还没有完全打通
+
+理解这块很重要：
+
+- `SceneManager::GetActiveScene()` 是“哪一个场景被管理器认为是当前活动场景”。
+- `Scene::IsActive()` 是 `Scene` 自己保存的一个布尔标志。
+- `GameObject::IsActiveInHierarchy()` 才是对象更新真正参与的门槛。
+
+在当前实现里，这三者并没有完全联动：
+
+- `Scene::SetActive(false)` 不会阻止 `Scene::Update()`。
+- `SceneManager::SetActiveScene()` 也不会自动改 `Scene::IsActive()`。
+
+这意味着现在更稳妥的理解方式是：
+
+- `SceneManager` 的 active scene 更接近“当前选中的场景引用”。
+- `Scene::m_active` 更接近“一个可保存的场景状态位”。
+
+## 序列化为什么用自定义文本格式
+
+当前 `Scene::SerializeToString()` 没有走 JSON，而是用了非常直接的文本块格式。这样做的现实好处是：
+
+- 实现简单。
+- 组件可以继续用自己的 `Serialize(std::ostream&)` 输出。
+- 调试时直接打开文本就能看见对象、父子关系和组件条目。
+
+但代价也很明确：
+
+- 格式是引擎私有的，没有版本协商。
+- 解析鲁棒性有限。
+- 组件恢复依赖 `ComponentFactoryRegistry`，组件名或注册表变化都会影响加载结果。
+
+## 当前最需要小心的几个事实
+
+- 场景析构不会自动为所有对象走显式销毁流程，所以不要把 `~Scene()` 当成完整生命周期清理器。
+- `FindGameObjectWithTag()` 现在其实是在按名字查。
+- `LoadSceneAsync()` 现在不是异步，更多只是一个名字上预留好的 API。
+- `LoadScene()` 后的管理器 key 来自文件名，而不是场景内部保存的 `scene=` 名称。
+
+## 实际使用建议
+
+如果你现在基于这套系统开发，比较稳妥的做法通常是：
+
+- 需要 `OnDestroy` 或场景事件时，显式调用对象销毁入口，不要只依赖场景析构。
+- 需要稳定查场景时，优先用 `CreateScene()` 的名称或加载文件的文件名 stem，不要假设一定等于场景内部名字。
+- 不要把 `LoadSceneAsync()` 当成真正的后台加载接口。
+- 不要把 `FindGameObjectWithTag()` 当成完整 tag 系统。
+
+## 相关 API
+
+- [Scene Module](../../XCEngine/Scene/Scene.md)
+- [Scene](../../XCEngine/Scene/Scene/Scene.md)
+- [SceneManager](../../XCEngine/Scene/SceneManager/SceneManager.md)
+- [GameObject](../../XCEngine/Components/GameObject/GameObject.md)

docs/api/_meta/rebuild-status.md

@@ -1,12 +1,12 @@
 # API 文档重构状态
 
-**生成时间**: `2026-03-26 18:01:19`
+**生成时间**: `2026-03-26 19:32:04`
 
 **来源**: `docs/api/_tools/audit_api_docs.py`
 
 ## 摘要
 
-- Markdown 页面数（全部）: `2444`
+- Markdown 页面数（全部）: `2445`
 - Markdown 页面数（canonical）: `2436`
 - Public headers 数: `185`
 - 有效头文件引用数（全部）: `185`