XCEngine/docs/api/components/transform-component/transform-component.md

# TransformComponent

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

**类型**: `class`

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

**描述**: 游戏对象变换组件，管理位置、旋转、缩放和层级关系。

## 概述

TransformComponent 是 XCEngine ECS 系统中的变换组件，每个 GameObject 都拥有一个 TransformComponent。它管理对象的局部空间（Local）和世界空间（World）位置、旋转（四元数）和缩放，支持父子层级变换、方向向量计算（前后左右上下）、矩阵运算和坐标变换。变换组件使用延迟更新机制，只有在需要时才重新计算世界变换矩阵。

## 枚举

| 枚举值 | 描述 |
|--------|------|
| `Space::Self` | 相对于自身空间 |
| `Space::World` | 相对于世界空间 |

## 公共方法

### 局部空间

| 方法 | 描述 |
|------|------|
| [`GetLocalPosition`](get-local-position.md) | 获取局部位置 |
| [`SetLocalPosition`](set-local-position.md) | 设置局部位置 |
| [`GetLocalRotation`](get-local-rotation.md) | 获取局部旋转 |
| [`SetLocalRotation`](set-local-rotation.md) | 设置局部旋转 |
| [`GetLocalScale`](get-local-scale.md) | 获取局部缩放 |
| [`SetLocalScale`](set-local-scale.md) | 设置局部缩放 |
| [`GetLocalEulerAngles`](get-local-euler-angles.md) | 获取局部欧拉角 |
| [`SetLocalEulerAngles`](set-local-euler-angles.md) | 设置局部欧拉角 |

### 世界空间

| 方法 | 描述 |
|------|------|
| [`GetPosition`](get-position.md) | 获取世界位置 |
| [`SetPosition`](set-position.md) | 设置世界位置 |
| [`GetRotation`](get-rotation.md) | 获取世界旋转 |
| [`SetRotation`](set-rotation.md) | 设置世界旋转 |
| [`GetScale`](get-scale.md) | 获取世界缩放 |
| [`SetScale`](set-scale.md) | 设置世界缩放 |

### 方向向量

| 方法 | 描述 |
|------|------|
| [`GetForward`](get-forward.md) | 获取前方方向 |
| [`GetRight`](get-right.md) | 获取右方方向 |
| [`GetUp`](get-up.md) | 获取上方方向 |

### 矩阵运算

| 方法 | 描述 |
|------|------|
| [`GetLocalToWorldMatrix`](get-local-to-world-matrix.md) | 获取局部到世界矩阵 |
| [`GetWorldToLocalMatrix`](get-world-to-local-matrix.md) | 获取世界到局部矩阵 |

### 层级结构

| 方法 | 描述 |
|------|------|
| [`GetParent`](get-parent.md) | 获取父变换 |
| [`SetParent`](set-parent.md) | 设置父变换 |
| [`GetChildCount`](get-child-count.md) | 获取子对象数量 |
| [`GetChild`](get-child.md) | 获取指定索引的子变换 |
| [`Find`](find.md) | 按名称查找子变换 |
| [`DetachChildren`](detach-children.md) | 分离所有子变换 |

### 同级顺序

| 方法 | 描述 |
|------|------|
| [`GetSiblingIndex`](get-sibling-index.md) | 获取同级索引 |
| [`SetSiblingIndex`](set-sibling-index.md) | 设置同级索引 |
| [`SetAsFirstSibling`](set-as-first-sibling.md) | 设为第一个同级 |
| [`SetAsLastSibling`](set-as-last-sibling.md) | 设为最后一个同级 |

### 变换操作

| 方法 | 描述 |
|------|------|
| [`LookAt`](look-at.md) | 指向目标 |
| [`Rotate`](rotate.md) | 旋转 |
| [`Translate`](translate.md) | 平移 |

### 坐标变换

| 方法 | 描述 |
|------|------|
| [`TransformPoint`](transform-point.md) | 变换点坐标 |
| [`InverseTransformPoint`](inverse-transform-point.md) | 逆变换点坐标 |
| [`TransformDirection`](transform-direction.md) | 变换方向向量 |
| [`InverseTransformDirection`](inverse-transform-direction.md) | 逆变换方向向量 |

## 使用示例

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

using namespace XCEngine::Components;

void TransformExample(TransformComponent* transform) {
    transform->SetPosition(Vector3(10, 0, 0));
    transform->SetRotation(Quaternion::FromEuler(0, 90, 0));
    
    Vector3 forward = transform->GetForward();
    Vector3 right = transform->GetRight();
    
    transform->Translate(Vector3(0, 0, 5), Space::Self);
    transform->Rotate(Vector3(0, 45, 0), Space::World);
    
    Vector3 worldPos = transform->GetPosition();
    Matrix4x4 l2w = transform->GetLocalToWorldMatrix();
}
```

## 相关文档

- [Components 模块总览](../components.md) - Components 模块总览
- [Component](../component/component.md) - 组件基类
- [GameObject](../game-object/game-object.md) - 游戏对象