xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: expand gameobject helper docs

Browse Source
This commit is contained in:
ssdfasd
2026-04-03 16:11:48 +08:00
parent ee44e14960
commit 2c2e1fab1c
34 changed files with 597 additions and 603 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
docs/api/XCEngine/Components/GameObject/AddComponent.md
View File

@@ -1,31 +1,44 @@
# GameObject::AddComponent # GameObject::AddComponent
添加元素或建立关联。 为当前对象添加一个普通组件，或返回已有的内建 `Transform`。
```cpp ```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() { - `Awake()`
XCEngine::Components::GameObject object; - `Start()`
// 根据上下文补齐参数后调用 GameObject::AddComponent(...)。 - `OnEnable()`
(void)object;
} 这是当前对象系统最重要的现实边界之一。组件挂载完成，不等于它已经追平生命周期进度。
```
## 所有权语义
- 普通组件的所有权由 `GameObject` 内部 `std::unique_ptr<Component>` 接管
- 返回值只是观察指针
- 调用方不应自行 `delete`
## 相关文档 ## 相关文档
- [返回类总览](GameObject.md) - [GameObject](GameObject.md)
- [返回模块目录](../Components.md) - [GetComponent](GetComponent.md)
- [RemoveComponent](RemoveComponent.md)
- [GetTransform](GetTransform.md)

26
docs/api/XCEngine/Components/GameObject/Awake.md
View File

@@ -1,30 +1,26 @@
# GameObject::Awake # GameObject::Awake
公开方法，详见头文件声明。 向当前对象的普通组件分发 `Awake()`。
```cpp ```cpp
void Awake(); 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() { - `Scene::CreateGameObject()` 创建对象后会立即调用它
XCEngine::Components::GameObject object; - 用户也可以手工直接调用，但这不等价于完整场景创建流程
// 根据上下文补齐参数后调用 GameObject::Awake(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](GameObject.md) - [Start](Start.md)
- [返回模块目录](../Components.md) - [Scene::CreateGameObject](../../Scene/Scene/CreateGameObject.md)

60
docs/api/XCEngine/Components/GameObject/Constructor.md
View File

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

32
docs/api/XCEngine/Components/GameObject/Destroy.md
View File

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

39
docs/api/XCEngine/Components/GameObject/Destructor.md
View File

@@ -1,29 +1,38 @@
# GameObject::~GameObject() # GameObject::Destructor
销毁对象并释放相关资源。 销毁 `GameObject` 自身持有的内建 `Transform` 与普通组件容器。
```cpp ```cpp
~GameObject(); ~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() { - 调用 [OnDestroy](OnDestroy.md)
XCEngine::Components::GameObject object; - 从全局 registry 中注销对象
// 对象离开作用域时会自动触发析构。 - 递归执行场景级销毁逻辑
}
``` 这些事情分别由更高层调用链负责：
- 场景托管对象通常由 [Scene::DestroyGameObject](../../Scene/Scene/DestroyGameObject.md) 或 `Scene` 析构处理
- 独立对象若想显式发送销毁通知，需要先调用 [Destroy](Destroy.md)
## 设计提示
在商业引擎对象系统里，“对象析构”与“游戏语义上的销毁”通常不是同一个层级。这里也是如此：析构更接近 C++ 所有权回收，而不是完整运行时销毁流程。
## 相关文档 ## 相关文档
- [返回类总览](GameObject.md) - [Destroy](Destroy.md)
- [返回模块目录](../Components.md) - [OnDestroy](OnDestroy.md)
- [GameObject](GameObject.md)

35
docs/api/XCEngine/Components/GameObject/DetachChildren.md
View File

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

28
docs/api/XCEngine/Components/GameObject/DetachFromParent.md
View File

@@ -1,30 +1,26 @@
# GameObject::DetachFromParent # GameObject::DetachFromParent
公开方法，详见头文件声明。 把当前对象从父节点分离，并保持世界空间变换。
```cpp ```cpp
void DetachFromParent(); 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) - [SetParent](SetParent.md)
- [返回模块目录](../Components.md) - [GetParent](GetParent.md)
- [DetachChildren](DetachChildren.md)

40
docs/api/XCEngine/Components/GameObject/Find.md
View File

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

30
docs/api/XCEngine/Components/GameObject/FindObjectsOfType.md
View File

