# Components

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

**类型**: `module`

**描述**: 提供 `GameObject`/`Component` 组合式对象模型，以及相机、灯光、网格渲染、音频等场景组件的 public API。

## 概览

`XCEngine::Components` 是当前引擎运行时对象模型的核心入口。它不是 ECS 风格的数据块系统，而是更接近 Unity 的 `GameObject + Component` 组织方式：

- `GameObject` 负责对象身份、父子层级、激活状态和生命周期分发。
- `TransformComponent` 是每个对象自带的内建组件，负责局部/世界变换与层级矩阵计算。
- 其他组件按职责挂接到 `GameObject` 上，例如相机、灯光、网格与音频。

这一设计的好处是上手门槛低，场景树、组件组合和序列化边界都比较直观，适合编辑器、脚本层和运行时调试共同使用。代价是对象关系、生命周期和序列化逻辑会集中在 `GameObject`/`Scene` 这条主线上，文档必须把这些边界讲清楚，否则很容易误用。

## 设计要点

- 当前实现以场景树为中心，而不是以查询驱动的 ECS 为中心。
- `TransformComponent` 不是普通可选组件，而是 `GameObject` 构造时就创建的内建组件。
- 生命周期由 `GameObject` 和 `Scene` 驱动，运行时直接 `AddComponent<T>()` 并不会自动补发 `Awake`、`Start` 或 `OnEnable`。
- 序列化职责分层：`GameObject::Serialize()` 只写对象基础字段和 `Transform`，完整场景保存由 `Scene::SerializeToString()` 负责组件和父子关系。
- `ComponentFactoryRegistry` 只负责把序列化文本里的组件类型名还原为内建组件实例，`Transform` 不走这条路径。

## 适用场景

- 构建编辑器可见的场景对象树。
- 以组合方式挂接渲染、音频或脚本行为。
- 让脚本层或工具层以 Unity 类似的心智模型操作对象。
- 做轻量级场景保存/加载和运行时对象遍历。

## 当前实现边界

- 静态查找接口 `GameObject::Find()`、`FindObjectsOfType()`、`FindGameObjectsWithTag()` 只会看到已注册到全局表的对象；普通 `GameObject` 直接构造后并不会自动注册。
- `FindGameObjectsWithTag()` 当前按对象名称比较，不是真正的 tag 系统。
- 某些组件已经具备基础运行时行为，但序列化覆盖并不完整，例如音频组件当前没有自定义 `Serialize()`/`Deserialize()`。
- 一些 API 名义上接近 Unity 对应物，但当前实现能力更轻量，不能直接按“完整 Unity 行为”等同理解。

## 头文件

- [AudioListenerComponent](AudioListenerComponent/AudioListenerComponent.md) - `AudioListenerComponent.h`，监听器状态与全局音频监听参数。
- [AudioSourceComponent](AudioSourceComponent/AudioSourceComponent.md) - `AudioSourceComponent.h`，音频源播放、解码与混音入口。
- [CameraComponent](CameraComponent/CameraComponent.md) - `CameraComponent.h`，相机投影与清屏参数。
- [Component](Component/Component.md) - `Component.h`，所有组件的抽象基类。
- [ComponentFactoryRegistry](ComponentFactoryRegistry/ComponentFactoryRegistry.md) - `ComponentFactoryRegistry.h`，场景反序列化时的组件工厂注册表。
- [GameObject](GameObject/GameObject.md) - `GameObject.h`，对象身份、层级和生命周期分发中心。
- [LightComponent](LightComponent/LightComponent.md) - `LightComponent.h`，基础灯光参数。
- [MeshFilterComponent](MeshFilterComponent/MeshFilterComponent.md) - `MeshFilterComponent.h`，网格资源引用。
- [MeshRendererComponent](MeshRendererComponent/MeshRendererComponent.md) - `MeshRendererComponent.h`，材质槽和渲染附加参数。
- [TransformComponent](TransformComponent/TransformComponent.md) - `TransformComponent.h`，局部/世界变换与层级矩阵。

## 推荐阅读顺序

1. 先读 [GameObject-Component Lifecycle And Serialization](../../_guides/Components/GameObject-Component-Lifecycle-And-Serialization.md)，建立整体心智模型。
2. 再读 [GameObject](GameObject/GameObject.md) 和 [TransformComponent](TransformComponent/TransformComponent.md)，理解对象树和变换树的关系。
3. 最后按功能阅读具体组件页，例如 [CameraComponent](CameraComponent/CameraComponent.md)、[MeshRendererComponent](MeshRendererComponent/MeshRendererComponent.md)、[AudioSourceComponent](AudioSourceComponent/AudioSourceComponent.md)。

## 相关文档

- [上级目录](../XCEngine.md)
- [Scene](../Scene/Scene.md) - 场景对象的创建、更新和完整序列化入口。
- [API 总索引](../../main.md)