docs: expand gameobject helper docs

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)