@@ -1,30 +1,30 @@
# GameObject::FindObjectsOfType # GameObject::FindObjectsOfType
查找并返回匹配对象。 返回当前全局 registry 中已注册的全部 `GameObject`。
```cpp ```cpp
static std::vector<GameObject*> FindObjectsOfType(); 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() { - `std::vector<GameObject*>` - 当前已注册对象列表。
XCEngine::Components::GameObject object;
// 根据上下文补齐参数后调用 GameObject::FindObjectsOfType(...)。 ## 顺序语义
(void)object;
} 由于底层来自 `std::unordered_map`，返回顺序当前不构成稳定契约。
```
## 相关文档 ## 相关文档
- [返回类总览](GameObject.md) - [GameObject](GameObject.md)
- [返回模块目录](../Components.md) - [Find](Find.md)
- [FindGameObjectsWithTag](FindGameObjectsWithTag.md)

27
docs/api/XCEngine/Components/GameObject/FixedUpdate.md
View File

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

36
docs/api/XCEngine/Components/GameObject/GetChild.md
View File

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

29
docs/api/XCEngine/Components/GameObject/GetChildCount.md
View File

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

34
docs/api/XCEngine/Components/GameObject/GetChildren.md
View File

@@ -1,30 +1,34 @@
# GameObject::GetChildren # GameObject::GetChildren
获取相关状态或对象。 返回当前对象全部直接子对象的指针列表。
```cpp ```cpp
std::vector<GameObject*> GetChildren() const; 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() { 返回顺序与当前内部 `m_children` 顺序一致，也就是：
XCEngine::Components::GameObject object;
// 根据上下文补齐参数后调用 GameObject::GetChildren(...)。 - `SetParent()` 加入子对象时建立的顺序
(void)object; - 后续层级重排后形成的当前顺序
}
``` ## 返回值
- `std::vector<GameObject*>` - 当前全部直接子对象。
## 相关文档 ## 相关文档
- [返回类总览](GameObject.md) - [GetChild](GetChild.md)
- [返回模块目录](../Components.md) - [GetChildCount](GetChildCount.md)
- [DetachChildren](DetachChildren.md)

51
docs/api/XCEngine/Components/GameObject/GetComponent.md
View File

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

32
docs/api/XCEngine/Components/GameObject/GetComponentInChildren.md
View File

@@ -1,30 +1,30 @@
# GameObject::GetComponentInChildren # GameObject::GetComponentInChildren
获取相关状态或对象。 在当前对象及其子树中查找第一个匹配组件。
```cpp ```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() { 如果你需要收集整个子树中的所有匹配项，应使用 [GetComponentsInChildren](GetComponentsInChildren.md)。
XCEngine::Components::GameObject object;
// 根据上下文补齐参数后调用 GameObject::GetComponentInChildren(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](GameObject.md) - [GetComponent](GetComponent.md)
- [返回模块目录](../Components.md) - [GetComponentsInChildren](GetComponentsInChildren.md)
- [GetChild](GetChild.md)

32
docs/api/XCEngine/Components/GameObject/GetComponentInParent.md
View File

@@ -1,30 +1,30 @@
# GameObject::GetComponentInParent # GameObject::GetComponentInParent
获取相关状态或对象。 沿父链向上查找第一个匹配组件。
```cpp ```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(...)。 - 对宽类型查询，父对象的 `TransformComponent` 仍可能优先命中
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](GameObject.md) - [GetComponent](GetComponent.md)
- [返回模块目录](../Components.md) - [GetParent](GetParent.md)
- [GetComponentInChildren](GetComponentInChildren.md)

42
docs/api/XCEngine/Components/GameObject/GetComponents.md
View File

