docs: sync gameobject tag layer docs

This commit is contained in:
2026-04-03 15:48:09 +08:00
parent 24a200e126
commit d33520752b
18 changed files with 805 additions and 207 deletions

View File

@@ -13,7 +13,7 @@
可以把它粗略类比成 Unity 的对象体系:
- `Scene` 像场景容器,拥有对象并驱动更新与序列化。
- `GameObject` 像层级树节点,负责身份、父子关系、激活状态和组件容器。
- `GameObject` 像层级树节点,负责身份、轻量 `tag` / `layer`父子关系、激活状态和组件容器。
- `TransformComponent` 像内建 `Transform`,每个对象必有一个。
- 其他组件按职责挂接到对象上,例如 `CameraComponent``LightComponent``MeshRendererComponent``AudioSourceComponent`
@@ -160,7 +160,9 @@ auto* source = go->AddComponent<XCEngine::Components::AudioSourceComponent>();
只写对象基础状态:
- `name`
- `tag`
- `active`
- `layer`
- `id`
- `uuid`
- `transform`
@@ -207,9 +209,19 @@ component=Camera;projection=0;fov=60;...
## 你现在必须知道的限制
### 1. `FindGameObjectsWithTag()` 不是 tag 系统
### 1. `FindGameObjectsWithTag()` 现在是真实 tag 查询,但仍是轻量实现
当前实现按对象名称匹配,不是独立 tag 字段
当前实现已经有独立 `m_tag` 字段
- 默认是 `"Untagged"`
- `SetTag("")` 会回退到 `"Untagged"`
- `FindGameObjectsWithTag()` / `Scene::FindGameObjectWithTag()` 都通过 `CompareTag()` 查询
但它仍不是完整 TagManager
- 没有项目级 tag 定义表
- 没有索引或缓存
- 查询仍是线性扫描
### 2. `TransformComponent::Find()` 不是局部子树查找
@@ -253,7 +265,7 @@ component=Camera;projection=0;fov=60;...
- 它在对象模型上明显借鉴了 Unity。
- 它提供了足够熟悉的 `GameObject + Transform + Component` 心智模型。
- 但当前实现仍然比 Unity 轻得多,特别是在 tag、运行时加组件生命周期、完整组件序列化和层级顺序控制上。
- 但当前实现仍然比 Unity 轻得多,特别是在 tag/layer 管理、运行时加组件生命周期、完整组件序列化和层级顺序控制上。
把它理解成“Unity 风格、但当前版本能力更收敛的对象系统”是比较准确的。

View File

@@ -61,10 +61,12 @@
- 解析鲁棒性有限。
- 组件恢复依赖 `ComponentFactoryRegistry`,组件名或注册表变化都会影响加载结果。
当前这份文本格式已经覆盖 `GameObject``tag` / `layer` 字段;场景 round-trip 会把它们和层级、Transform、普通组件一起恢复。
## 当前最需要小心的几个事实
- 场景析构不会自动为所有对象走显式销毁流程,所以不要把 `~Scene()` 当成完整生命周期清理器。
- `FindGameObjectWithTag()` 现在其实是在按名字查
- `FindGameObjectWithTag()` 当前已经是按真实 tag 做深度优先查询,但它仍是线性扫描,不是带索引的完整 tag 系统
- `LoadSceneAsync()` 现在不是异步,更多只是一个名字上预留好的 API。
- `LoadScene()` 后的管理器 key 来自文件名,而不是场景内部保存的 `scene=` 名称。
@@ -75,7 +77,7 @@
- 需要 `OnDestroy` 或场景事件时,显式调用对象销毁入口,不要只依赖场景析构。
- 需要稳定查场景时,优先用 `CreateScene()` 的名称或加载文件的文件名 stem不要假设一定等于场景内部名字。
- 不要把 `LoadSceneAsync()` 当成真正的后台加载接口。
- 不要`FindGameObjectWithTag()` 当成完整 tag 系统
- 可以`FindGameObjectWithTag()` 当成真实 tag 查询,但不要把它当成带项目配置和索引优化的完整 TagManager
## 相关 API