# GameObject

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

**类型**: `class`

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

**描述**: 当前对象树模型的核心节点，负责身份、层级、激活状态、轻量 `tag/layer` 元数据、组件容器与生命周期分发。

## 设计定位

`GameObject` 是当前引擎对象模型的中心类型。它的设计明显借鉴了 Unity 的 `GameObject + Transform + Component` 体系，但刻意保持为更轻的实现：

- 用对象树而不是 ECS 组织运行时对象，便于编辑器层级、脚本调用和场景保存。
- 把 `Transform` 作为基础设施内建到每个对象里，避免“对象没有空间变换”的特例分支。
- 提供熟悉的 `tag` / `layer` 心智模型，但暂时不引入完整的项目级 TagManager、LayerMask 配置器或查询索引。

这种设计的好处是学习成本低、编辑器友好、序列化边界清晰；代价则是很多查询仍是线性扫描，生命周期也更依赖 `Scene -> GameObject -> Component` 的调用链。

## 当前真实数据模型

`GameObject` 当前同时持有以下几类状态：

- 身份字段：`m_id`、`m_uuid`、`m_name`
- 元数据字段：`m_tag`、`m_layer`
- 层级字段：`m_parent`、`m_children`
- 激活字段：`m_activeSelf`、`m_started`
- 所有权字段：`m_scene`、`m_transform`、`m_components`

其中最容易和旧文档混淆的是 `tag` / `layer`：它们现在已经是独立字段，不再是名字别名或“预留接口”。

## Tag 与 Layer 语义

### Tag

- 底层字段是 `m_tag`
- 默认值是 `"Untagged"`
- [SetTag](SetTag.md) 传入空字符串时也会规范化回 `"Untagged"`
- [CompareTag](CompareTag.md) 直接比较 `m_tag == tag`

因此当前引擎里：

- `tag` 不是 `name` 的别名
- `CompareTag("Player")` 比较的是真实 tag 字段
- [FindGameObjectsWithTag](FindGameObjectsWithTag.md) 和 [Scene::FindGameObjectWithTag](../../Scene/Scene/FindGameObjectWithTag.md) 都是真正按 tag 查询

### Layer

- 底层字段是 `m_layer`
- 默认值是 `0`
- 原生 [SetLayer](SetLayer.md) 会把上界限制到 `31`
- 托管 `GameObject.layer` / `Component.layer` 先把 `int` 显式限制到 `[0, 31]`，再回落到 native setter

这意味着在“引擎正常产生的数据路径”里，layer 会稳定落在 `0..31`。文档里常说的“clamp 到 `[0, 31]`”，对托管调用链是精确描述；对原生 C++ API 来说，更精确的说法是“参数本身是 `uint8_t`，setter 再额外做上界限制”。

## 为什么 Tag / Layer 做成轻量字段

当前实现没有引入完整 TagManager 的原因并不是“尚未支持 tag”，而是有意把它们先收敛为轻量对象元数据：

- 对编辑器和脚本层来说，独立字段已经足够支撑常见对象分类与查询。
- 对场景序列化来说，独立字段更容易稳定 round-trip。
- 对运行时复杂度来说，不必提前引入项目级表、重命名迁移、索引维护和配置资产。

因此它更接近“商业引擎里可持续扩展的第一阶段实现”，而不是临时占位符。

## 内建 Transform 与组件模型

`GameObject` 构造时会立即创建一个 `TransformComponent` 并绑定到 `m_transform`。这带来三个明确语义：

- 每个对象天然拥有 `Transform`
- `AddComponent<TransformComponent>()` 返回已有实例，而不是再造一个
- `RemoveComponent()` 不允许移除 `Transform`

普通组件则保存在 `m_components` 里，所有权由 `std::unique_ptr<Component>` 持有。也正因为 `Transform` 不在 `m_components` 中，很多生命周期与序列化逻辑都只覆盖“普通组件”，不会自动覆盖内建 `Transform`。

## 创建路径与对象注册

### 直接构造

