docs: expand gameobject helper docs

docs/api/XCEngine/Components/GameObject/AddComponent.md

@@ -1,31 +1,44 @@
 # GameObject::AddComponent
 
-添加元素或建立关联。
+为当前对象添加一个普通组件，或返回已有的内建 `Transform`。
 
 ```cpp
-template<typename T, typename... Args> T* AddComponent(Args&&... args);
+template<typename T, typename... Args>
+T* AddComponent(Args&&... args);
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `args` - 参数语义详见头文件声明。
+当前模板实现分两条路径：
 
-**返回：** `template<typename T, typename... Args> T*` - 返回值语义详见头文件声明。
+- 如果 `T` 继承自 `TransformComponent`
+  - 直接返回已有 `m_transform`
+  - 不会创建第二个 `Transform`
+- 否则
+  - 构造一个新的组件实例
+  - 回填 `component->m_gameObject = this`
+  - 放入 `m_components`
+  - 返回新组件指针
 
-**示例：**
+## 当前不会自动发生什么
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+运行时添加普通组件时，当前实现**不会自动补发**：
 
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::AddComponent(...)。
-    (void)object;
-}
-```
+- `Awake()`
+- `Start()`
+- `OnEnable()`
+
+这是当前对象系统最重要的现实边界之一。组件挂载完成，不等于它已经追平生命周期进度。
+
+## 所有权语义
+
+- 普通组件的所有权由 `GameObject` 内部 `std::unique_ptr<Component>` 接管
+- 返回值只是观察指针
+- 调用方不应自行 `delete`
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [GameObject](GameObject.md)
+- [GetComponent](GetComponent.md)
+- [RemoveComponent](RemoveComponent.md)
+- [GetTransform](GetTransform.md)

docs/api/XCEngine/Components/GameObject/Awake.md

@@ -1,30 +1,26 @@
 # GameObject::Awake
 
-公开方法，详见头文件声明。
+向当前对象的普通组件分发 `Awake()`。
 
 ```cpp
 void Awake();
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现会遍历 `m_components`，并对每个普通组件调用 `Awake()`。
 
-**返回：** `void` - 无返回值。
+需要注意：
 
-**示例：**
+- 它不会递归调用子对象的 `Awake()`
+- `TransformComponent` 不在 `m_components` 中，因此不会在这里收到 `Awake()`
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+## 典型触发路径
 
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::Awake(...)。
-    (void)object;
-}
-```
+- `Scene::CreateGameObject()` 创建对象后会立即调用它
+- 用户也可以手工直接调用，但这不等价于完整场景创建流程
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [Start](Start.md)
+- [Scene::CreateGameObject](../../Scene/Scene/CreateGameObject.md)

docs/api/XCEngine/Components/GameObject/Constructor.md

@@ -1,41 +1,49 @@
-# GameObject::GameObject()
+# GameObject::Constructor
 
-构造对象。
+构造一个 `GameObject`。
 
-该方法在 `XCEngine/Components/GameObject.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
+`GameObject` 当前提供两个公开构造形式：
 
 ```cpp
 GameObject();
-```
-
-**参数：** 无。
-
-**返回：** `void` - 无返回值。
-
-## 重载 2: 声明
-
-```cpp
 explicit GameObject(const std::string& name);
 ```
 
-**参数：**
-- `name` - 参数语义详见头文件声明。
+## 默认构造行为
 
-**返回：** `void` - 无返回值。
+默认构造当前会建立如下初始状态：
 
-**示例：**
+- `name = "GameObject"`
+- `tag = "Untagged"`
+- `activeSelf = true`
+- `started = false`
+- `layer = 0`
+- `scene = nullptr`
+- `parent = nullptr`
+- 自动创建一个内建 `TransformComponent`
+- 分配新的递增 ID 与随机 UUID
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+`tests/Components/test_game_object.cpp` 中的 `DefaultConstructor_DefaultValues` 已验证默认 `tag`、`layer`、激活态和 `Transform` 都会按这套语义建立。
 
-void Example() {
-    XCEngine::Components::GameObject object;
-}
-```
+## 命名构造行为
+
+带 `name` 的构造只会把对象名替换为传入值，其他默认状态保持一致：
+
+- `tag` 仍是 `"Untagged"`
+- `layer` 仍是 `0`
+- 仍然会创建内建 `Transform`
+- 仍然不会自动加入任何 `Scene`
+
+## 重要边界
+
+- 直接构造对象不会自动注册到全局 registry
+- 不会自动触发 `Awake()`
+- 不会自动接入场景层级
+
+如果你需要完整运行时语义，应优先通过 [Scene::CreateGameObject](../../Scene/Scene/CreateGameObject.md) 创建。
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [GameObject](GameObject.md)
+- [GetTransform](GetTransform.md)
+- [Scene::CreateGameObject](../../Scene/Scene/CreateGameObject.md)

docs/api/XCEngine/Components/GameObject/Destroy.md

@@ -1,30 +1,32 @@
 # GameObject::Destroy
 
-公开方法，详见头文件声明。
+销毁当前对象。
 
 ```cpp
 void Destroy();
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现有两条分支：
 
-**返回：** `void` - 无返回值。
+- 如果对象属于某个 `Scene`
+  - 调用 `m_scene->DestroyGameObject(this)`
+- 如果对象不属于场景
+  - 只调用 `OnDestroy()`
 
-**示例：**
+## 重要边界
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+- 对场景托管对象来说，真正的移除、子树递归、事件分发和 registry 清理都在 `Scene::DestroyGameObject()` 里完成
+- 对独立对象来说，这个接口**不会释放对象自身内存**
+- 析构函数和 `Destroy()` 不是同一个语义层级
 
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::Destroy(...)。
-    (void)object;
-}
-```
+## 返回值
+
+- 无。
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [OnDestroy](OnDestroy.md)
+- [Scene::DestroyGameObject](../../Scene/Scene/DestroyGameObject.md)
+- [GameObject](GameObject.md)