@@ -1,42 +1,32 @@
# GameObject::GetComponents # GameObject::GetComponents
获取相关状态或对象。 返回当前对象自身上的全部匹配组件。
该方法在 `XCEngine/Components/GameObject.h` 中提供了 2 个重载，当前页面统一汇总这些公开声明。 该方法当前提供两个公开重载：
## 重载 1: 声明
```cpp ```cpp
template<typename T> std::vector<T*> GetComponents(); 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*> 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; - `TransformComponent` 即使不在 `m_components` 中，只要类型匹配也会出现在结果里
// 根据上下文补齐参数后调用 GameObject::GetComponents(...)。 - 结果顺序受普通组件添加顺序影响
(void)object;
} `tests/Components/test_game_object.cpp` 中的 `GetComponents_Multiple` 已验证多个同类型普通组件会全部被返回。
```
## 相关文档 ## 相关文档
- [返回类总览](GameObject.md) - [GetComponent](GetComponent.md)
- [返回模块目录](../Components.md) - [GetComponentsInChildren](GetComponentsInChildren.md)
- [GetTransform](GetTransform.md)

32
docs/api/XCEngine/Components/GameObject/GetComponentsInChildren.md
View File

@@ -1,30 +1,30 @@
# GameObject::GetComponentsInChildren # GameObject::GetComponentsInChildren
获取相关状态或对象。 返回当前对象及其子树中的全部匹配组件。
```cpp ```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(...)。 - `TransformComponent` 只要类型匹配，同样会通过 [GetComponents](GetComponents.md) 出现在结果里
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](GameObject.md) - [GetComponents](GetComponents.md)
- [返回模块目录](../Components.md) - [GetComponentInChildren](GetComponentInChildren.md)
- [GetChildren](GetChildren.md)

28
docs/api/XCEngine/Components/GameObject/GetID.md
View File

@@ -1,30 +1,28 @@
# GameObject::GetID # GameObject::GetID
获取相关状态或对象。 返回当前对象的运行时 ID。
```cpp ```cpp
ID GetID() const; 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(...)。 - `GameObject::ID` - 当前对象 ID。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](GameObject.md) - [GetUUID](GetUUID.md)
- [返回模块目录](../Components.md) - [GameObject](GameObject.md)

27
docs/api/XCEngine/Components/GameObject/GetName.md
View File

@@ -1,30 +1,27 @@
# GameObject::GetName # GameObject::GetName
获取相关状态或对象。 返回当前对象名称。
```cpp ```cpp
const std::string& GetName() const; 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() { - `const std::string&` - 当前对象名的只读引用。
XCEngine::Components::GameObject object;
// 根据上下文补齐参数后调用 GameObject::GetName(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](GameObject.md) - [SetName](SetName.md)
- [返回模块目录](../Components.md) - [Find](Find.md)

27
docs/api/XCEngine/Components/GameObject/GetParent.md
View File

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

28
docs/api/XCEngine/Components/GameObject/GetScene.md
View File

@@ -1,30 +1,28 @@
# GameObject::GetScene # GameObject::GetScene
获取相关状态或对象。 返回当前对象所属的 `Scene`。
```cpp ```cpp
Scene* GetScene() const; 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() { - `Scene*` - 当前所属场景；独立对象返回 `nullptr`。
XCEngine::Components::GameObject object;
// 根据上下文补齐参数后调用 GameObject::GetScene(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](GameObject.md) - [GameObject](GameObject.md)
- [返回模块目录](../Components.md) - [Scene](../../Scene/Scene/Scene.md)
- [Deserialize](Deserialize.md)

46
docs/api/XCEngine/Components/GameObject/GetTransform.md
View File

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

25
docs/api/XCEngine/Components/GameObject/GetUUID.md
View File

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

26
docs/api/XCEngine/Components/GameObject/IsActive.md
View File

@@ -1,30 +1,26 @@
# GameObject::IsActive # GameObject::IsActive
查询当前状态。 返回对象自身的 `activeSelf` 状态。
```cpp ```cpp
bool IsActive() const; 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() { - `true` - 对象自身处于激活状态。
XCEngine::Components::GameObject object; - `false` - 对象自身被显式关闭。
// 根据上下文补齐参数后调用 GameObject::IsActive(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](GameObject.md) - [SetActive](SetActive.md)
- [返回模块目录](../Components.md) - [IsActiveInHierarchy](IsActiveInHierarchy.md)

28
docs/api/XCEngine/Components/GameObject/IsActiveInHierarchy.md
View File

@@ -1,30 +1,28 @@
# GameObject::IsActiveInHierarchy # GameObject::IsActiveInHierarchy
查询当前状态。 判断对象在当前父链下是否真正处于有效激活状态。
```cpp ```cpp
bool IsActiveInHierarchy() const; 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() { - `true` - 对象自己激活，且所有父节点也都激活。
XCEngine::Components::GameObject object; - `false` - 任一层不满足。
// 根据上下文补齐参数后调用 GameObject::IsActiveInHierarchy(...)。
(void)object;
}
```
## 相关文档 ## 相关文档
- [返回类总览](GameObject.md) - [IsActive](IsActive.md)
- [返回模块目录](../Components.md) - [SetActive](SetActive.md)
- [SetParent](SetParent.md)

28
docs/api/XCEngine/Components/GameObject/LateUpdate.md
View File

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

26
docs/api/XCEngine/Components/GameObject/OnDestroy.md
View File

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

56
docs/api/XCEngine/Components/GameObject/RemoveComponent.md
View File

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

41
docs/api/XCEngine/Components/GameObject/SetActive.md
View File

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

43
docs/api/XCEngine/Components/GameObject/SetName.md
View File

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

60
docs/api/XCEngine/Components/GameObject/SetParent.md
View File

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

31
docs/api/XCEngine/Components/GameObject/Start.md
View File

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

28
docs/api/XCEngine/Components/GameObject/Update.md
View File

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