`GameObject go;` 或 `GameObject go("Name");` 会得到一个可用对象，但它：

- 拥有内建 `Transform`
- `m_scene == nullptr`
- 不会自动注册到全局 registry
- 不会自动触发 `Awake()`

这条路径适合测试、临时对象或完全手工控制生命周期的代码。

### 由 `Scene::CreateGameObject()` 创建

这是当前推荐的运行时路径。`Scene` 会额外完成：

- 接管对象所有权
- 把对象放入 `GameObject::GetGlobalRegistry()`
- 设置所属 `Scene`
- 接入根节点或父子层级
- 创建后立即调用 `Awake()`

### 由 `Scene::DeserializeFromString()` 恢复

反序列化也会重建对象并注册到场景和全局 registry，但它不会经过 `CreateGameObject()`，因此不会自动触发创建事件，也不会补发 `Awake()` / `Start()`。

## 生命周期语义

`GameObject` 自己不是组件，但它是普通组件生命周期的分发者。

- [Awake](Awake.md) 遍历普通组件并调用 `Awake()`
- [Start](Start.md) 只在 `active in hierarchy` 时执行，且每个对象最多执行一次
- [Update](Update.md)、[FixedUpdate](FixedUpdate.md)、[LateUpdate](LateUpdate.md) 只对激活层级中的已启用组件递归分发
- [OnDestroy](OnDestroy.md) 会把销毁消息发给普通组件

需要特别注意两条现实边界：

- `TransformComponent` 不参与普通组件生命周期遍历
- 运行时 `AddComponent<T>()` 只负责挂接，不会自动补发 `Awake()`、`Start()` 或 `OnEnable()`

所以如果对象已经进入过 `Start()`，你之后再动态添加组件，新组件不会被引擎自动“追上进度”。

## 激活状态与层级传播

`GameObject` 维护两套不同层面的激活状态：

- [IsActive](IsActive.md) 对应 `m_activeSelf`
- [IsActiveInHierarchy](IsActiveInHierarchy.md) 要求对象自己激活，且所有父节点也激活

[SetActive](SetActive.md) 与 [SetParent](SetParent.md) 都会重新计算“层级有效激活态”。一旦有效激活态发生变化，当前实现会：

- 对已启用的普通组件发送 `OnEnable()` 或 `OnDisable()`
- 把变化递归传播给子对象

这和商业引擎里把“对象自己是否开启”和“它是否真的在运行层级里生效”拆开的做法一致。

## 查找语义与全局 Registry

静态查找接口：

- [Find](Find.md) 按对象名遍历全局 registry
- [FindObjectsOfType](FindObjectsOfType.md) 返回当前 registry 全部对象
- [FindGameObjectsWithTag](FindGameObjectsWithTag.md) 通过 `CompareTag()` 过滤 registry

当前 registry 主要由两条路径填充：

- `Scene::CreateGameObject()`
- `Scene::DeserializeFromString()`

因此未加入场景的独立对象默认不会出现在这些查询结果中。另一方面，场景级 [Scene::FindGameObjectWithTag](../../Scene/Scene/FindGameObjectWithTag.md) 则是沿场景根对象做深度优先遍历，更适合表达“当前场景树里的第一个匹配对象”。

## 所有权与销毁

- 场景托管对象由 `Scene` 以 `std::unique_ptr<GameObject>` 持有
- 普通组件由 `GameObject` 以 `std::unique_ptr<Component>` 持有
- `TransformComponent` 由 `m_transform` 单独持有并在析构时删除

[Destroy](Destroy.md) 当前有两种路径：

- 如果对象属于某个场景，则委托给 `Scene::DestroyGameObject(this)`
- 如果对象不属于场景，只调用 `OnDestroy()`，不会释放对象自身内存

因此“独立对象调用 `Destroy()`”不等于“对象被 delete”。真正释放内存的仍然是拥有它的那一层所有者。

## 序列化边界

[Serialize](Serialize.md) 只负责单对象基础状态：