docs/api/XCEngine/Components/GameObject/Destructor.md

@@ -1,29 +1,38 @@
-# GameObject::~GameObject()
+# GameObject::Destructor
 
-销毁对象并释放相关资源。
+销毁 `GameObject` 自身持有的内建 `Transform` 与普通组件容器。
 
 ```cpp
 ~GameObject();
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前析构实现会：
 
-**返回：** `void` - 无返回值。
+- 若 `m_transform` 存在，则先 `delete m_transform`
+- 将 `m_transform` 置空
+- 清空 `m_components`
 
-**示例：**
+## 当前不会自动发生什么
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+析构函数本身不会自动：
 
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 对象离开作用域时会自动触发析构。
-}
-```
+- 调用 [OnDestroy](OnDestroy.md)
+- 从全局 registry 中注销对象
+- 递归执行场景级销毁逻辑
+
+这些事情分别由更高层调用链负责：
+
+- 场景托管对象通常由 [Scene::DestroyGameObject](../../Scene/Scene/DestroyGameObject.md) 或 `Scene` 析构处理
+- 独立对象若想显式发送销毁通知，需要先调用 [Destroy](Destroy.md)
+
+## 设计提示
+
+在商业引擎对象系统里，“对象析构”与“游戏语义上的销毁”通常不是同一个层级。这里也是如此：析构更接近 C++ 所有权回收，而不是完整运行时销毁流程。
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [Destroy](Destroy.md)
+- [OnDestroy](OnDestroy.md)
+- [GameObject](GameObject.md)

docs/api/XCEngine/Components/GameObject/DetachChildren.md

@@ -1,30 +1,33 @@
 # GameObject::DetachChildren
 
-公开方法，详见头文件声明。
+把当前对象的所有直接子对象全部分离出去，并保持它们的世界空间变换。
 
 ```cpp
 void DetachChildren();
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
-
-**返回：** `void` - 无返回值。
-
-**示例：**
+当前实现会先复制一份 `m_children`，然后对副本中的每个子对象调用：
 
 ```cpp
-#include <XCEngine/Components/GameObject.h>
-
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::DetachChildren(...)。
-    (void)object;
-}
+child->SetParent(nullptr, true);
 ```
 
+这么做的目的，是避免在遍历过程中直接修改原始 `m_children` 容器导致迭代失效。
+
+## 结果语义
+
+调用完成后：
+
+- 当前对象的直接子列表会被清空
+- 每个原子对象都会变成根对象，或在无场景时变成无父独立对象
+- 每个子对象都会尽量保持原世界空间变换
+
+`tests/Components/test_game_object.cpp` 中的 `DetachChildren` 已验证父对象的 `GetChildCount()` 会从原值变成 `0`。
+
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [DetachFromParent](DetachFromParent.md)
+- [SetParent](SetParent.md)
+- [GetChildren](GetChildren.md)

docs/api/XCEngine/Components/GameObject/DetachFromParent.md

@@ -1,30 +1,26 @@
 # GameObject::DetachFromParent
 
-公开方法，详见头文件声明。
+把当前对象从父节点分离，并保持世界空间变换。
 
 ```cpp
 void DetachFromParent();
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现很直接：
 
-**返回：** `void` - 无返回值。
+- 如果当前没有父节点，直接返回
+- 否则调用 `SetParent(nullptr, true)`
 
-**示例：**
+因此它的真实语义是：
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
-
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::DetachFromParent(...)。
-    (void)object;
-}
-```
+- 把对象提升为根对象，或在无场景时变成无父独立对象
+- 保持当前世界空间位置/旋转/缩放
+- 同步更新场景根列表与层级激活态传播
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [SetParent](SetParent.md)
+- [GetParent](GetParent.md)
+- [DetachChildren](DetachChildren.md)

docs/api/XCEngine/Components/GameObject/Find.md

@@ -1,31 +1,37 @@
 # GameObject::Find
 
-查找并返回匹配对象。
+按对象名称在全局 registry 中查找第一个匹配的 `GameObject`。
 
 ```cpp
 static GameObject* Find(const std::string& name);
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `name` - 参数语义详见头文件声明。
-
-**返回：** `GameObject*` - 返回值语义详见头文件声明。
-
-**示例：**
+当前实现会遍历 `GameObject::GetGlobalRegistry()`，并检查：
 
 ```cpp
-#include <XCEngine/Components/GameObject.h>
-
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::Find(...)。
-    (void)object;
-}
+pair.second->GetName() == name
 ```
 
+找到第一个匹配项后立即返回。
+
+## 重要边界
+
+- 查询范围是全局 registry，不是某个 `Scene` 的局部子树
+- 独立构造、未加入场景的对象默认不会被查到
+- registry 底层是 `std::unordered_map`，因此“第一个匹配项”的顺序不构成稳定契约
+
+## 参数
+
+- `name` - 目标对象名。
+
+## 返回值
+
+- `GameObject*` - 找到时返回匹配对象；否则返回 `nullptr`。
+
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [GameObject](GameObject.md)
+- [FindObjectsOfType](FindObjectsOfType.md)
+- [FindGameObjectsWithTag](FindGameObjectsWithTag.md)

