XCEngine/docs/api/components/game-object/game-object.md

# GameObject

**命名空间**: `XCEngine::Components`

**类型**: `class`

**头文件**: `XCEngine/Components/GameObject.h`

**描述**: ECS 架构中的游戏对象实体，可附加组件并形成层级结构。

## 概述

GameObject 是 XCEngine ECS 架构中的实体（Entity）类，代表游戏世界中的一个个对象（如角色、道具、光源等）。每个 GameObject 可以通过 AddComponent 附加各种组件（如 TransformComponent、AudioSourceComponent）来定义其行为和数据。GameObject 支持层级结构（父子关系）、名称查找、标签系统和生命周期管理。

## 类型别名

| 别名 | 类型 | 描述 |
|------|------|------|
| `ID` | `uint64_t` | 游戏对象唯一标识符类型 |
| `INVALID_ID` | `static constexpr ID` | 无效 ID 常量，值为 0 |

## 公共方法

### 基础信息

| 方法 | 描述 |
|------|------|
| [`GetID`](get-id.md) | 获取唯一标识符 |
| [`GetUUID`](get-uuid.md) | 获取全局唯一标识符 |
| [`GetName`](get-name.md) | 获取名称 |
| [`SetName`](set-name.md) | 设置名称 |
| [`GetScene`](get-scene.md) | 获取所属场景 |

### 组件系统

| 方法 | 描述 |
|------|------|
| [`GetTransform`](get-transform.md) | 获取变换组件 |
| [`AddComponent`](add-component.md) | 添加组件（模板方法） |
| [`GetComponent`](get-component.md) | 获取组件（模板方法） |
| [`GetComponents`](get-components.md) | 获取所有指定类型组件（模板方法） |
| [`GetComponentInChildren`](get-component-in-children.md) | 在子对象中查找组件 |
| [`GetComponentInParent`](get-component-in-parent.md) | 在父对象中查找组件 |
| [`GetComponentsInChildren`](get-components-in-children.md) | 获取所有子对象的指定组件 |
| [`RemoveComponent`](remove-component.md) | 移除组件（模板方法） |

### 层级结构

| 方法 | 描述 |
|------|------|
| [`DetachFromParent`](detach-from-parent.md) | 从父对象分离 |
| [`GetParent`](get-parent.md) | 获取父对象 |
| [`SetParent`](set-parent.md) | 设置父对象 |
| [`GetChildCount`](get-child-count.md) | 获取子对象数量 |
| [`GetChild`](get-child.md) | 获取指定索引的子对象 |
| [`GetChildren`](get-children.md) | 获取所有子对象 |
| [`DetachChildren`](detach-children.md) | 分离所有子对象 |

### 激活状态

| 方法 | 描述 |
|------|------|
| [`IsActive`](is-active.md) | 检查自身激活状态 |
| [`SetActive`](set-active.md) | 设置激活状态 |
| [`IsActiveInHierarchy`](is-active-in-hierarchy.md) | 检查在层级中的激活状态 |

### 静态查找

| 方法 | 描述 |
|------|------|
| [`Find`](find.md) | 查找指定名称的对象 |
| [`FindObjectsOfType`](find-objects-of-type.md) | 查找所有对象 |
| [`FindGameObjectsWithTag`](find-game-objects-with-tag.md) | 查找具有指定标签的对象 |

### 生命周期

| 方法 | 描述 |
|------|------|
| [`Awake`](awake.md) | 唤醒对象 |
| [`Start`](start.md) | 开始对象 |
| [`Update`](update.md) | 每帧更新 |
| [`FixedUpdate`](fixed-update.md) | 固定频率更新 |
| [`LateUpdate`](late-update.md) | 晚更新 |
| [`OnDestroy`](on-destroy.md) | 销毁回调 |
| [`Destroy`](destroy.md) | 销毁对象 |

## 使用示例

```cpp
#include <XCEngine/Components/GameObject.h>
#include <XCEngine/Components/TransformComponent.h>
#include <XCEngine/Components/AudioSourceComponent.h>

using namespace XCEngine::Components;

void CreatePlayer() {
    GameObject* player = new GameObject("Player");
    
    auto transform = player->AddComponent<TransformComponent>();
    transform->SetPosition(Vector3(0, 0, 0));
    
    auto audio = player->AddComponent<AudioSourceComponent>();
    audio->SetVolume(0.8f);
    
    player->SetParent(cameraObject);
}

void FindAndOperate() {
    GameObject* enemy = GameObject::Find("Enemy");
    if (enemy) {
        enemy->SetActive(false);
    }
}
```

## 相关文档

- [Components 模块总览](../components.md) - Components 模块总览
- [Component](../component/component.md) - 组件基类
- [TransformComponent](../transform-component/transform-component.md) - 变换组件
- [Scene](../../scene/scene.md) - 场景