5.6 KiB
5.6 KiB
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.h，监听器状态与全局音频监听参数。 - AudioSourceComponent -
AudioSourceComponent.h，音频源播放、解码与混音入口。 - CameraComponent -
CameraComponent.h，相机投影与清屏参数。 - Component -
Component.h，所有组件的抽象基类。 - ComponentFactoryRegistry -
ComponentFactoryRegistry.h，场景反序列化时的组件工厂注册表。 - GameObject -
GameObject.h，对象身份、层级和生命周期分发中心。 - LightComponent -
LightComponent.h，基础灯光参数。 - MeshFilterComponent -
MeshFilterComponent.h，mesh 资源绑定、序列化路径和资产引用恢复。 - MeshRendererComponent -
MeshRendererComponent.h，材质槽和渲染附加参数。 - TransformComponent -
TransformComponent.h，局部/世界变换与层级矩阵。
推荐阅读顺序
- 先读 GameObject-Component Lifecycle And Serialization，建立整体心智模型。
- 再读 GameObject 和 TransformComponent，理解对象树和变换树的关系。
- 如果关注渲染资源绑定，再读 MeshFilterComponent 和 MeshRendererComponent，理解几何、材质和渲染提取之间的分工。
- 最后按功能阅读其余组件页，例如 CameraComponent、AudioSourceComponent。