docs/api/XCEngine/Components/GameObject/FindObjectsOfType.md

@@ -1,30 +1,30 @@
 # GameObject::FindObjectsOfType
 
-查找并返回匹配对象。
+返回当前全局 registry 中已注册的全部 `GameObject`。
 
 ```cpp
 static std::vector<GameObject*> FindObjectsOfType();
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+虽然名字叫 `FindObjectsOfType()`，但对 `GameObject` 这个类来说，当前实现并不做额外类型过滤，而是：
 
-**返回：** `std::vector<GameObject*>` - 返回值语义详见头文件声明。
+- 遍历 `GameObject::GetGlobalRegistry()`
+- 把每个已注册对象都加入结果数组
 
-**示例：**
+所以它的真实语义更接近“返回当前所有已注册 `GameObject`”。
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+## 返回值
 
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::FindObjectsOfType(...)。
-    (void)object;
-}
-```
+- `std::vector<GameObject*>` - 当前已注册对象列表。
+
+## 顺序语义
+
+由于底层来自 `std::unordered_map`，返回顺序当前不构成稳定契约。
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [GameObject](GameObject.md)
+- [Find](Find.md)
+- [FindGameObjectsWithTag](FindGameObjectsWithTag.md)

docs/api/XCEngine/Components/GameObject/FixedUpdate.md

@@ -1,30 +1,23 @@
 # GameObject::FixedUpdate
 
-公开方法，详见头文件声明。
+向当前对象及其子树分发固定步长 `FixedUpdate()`。
 
 ```cpp
 void FixedUpdate();
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现会：
 
-**返回：** `void` - 无返回值。
+- 若对象不处于 `active in hierarchy`，直接返回
+- 对所有已启用普通组件调用 `FixedUpdate()`
+- 递归对子对象调用 `FixedUpdate()`
 
-**示例：**
-
-```cpp
-#include <XCEngine/Components/GameObject.h>
-
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::FixedUpdate(...)。
-    (void)object;
-}
-```
+它本身不接收 fixed delta 参数；固定步长配置由更上层运行时或场景驱动决定。
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [Update](Update.md)
+- [LateUpdate](LateUpdate.md)
+- [Scene::FixedUpdate](../../Scene/Scene/FixedUpdate.md)

docs/api/XCEngine/Components/GameObject/GetChild.md

@@ -1,31 +1,35 @@
 # GameObject::GetChild
 
-获取相关状态或对象。
+按索引返回当前对象的直接子对象。
 
 ```cpp
 GameObject* GetChild(size_t index) const;
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `index` - 参数语义详见头文件声明。
+当前实现只访问 `m_children`：
 
-**返回：** `GameObject*` - 返回值语义详见头文件声明。
+- 若 `index < m_children.size()`，返回对应子对象指针
+- 否则返回 `nullptr`
 
-**示例：**
+它不会递归搜索孙节点或更深层子树。
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+`tests/Components/test_game_object.cpp` 已验证：
 
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::GetChild(...)。
-    (void)object;
-}
-```
+- 有效索引会返回正确子对象
+- 越界索引会返回 `nullptr`
+
+## 参数
+
+- `index` - 直接子对象索引，基于当前 `m_children` 顺序。
+
+## 返回值
+
+- `GameObject*` - 对应直接子对象；越界时返回 `nullptr`。
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [GetChildCount](GetChildCount.md)
+- [GetChildren](GetChildren.md)
+- [SetParent](SetParent.md)

docs/api/XCEngine/Components/GameObject/GetChildCount.md

@@ -1,30 +1,29 @@
 # GameObject::GetChildCount
 
-获取相关状态或对象。
+返回当前对象的直接子对象数量。
 
 ```cpp
 size_t GetChildCount() const;
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现直接返回 `m_children.size()`。
 
-**返回：** `size_t` - 返回值语义详见头文件声明。
+因此：
 
-**示例：**
+- 统计的是“直接子对象”数量
+- 不包含孙节点或更深层子树
+- 与 [GetChild](GetChild.md) / [GetChildren](GetChildren.md) 共享同一份当前顺序
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+`tests/Components/test_game_object.cpp` 已验证在父对象挂入两个子对象后，这里会返回 `2`。
 
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::GetChildCount(...)。
-    (void)object;
-}
-```
+## 返回值
+
+- `size_t` - 当前直接子对象数量。
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [GetChild](GetChild.md)
+- [GetChildren](GetChildren.md)
+- [DetachChildren](DetachChildren.md)

docs/api/XCEngine/Components/GameObject/GetChildren.md

@@ -1,30 +1,34 @@
 # GameObject::GetChildren
 
-获取相关状态或对象。
+返回当前对象全部直接子对象的指针列表。
 
 ```cpp
 std::vector<GameObject*> GetChildren() const;
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现直接返回 `m_children` 的一份拷贝。
 
-**返回：** `std::vector<GameObject*>` - 返回值语义详见头文件声明。
+这意味着：
 
-**示例：**
+- 结果里的每一项都是直接子对象指针
+- 返回的是容器副本，不是对内部数组的可写引用
+- 修改返回的 `std::vector` 本身，不会改变对象真实层级
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+## 顺序语义
 
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::GetChildren(...)。
-    (void)object;
-}
-```
+返回顺序与当前内部 `m_children` 顺序一致，也就是：
+
+- `SetParent()` 加入子对象时建立的顺序
+- 后续层级重排后形成的当前顺序
+
+## 返回值
+
+- `std::vector<GameObject*>` - 当前全部直接子对象。
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [GetChild](GetChild.md)
+- [GetChildCount](GetChildCount.md)
+- [DetachChildren](DetachChildren.md)

docs/api/XCEngine/Components/GameObject/GetComponent.md

@@ -1,42 +1,41 @@
 # GameObject::GetComponent
 
-获取相关状态或对象。
+返回当前对象自身上的第一个匹配组件。
 
-该方法在 `XCEngine/Components/GameObject.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
+该方法当前提供两个公开重载：
 
 ```cpp
 template<typename T> T* GetComponent();
-```
-
-**参数：** 无。
-
-**返回：** `template<typename T> T*` - 返回值语义详见头文件声明。
-
-## 重载 2: 声明
-
-```cpp
 template<typename T> const T* GetComponent() const;
 ```
 
