69 lines
5.6 KiB
Markdown
69 lines
5.6 KiB
Markdown
# 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` 不走这条路径。
|
||
- 渲染组件链路当前是显式拆分的：`MeshFilterComponent` 负责 mesh 的运行时路径缓存、项目 `AssetRef` 与句柄绑定，`MeshRendererComponent` 负责材质槽的运行时路径缓存、项目 `AssetRef`、句柄以及渲染附加状态；对项目资产来说，正式持久化协议都优先是 `AssetRef`，而不是普通项目路径。
|
||
|
||
## 适用场景
|
||
|
||
- 构建编辑器可见的场景对象树。
|
||
- 以组合方式挂接渲染、音频或脚本行为。
|
||
- 让脚本层或工具层以 Unity 类似的心智模型操作对象。
|
||
- 做轻量级场景保存/加载和运行时对象遍历。
|
||
|
||
## 当前实现边界
|
||
|
||
- 静态查找接口 `GameObject::Find()`、`FindObjectsOfType()`、`FindGameObjectsWithTag()` 只会看到已注册到全局表的对象；普通 `GameObject` 直接构造后并不会自动注册。
|
||
- `FindGameObjectsWithTag()` 当前按对象名称比较，不是真正的 tag 系统。
|
||
- 某些组件已经具备基础运行时行为，但序列化覆盖并不完整，例如音频组件当前没有自定义 `Serialize()`/`Deserialize()`。
|
||
- `MeshFilterComponent` 在 deferred scene load 模式下会先按 `AssetRef` 恢复身份，并在可解析时补出路径缓存；真正的 mesh 句柄通常要到首次访问时才异步兑现，因此“组件存在”不等于“这一帧已经有可绘制网格”。
|
||
- `MeshRendererComponent` 也会先恢复槽位的 `AssetRef` 与必要的路径缓存；普通项目路径不会作为长期持久化协议单独存活，只有 virtual scheme 路径才会稳定保留在 `materialPaths` 中。
|
||
- 一些 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`，mesh 资源绑定、序列化路径和资产引用恢复。
|
||
- [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. 如果关注渲染资源绑定，再读 [MeshFilterComponent](MeshFilterComponent/MeshFilterComponent.md) 和 [MeshRendererComponent](MeshRendererComponent/MeshRendererComponent.md)，理解几何、材质和渲染提取之间的分工。
|
||
4. 最后按功能阅读其余组件页，例如 [CameraComponent](CameraComponent/CameraComponent.md)、[AudioSourceComponent](AudioSourceComponent/AudioSourceComponent.md)。
|
||
|
||
## 相关文档
|
||
|
||
- [上级目录](../XCEngine.md)
|
||
- [Scene](../Scene/Scene.md) - 场景对象的创建、更新和完整序列化入口。
|
||
- [API 总索引](../../main.md)
|