- `name`
- `tag`
- `active`
- `layer`
- `id`
- `uuid`
- `transform`

它不会保存：

- 普通组件列表
- 父子层级
- 所属场景

完整对象树持久化由 [Scene::SerializeToString](../../Scene/Scene/SerializeToString.md) 负责；对应地，[Deserialize](Deserialize.md) 也只恢复单对象基础字段，不会重建组件、父子关系或 `Scene` 归属。

## 托管脚本桥接

Mono 运行时当前已经把这些元数据直接暴露给 C#：

- `GameObject.Tag` / `GameObject.tag`
- `GameObject.Layer` / `GameObject.layer`
- `Component.Tag` / `Component.tag`
- `Component.Layer` / `Component.layer`
- `CompareTag(...)`

这些接口不是副本，而是直接读写同一份原生字段。`tests/scripting/test_mono_script_runtime.cpp` 中的 `GameObjectTagAndLayerApiExposeUnityStylePropertiesAndCompareTag` 明确验证了：

- 托管脚本能读到原生已有的 tag / layer
- 托管脚本写回 `"Player"` 和 `31` 后，原生对象会立即更新
- 场景级 `FindGameObjectWithTag("Player")` 会立刻看到更新结果

## 当前实现限制

- tag / layer 仍是轻量字段，没有项目级定义表、mask 工具或索引查询
- 全局静态查找只对已注册对象成立
- 运行时新增组件不会自动补发初始化生命周期
- `Destroy()` 对独立对象不会释放自身内存
- `Transform` 不参与普通组件生命周期遍历
- `Scene::DeserializeFromString()` 恢复出的对象不会自动补发 `Awake()`

## 推荐使用方式

1. 运行时对象优先通过 `Scene::CreateGameObject()` 创建。
2. 需要对象分类时使用真实的 [SetTag](SetTag.md) / [CompareTag](CompareTag.md)，不要再把 tag 当作名字别名。
3. 需要层过滤或脚本暴露时使用 [SetLayer](SetLayer.md)，并按 `0..31` 的轻量层模型组织约定。
4. 需要完整持久化对象树时使用 [Scene::SerializeToString](../../Scene/Scene/SerializeToString.md) / [Scene::DeserializeFromString](../../Scene/Scene/DeserializeFromString.md)。
5. 运行时动态挂组件时，不要假设引擎会自动补发 `Awake()` / `Start()`。

## 相关方法

- [Constructor](Constructor.md)
- [GetName](GetName.md)
- [SetName](SetName.md)
- [GetTag](GetTag.md)
- [SetTag](SetTag.md)
- [CompareTag](CompareTag.md)
- [GetLayer](GetLayer.md)
- [SetLayer](SetLayer.md)
- [AddComponent](AddComponent.md)
- [GetComponent](GetComponent.md)
- [GetComponents](GetComponents.md)
- [GetComponentInChildren](GetComponentInChildren.md)
- [GetComponentInParent](GetComponentInParent.md)
- [GetComponentsInChildren](GetComponentsInChildren.md)
- [GetTransform](GetTransform.md)
- [SetParent](SetParent.md)
- [DetachFromParent](DetachFromParent.md)
- [DetachChildren](DetachChildren.md)
- [SetActive](SetActive.md)
- [IsActive](IsActive.md)
- [IsActiveInHierarchy](IsActiveInHierarchy.md)
- [Find](Find.md)
- [FindObjectsOfType](FindObjectsOfType.md)
- [FindGameObjectsWithTag](FindGameObjectsWithTag.md)
- [Destroy](Destroy.md)
- [Serialize](Serialize.md)
- [Deserialize](Deserialize.md)

## 相关指南

- [GameObject-Component Lifecycle And Serialization](../../../_guides/Components/GameObject-Component-Lifecycle-And-Serialization.md)

## 相关文档

- [当前模块](../Components.md)
- [Component](../Component/Component.md)
- [TransformComponent](../TransformComponent/TransformComponent.md)
- [Scene](../../Scene/Scene/Scene.md)