-**参数：** 无。
+## 搜索顺序
 
-**返回：** `template<typename T> const T*` - 返回值语义详见头文件声明。
+两个重载的搜索顺序一致：
 
-**示例：**
+1. 先尝试把内建 `m_transform` `dynamic_cast` 成 `T`
+2. 再按 `m_components` 当前顺序逐个 `dynamic_cast`
+3. 返回第一个命中的组件
+4. 全部没命中时返回 `nullptr`
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+## 当前语义边界
 
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::GetComponent(...)。
-    (void)object;
-}
-```
+- 只搜索“当前对象自身”，不会递归到父节点或子节点
+- `TransformComponent` 是特例：虽然它不在 `m_components` 中，但这里仍可能最先返回它
+- 对普通组件来说，多个同类型组件时只返回第一个匹配项
+
+这也意味着像 `GetComponent<Component>()` 这种宽类型查询，当前很可能先拿到 `TransformComponent`，因为它会在普通组件之前被检查。
+
+## 测试锚点
+
+`tests/Components/test_game_object.cpp` 当前验证了：
+
+- 添加后的普通组件可以被 `GetComponent<T>()` 找回
+- 不存在目标类型时返回 `nullptr`
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [GetComponents](GetComponents.md)
+- [GetComponentInChildren](GetComponentInChildren.md)
+- [GetComponentInParent](GetComponentInParent.md)
+- [GetTransform](GetTransform.md)

docs/api/XCEngine/Components/GameObject/GetComponentInChildren.md

@@ -1,30 +1,30 @@
 # GameObject::GetComponentInChildren
 
-获取相关状态或对象。
+在当前对象及其子树中查找第一个匹配组件。
 
 ```cpp
-template<typename T> T* GetComponentInChildren();
+template<typename T>
+T* GetComponentInChildren();
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 搜索顺序
 
-**参数：** 无。
+当前实现按深度优先方式搜索：
 
-**返回：** `template<typename T> T*` - 返回值语义详见头文件声明。
+1. 先对当前对象自身调用 [GetComponent](GetComponent.md)
+2. 若当前对象没找到，再按 `m_children` 当前顺序递归搜索每个子对象
+3. 找到第一个命中项后立即返回
 
-**示例：**
+## 当前语义边界
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+- 搜索范围包含“当前对象自己”
+- `TransformComponent` 仍然可能因 [GetComponent](GetComponent.md) 的特例路径而最先命中
+- 返回的是第一个匹配项，不会收集全部结果
 
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::GetComponentInChildren(...)。
-    (void)object;
-}
-```
+如果你需要收集整个子树中的所有匹配项，应使用 [GetComponentsInChildren](GetComponentsInChildren.md)。
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [GetComponent](GetComponent.md)
+- [GetComponentsInChildren](GetComponentsInChildren.md)
+- [GetChild](GetChild.md)

docs/api/XCEngine/Components/GameObject/GetComponentInParent.md

@@ -1,30 +1,30 @@
 # GameObject::GetComponentInParent
 
-获取相关状态或对象。
+沿父链向上查找第一个匹配组件。
 
 ```cpp
-template<typename T> T* GetComponentInParent();
+template<typename T>
+T* GetComponentInParent();
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 搜索顺序
 
-**参数：** 无。
+当前实现不会先检查当前对象自己，而是：
 
-**返回：** `template<typename T> T*` - 返回值语义详见头文件声明。
+1. 先看当前对象是否存在父节点
+2. 对父对象调用 [GetComponent](GetComponent.md)
+3. 若父对象未命中，则继续递归向更高层父节点查询
 
-**示例：**
+因此它返回的是“最近祖先链上第一个匹配组件”。
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+## 当前语义边界
 
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::GetComponentInParent(...)。
-    (void)object;
-}
-```
+- 搜索范围不包含当前对象自己
+- 若父对象存在匹配项，就不会继续往更高祖先找
+- 对宽类型查询，父对象的 `TransformComponent` 仍可能优先命中
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [GetComponent](GetComponent.md)
+- [GetParent](GetParent.md)
+- [GetComponentInChildren](GetComponentInChildren.md)

docs/api/XCEngine/Components/GameObject/GetComponents.md

@@ -1,42 +1,32 @@
 # GameObject::GetComponents
 
-获取相关状态或对象。
+返回当前对象自身上的全部匹配组件。
 
-该方法在 `XCEngine/Components/GameObject.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
+该方法当前提供两个公开重载：
 
 ```cpp
 template<typename T> std::vector<T*> GetComponents();
-```
-
-**参数：** 无。
-
-**返回：** `template<typename T> std::vector<T*>` - 返回值语义详见头文件声明。
-
-## 重载 2: 声明
-
-```cpp
 template<typename T> std::vector<const T*> GetComponents() const;
 ```
 
-**参数：** 无。
+## 收集顺序
 
-**返回：** `template<typename T> std::vector<const T*>` - 返回值语义详见头文件声明。
+两个重载的收集顺序一致：
 
-**示例：**
+1. 先尝试把内建 `m_transform` `dynamic_cast` 成 `T`
+2. 若命中，则先把它加入结果
+3. 再按 `m_components` 当前顺序，把所有匹配普通组件追加到结果
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+## 当前语义边界
 
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::GetComponents(...)。
-    (void)object;
-}
-```
+- 只收集当前对象自身，不递归父节点或子节点
+- `TransformComponent` 即使不在 `m_components` 中，只要类型匹配也会出现在结果里
+- 结果顺序受普通组件添加顺序影响
+
+`tests/Components/test_game_object.cpp` 中的 `GetComponents_Multiple` 已验证多个同类型普通组件会全部被返回。
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [GetComponent](GetComponent.md)
+- [GetComponentsInChildren](GetComponentsInChildren.md)
+- [GetTransform](GetTransform.md)

docs/api/XCEngine/Components/GameObject/GetComponentsInChildren.md

@@ -1,30 +1,30 @@
 # GameObject::GetComponentsInChildren
 
-获取相关状态或对象。
+返回当前对象及其子树中的全部匹配组件。
 
 ```cpp
-template<typename T> std::vector<T*> GetComponentsInChildren();
+template<typename T>
+std::vector<T*> GetComponentsInChildren();
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 收集顺序
 
-**参数：** 无。
+当前实现会：
 
-**返回：** `template<typename T> std::vector<T*>` - 返回值语义详见头文件声明。
+1. 先调用当前对象自己的 [GetComponents](GetComponents.md)
+2. 再按 `m_children` 当前顺序递归调用每个子对象的 `GetComponentsInChildren<T>()`
+3. 把每个子树结果依次追加到总数组
 
-**示例：**
+因此它的结果语义是“当前对象优先，然后按子树深度优先展开”。
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+## 当前语义边界
 
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::GetComponentsInChildren(...)。
-    (void)object;
-}
-```
+- 搜索范围包含当前对象自己
+- 返回全部匹配项，而不是第一个
+- `TransformComponent` 只要类型匹配，同样会通过 [GetComponents](GetComponents.md) 出现在结果里
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [GetComponents](GetComponents.md)
+- [GetComponentInChildren](GetComponentInChildren.md)
+- [GetChildren](GetChildren.md)

docs/api/XCEngine/Components/GameObject/GetID.md

@@ -1,30 +1,28 @@
 # GameObject::GetID
 
-获取相关状态或对象。
+返回当前对象的运行时 ID。
 
 ```cpp
 ID GetID() const;
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前 `ID` 是 `uint64_t` 别名，默认由静态递增计数 `s_nextID` 分配。
 
-**返回：** `ID` - 返回值语义详见头文件声明。
+按当前实现：
 
-**示例：**
+- 默认构造出的对象会得到非零 ID
+- 场景反序列化时，文本中的 `id` 可能覆盖当前对象 ID
+- 反序列化结束后，`s_nextID` 会推进到当前最大 ID 之后
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+因此它适合作为当前运行时与编辑器里的对象句柄，但不应把它理解成天然不可变的全局永久标识。
 
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::GetID(...)。
-    (void)object;
-}
-```
+## 返回值
+
+- `GameObject::ID` - 当前对象 ID。
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [GetUUID](GetUUID.md)
+- [GameObject](GameObject.md)

docs/api/XCEngine/Components/GameObject/GetName.md

@@ -1,30 +1,27 @@
 # GameObject::GetName
 
-获取相关状态或对象。
+返回当前对象名称。
 
 ```cpp
 const std::string& GetName() const;
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+这个接口直接返回底层 `m_name` 的只读引用。
 
-**返回：** `const std::string&` - 返回值语义详见头文件声明。
+按当前实现：
 
-**示例：**
+- 默认构造名称是 `"GameObject"`
+- 带参构造会把名字初始化为传入值
+- [SetName](SetName.md) 直接改写这个字段
+- [Find](Find.md) 每次查询时都会读取当前名字
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+## 返回值
 
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::GetName(...)。
-    (void)object;
-}
-```
+- `const std::string&` - 当前对象名的只读引用。
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [SetName](SetName.md)
+- [Find](Find.md)

docs/api/XCEngine/Components/GameObject/GetParent.md

@@ -1,30 +1,27 @@
 # GameObject::GetParent
 
-获取相关状态或对象。
+返回当前对象的直接父对象。
 
 ```cpp
 GameObject* GetParent() const;
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现直接返回底层 `m_parent`。
 
-**返回：** `GameObject*` - 返回值语义详见头文件声明。
+因此：
 
-**示例：**
+- 有父节点时返回对应直接父对象
+- 根对象或独立对象返回 `nullptr`
+- 不会递归查更高祖先
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+## 返回值
 
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::GetParent(...)。
-    (void)object;
-}
-```
+- `GameObject*` - 当前直接父对象；没有父节点时返回 `nullptr`。
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [SetParent](SetParent.md)
+- [DetachFromParent](DetachFromParent.md)
+- [GetScene](GetScene.md)

docs/api/XCEngine/Components/GameObject/GetScene.md

@@ -1,30 +1,28 @@
 # GameObject::GetScene
 
-获取相关状态或对象。
+返回当前对象所属的 `Scene`。
 
 ```cpp
 Scene* GetScene() const;
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+这个接口直接返回底层 `m_scene` 指针。
 
-**返回：** `Scene*` - 返回值语义详见头文件声明。
+按当前实现：
 
-**示例：**
+- 直接构造的独立对象默认返回 `nullptr`
+- `Scene::CreateGameObject()` 创建的对象会返回所属场景
+- `Scene::DeserializeFromString()` 恢复出来的对象也会写回所属场景
+- 单对象 [Deserialize](Deserialize.md) 不会设置这个指针
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+## 返回值
 
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::GetScene(...)。
-    (void)object;
-}
-```
+- `Scene*` - 当前所属场景；独立对象返回 `nullptr`。
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [GameObject](GameObject.md)
+- [Scene](../../Scene/Scene/Scene.md)
+- [Deserialize](Deserialize.md)

docs/api/XCEngine/Components/GameObject/GetTransform.md

@@ -1,42 +1,36 @@
 # GameObject::GetTransform
 
-获取相关状态或对象。
+返回当前对象的内建 `TransformComponent`。
 
-该方法在 `XCEngine/Components/GameObject.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
+该方法当前提供两个公开重载：
 
 ```cpp
 TransformComponent* GetTransform();
-```
-
-**参数：** 无。
-
-**返回：** `TransformComponent*` - 返回值语义详见头文件声明。
-
-## 重载 2: 声明
-
-```cpp
 const TransformComponent* GetTransform() const;
 ```
 
-**参数：** 无。
+## 行为说明
 
-**返回：** `const TransformComponent*` - 返回值语义详见头文件声明。
+两个重载都直接返回底层 `m_transform` 指针。
 
-**示例：**
+按当前对象模型：
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+- 每个 `GameObject` 构造时都会创建一个 `TransformComponent`
+- `AddComponent<TransformComponent>()` 也只是返回这同一份实例
+- `RemoveComponent()` 不允许移除它
 
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::GetTransform(...)。
-    (void)object;
-}
-```
+因此在正常存活期内，这个接口应始终返回非空指针。
+
+## 为什么它不是普通组件查询的简单别名
+
+虽然 [GetComponent](GetComponent.md) 也可能返回 `TransformComponent`，但 `GetTransform()` 更明确：
+
+- 它直接表达“我要对象的内建 Transform”
+- 不受模板匹配与搜索顺序歧义影响
+- 对编辑器、脚本桥接和空间变换代码更可读
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [GetComponent](GetComponent.md)
+- [AddComponent](AddComponent.md)
+- [TransformComponent](../TransformComponent/TransformComponent.md)

docs/api/XCEngine/Components/GameObject/GetUUID.md

@@ -1,30 +1,23 @@
 # GameObject::GetUUID
 
-获取相关状态或对象。
+返回当前对象的 64 位 UUID。
 
 ```cpp
 uint64_t GetUUID() const;
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前默认构造会通过随机数分布生成一个 UUID；场景反序列化和单对象反序列化也可能恢复文本里已有的 UUID。
 
-**返回：** `uint64_t` - 返回值语义详见头文件声明。
+与 [GetID](GetID.md) 相比，UUID 更适合表达跨保存/加载流程的稳定对象引用。当前脚本字段与若干编辑器工具也更常通过 UUID 跟踪对象。
 
-**示例：**
+## 返回值
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
-
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::GetUUID(...)。
-    (void)object;
-}
-```
+- `uint64_t` - 当前对象 UUID。
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [GetID](GetID.md)
+- [Serialize](Serialize.md)
+- [Scene::SerializeToString](../../Scene/Scene/SerializeToString.md)

docs/api/XCEngine/Components/GameObject/IsActive.md

@@ -1,30 +1,26 @@
 # GameObject::IsActive
 
-查询当前状态。
+返回对象自身的 `activeSelf` 状态。
 
 ```cpp
 bool IsActive() const;
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+这个接口只读 `m_activeSelf`，不考虑父对象状态。
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+因此：
 
-**示例：**
+- 返回 `true` 不代表对象一定在运行
+- 只要父链中有对象失活，[IsActiveInHierarchy](IsActiveInHierarchy.md) 仍可能返回 `false`
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+## 返回值
 
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::IsActive(...)。
-    (void)object;
-}
-```
+- `true` - 对象自身处于激活状态。
+- `false` - 对象自身被显式关闭。
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [SetActive](SetActive.md)
+- [IsActiveInHierarchy](IsActiveInHierarchy.md)

docs/api/XCEngine/Components/GameObject/IsActiveInHierarchy.md

@@ -1,30 +1,28 @@
 # GameObject::IsActiveInHierarchy
 
-查询当前状态。
+判断对象在当前父链下是否真正处于有效激活状态。
 
 ```cpp
 bool IsActiveInHierarchy() const;
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现规则很直接：
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+- 如果对象自己的 `m_activeSelf == false`，返回 `false`
+- 否则若存在父对象，则递归询问父对象 `IsActiveInHierarchy()`
+- 没有父对象时返回 `true`
 
-**示例：**
+因此它表达的是“这个对象现在是否真的处于运行层级里”，而不是“它自己有没有被勾选 active”。
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+## 返回值
 
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::IsActiveInHierarchy(...)。
-    (void)object;
-}
-```
+- `true` - 对象自己激活，且所有父节点也都激活。
+- `false` - 任一层不满足。
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [IsActive](IsActive.md)
+- [SetActive](SetActive.md)
+- [SetParent](SetParent.md)

docs/api/XCEngine/Components/GameObject/LateUpdate.md

@@ -1,31 +1,25 @@
 # GameObject::LateUpdate
 
-公开方法，详见头文件声明。
+向当前对象及其子树分发 `LateUpdate(deltaTime)`。
 
 ```cpp
 void LateUpdate(float deltaTime);
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `deltaTime` - 参数语义详见头文件声明。
+当前实现会：
 
-**返回：** `void` - 无返回值。
+- 若对象不处于 `active in hierarchy`，直接返回
+- 对所有已启用普通组件调用 `LateUpdate(deltaTime)`
+- 递归对子对象调用 `LateUpdate(deltaTime)`
 
-**示例：**
+## 参数
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
-
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::LateUpdate(...)。
-    (void)object;
-}
-```
+- `deltaTime` - 当前变步长帧时间。
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [Update](Update.md)
+- [FixedUpdate](FixedUpdate.md)
+- [Scene::LateUpdate](../../Scene/Scene/LateUpdate.md)

docs/api/XCEngine/Components/GameObject/OnDestroy.md

@@ -1,30 +1,22 @@
 # GameObject::OnDestroy
 
-公开方法，详见头文件声明。
+向当前对象的普通组件分发销毁通知。
 
 ```cpp
 void OnDestroy();
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现会遍历 `m_components`，并对每个普通组件调用 `OnDestroy()`。
 
-**返回：** `void` - 无返回值。
+需要注意：
 
-**示例：**
-
-```cpp
-#include <XCEngine/Components/GameObject.h>
-
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::OnDestroy(...)。
-    (void)object;
-}
-```
+- 它不会递归销毁子对象；子对象销毁由 `Scene::DestroyGameObject()` 递归控制
+- `TransformComponent` 不在 `m_components` 中，因此不会在这里收到 `OnDestroy()`
+- 析构函数本身不会自动调用这个接口
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [Destroy](Destroy.md)
+- [Scene::DestroyGameObject](../../Scene/Scene/DestroyGameObject.md)

docs/api/XCEngine/Components/GameObject/RemoveComponent.md

@@ -1,43 +1,45 @@
 # GameObject::RemoveComponent
 
-移除元素或解除关联。
+从当前对象身上移除普通组件。
 
-该方法在 `XCEngine/Components/GameObject.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
+该方法当前提供两个公开重载：
 
 ```cpp
 template<typename T> void RemoveComponent();
-```
-
-**参数：** 无。
-
-**返回：** `template<typename T> void` - 返回值语义详见头文件声明。
-
-## 重载 2: 声明
-
-```cpp
 bool RemoveComponent(Component* component);
 ```
 
-**参数：**
-- `component` - 参数语义详见头文件声明。
+## 当前实现行为
 
-**返回：** `bool` - 返回值语义详见头文件声明。
+### 模板重载
 
-**示例：**
+- 如果模板参数命中内建 `TransformComponent`，直接返回，不允许移除 `Transform`
+- 否则按 `m_components` 顺序找到第一个能 `dynamic_cast` 成 `T` 的普通组件
+- 命中后立即 `erase(it)`，然后返回
+- 没找到时静默 no-op
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+### 指针重载
 
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::RemoveComponent(...)。
-    (void)object;
-}
-```
+- 传入 `nullptr` 时返回 `false`
+- 传入当前 `m_transform` 时返回 `false`
+- 否则按指针地址在 `m_components` 中查找精确同一实例
+- 找到则 `erase(it)` 并返回 `true`
+- 没找到则返回 `false`
+
+## 当前语义边界
+
+- 两个重载都只处理普通组件，不会移除内建 `Transform`
+- 当前实现只是直接擦除 `std::unique_ptr`，不会先补发 [OnDestroy](OnDestroy.md)
+- 模板重载只移除第一个匹配类型，不会批量移除全部同类组件
+
+## 返回值
+
+- 模板重载无返回值
+- 指针重载返回是否成功移除了那一份具体组件实例
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [AddComponent](AddComponent.md)
+- [GetComponent](GetComponent.md)
+- [GetComponents](GetComponents.md)
+- [GetTransform](GetTransform.md)

docs/api/XCEngine/Components/GameObject/SetActive.md

@@ -1,31 +1,40 @@
 # GameObject::SetActive
 
-设置相关状态或配置。
+设置对象自身的 `activeSelf` 状态，并在必要时重新传播层级有效激活态。
 
 ```cpp
 void SetActive(bool active);
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `active` - 参数语义详见头文件声明。
+当前实现会先比较新旧 `m_activeSelf`：
 
-**返回：** `void` - 无返回值。
+- 如果值没有变化，直接返回
+- 如果值变化，重新计算对象当前的 `active in hierarchy`
 
-**示例：**
+当“层级有效激活态”发生变化时，当前实现会：
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+- 对已启用的普通组件发送 `OnEnable()` 或 `OnDisable()`
+- 把变化递归传播到子对象
 
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::SetActive(...)。
-    (void)object;
-}
-```
+## 重要边界
+
+- 它改的是对象自己的 `activeSelf`，不是直接改父子层级
+- 真正是否参与运行，还要结合 [IsActiveInHierarchy](IsActiveInHierarchy.md) 判断
+- `TransformComponent` 不参与普通组件遍历，因此不会在这里收到 `OnEnable()` / `OnDisable()`
+
+## 参数
+
+- `active` - 新的 `activeSelf` 值。
+
+## 返回值
+
+- 无。
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [GameObject](GameObject.md)
+- [IsActive](IsActive.md)
+- [IsActiveInHierarchy](IsActiveInHierarchy.md)
+- [SetParent](SetParent.md)

docs/api/XCEngine/Components/GameObject/SetName.md

@@ -1,31 +1,40 @@
 # GameObject::SetName
 
-设置相关状态或配置。
+设置当前对象名称。
 
 ```cpp
 void SetName(const std::string& name);
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `name` - 参数语义详见头文件声明。
-
-**返回：** `void` - 无返回值。
-
-**示例：**
+当前实现就是一次直接赋值：
 
 ```cpp
-#include <XCEngine/Components/GameObject.h>
-
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::SetName(...)。
-    (void)object;
-}
+m_name = name;
 ```
 
+因此它不会自动做以下事情：
+
+- 名称合法性校验
+- 重名去重
+- 空字符串回退
+- 级联修改 tag 或其他元数据
+
+## 运行时影响
+
+- 之后的 [GetName](GetName.md) 会立即返回新值
+- 若对象已注册到全局 registry，后续 [Find](Find.md) 也会按新名字参与匹配
+
+## 参数
+
+- `name` - 新对象名。
+
+## 返回值
+
+- 无。
+
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [GetName](GetName.md)
+- [Find](Find.md)

docs/api/XCEngine/Components/GameObject/SetParent.md

@@ -1,45 +1,47 @@
 # GameObject::SetParent
 
-设置相关状态或配置。
+修改对象的父节点，并同步场景根列表、`Transform` 层级与激活态传播。
 
-该方法在 `XCEngine/Components/GameObject.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。
-
-## 重载 1: 声明
+该方法当前提供两个公开重载：
 
 ```cpp
 void SetParent(GameObject* parent);
-```
-
-**参数：**
-- `parent` - 参数语义详见头文件声明。
-
-**返回：** `void` - 无返回值。
-
-## 重载 2: 声明
-
-```cpp
 void SetParent(GameObject* parent, bool worldPositionStays);
 ```
 
-**参数：**
-- `parent` - 参数语义详见头文件声明。
-- `worldPositionStays` - 参数语义详见头文件声明。
+## 重载关系
 
-**返回：** `void` - 无返回值。
+- `SetParent(parent)` 当前等价于 `SetParent(parent, true)`
+- `worldPositionStays` 会继续传给 `TransformComponent::SetParent(...)`
 
-**示例：**
+## 行为说明
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
+当前实现会处理以下事情：
 
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::SetParent(...)。
-    (void)object;
-}
-```
+- 若目标父节点与当前父节点相同，直接返回
+- 若 `parent == this`，直接返回
+- 从旧父节点子列表或场景根列表中移除当前对象
+- 更新 `m_parent`
+- 加入新父节点的子列表，或重新进入场景根列表
+- 调用 `GetTransform()->SetParent(...)`
+- 如有需要，重新传播 `active in hierarchy` 变化
+
+## 参数
+
+- `parent` - 新父对象；传 `nullptr` 表示把对象变成根对象。
+- `worldPositionStays` - 是否尽量保持当前世界空间变换。
+
+## 返回值
+
+- 无。
+
+## 设计提示
+
+把“对象层级”和“Transform 层级”同时更新，是商业引擎对象系统的必要一致性要求。否则编辑器看到的对象树和运行时空间层级会很容易脱节。
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [GameObject](GameObject.md)
+- [GetParent](GetParent.md)
+- [DetachFromParent](DetachFromParent.md)
+- [SetActive](SetActive.md)

docs/api/XCEngine/Components/GameObject/Start.md

@@ -1,30 +1,29 @@
 # GameObject::Start
 
-公开方法，详见头文件声明。
+向当前对象及其子树分发一次性的 `Start()` 阶段。
 
 ```cpp
 void Start();
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：** 无。
+当前实现分两步：
 
-**返回：** `void` - 无返回值。
+1. 若对象不处于 `active in hierarchy`，直接返回
+2. 若对象尚未 `m_started`
+   - 对所有已启用普通组件调用 `Start()`
+   - 把 `m_started` 置为 `true`
+3. 无论当前对象是否第一次启动，都会继续递归对子对象调用 `Start()`
 
-**示例：**
+## 重要边界
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
-
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::Start(...)。
-    (void)object;
-}
-```
+- 每个对象自己的 `Start()` 只会自动执行一次
+- 子对象也通过这个递归链进入 `Start()`
+- 运行时后加的组件不会因为对象已启动过而自动补发 `Start()`
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [Awake](Awake.md)
+- [Update](Update.md)
+- [IsActiveInHierarchy](IsActiveInHierarchy.md)

docs/api/XCEngine/Components/GameObject/Update.md

@@ -1,31 +1,25 @@
 # GameObject::Update
 
-更新运行时状态。
+向当前对象及其子树分发逐帧 `Update(deltaTime)`。
 
 ```cpp
 void Update(float deltaTime);
 ```
 
-该方法声明于 `XCEngine/Components/GameObject.h`，当前页面用于固定 `GameObject` 类目录下的方法级 canonical 路径。
+## 行为说明
 
-**参数：**
-- `deltaTime` - 参数语义详见头文件声明。
+当前实现会：
 
-**返回：** `void` - 无返回值。
+- 若对象不处于 `active in hierarchy`，直接返回
+- 对所有已启用普通组件调用 `Update(deltaTime)`
+- 递归对子对象调用 `Update(deltaTime)`
 
-**示例：**
+## 参数
 
-```cpp
-#include <XCEngine/Components/GameObject.h>
-
-void Example() {
-    XCEngine::Components::GameObject object;
-    // 根据上下文补齐参数后调用 GameObject::Update(...)。
-    (void)object;
-}
-```
+- `deltaTime` - 当前变步长帧时间。
 
 ## 相关文档
 
-- [返回类总览](GameObject.md)
-- [返回模块目录](../Components.md)
+- [Start](Start.md)
+- [FixedUpdate](FixedUpdate.md)
+- [LateUpdate](LateUpdate.md)