From a9d5a68dd6c429f4dcd426d1c25d42182b9df1e5 Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Sun, 22 Mar 2026 03:33:55 +0800 Subject: [PATCH] docs: Add Component, GameObject, TransformComponent and Scene API documentation - Add Component class documentation with lifecycle methods - Add GameObject class documentation with component system - Add TransformComponent documentation with transform methods - Add Scene class documentation with GameObject management - Add SceneManager singleton documentation with scene loading - Update components.md overview with all component classes - Update main.md navigation with Scene module --- docs/api/components/component/component.md | 67 ++++++++++ .../components/component/get-game-object.md | 13 ++ docs/api/components/component/get-name.md | 13 ++ docs/api/components/component/get-scene.md | 14 ++ docs/api/components/component/is-enabled.md | 14 ++ docs/api/components/component/set-enabled.md | 17 +++ docs/api/components/component/transform.md | 16 +++ docs/api/components/components.md | 19 ++- .../components/game-object/add-component.md | 23 ++++ docs/api/components/game-object/awake.md | 14 ++ docs/api/components/game-object/destroy.md | 14 ++ .../components/game-object/detach-children.md | 14 ++ .../components/game-object/fixed-update.md | 14 ++ .../api/components/game-object/game-object.md | 118 ++++++++++++++++ .../components/game-object/get-child-count.md | 14 ++ docs/api/components/game-object/get-child.md | 17 +++ .../components/game-object/get-children.md | 14 ++ .../game-object/get-component-in-children.md | 20 +++ .../game-object/get-component-in-parent.md | 20 +++ .../components/game-object/get-component.md | 23 ++++ .../game-object/get-components-in-children.md | 20 +++ .../components/game-object/get-components.md | 21 +++ docs/api/components/game-object/get-id.md | 13 ++ docs/api/components/game-object/get-name.md | 14 ++ docs/api/components/game-object/get-parent.md | 14 ++ docs/api/components/game-object/get-scene.md | 14 ++ .../components/game-object/get-transform.md | 15 +++ .../game-object/is-active-in-hierarchy.md | 16 +++ docs/api/components/game-object/is-active.md | 15 +++ .../api/components/game-object/late-update.md | 17 +++ docs/api/components/game-object/on-destroy.md | 14 ++ docs/api/components/game-object/set-active.md | 15 +++ docs/api/components/game-object/set-name.md | 15 +++ docs/api/components/game-object/set-parent.md | 19 +++ docs/api/components/game-object/start.md | 15 +++ docs/api/components/game-object/update.md | 15 +++ .../transform-component/detach-children.md | 26 ++++ .../components/transform-component/find.md | 33 +++++ .../transform-component/get-child-count.md | 27 ++++ .../transform-component/get-child.md | 32 +++++ .../transform-component/get-forward.md | 31 +++++ .../get-local-euler-angles.md | 31 +++++ .../transform-component/get-local-position.md | 33 +++++ .../transform-component/get-local-rotation.md | 33 +++++ .../transform-component/get-local-scale.md | 31 +++++ .../get-local-to-world-matrix.md | 29 ++++ .../transform-component/get-parent.md | 32 +++++ .../transform-component/get-position.md | 33 +++++ .../transform-component/get-right.md | 30 +++++ .../transform-component/get-rotation.md | 31 +++++ .../transform-component/get-scale.md | 31 +++++ .../transform-component/get-sibling-index.md | 28 ++++ .../components/transform-component/get-up.md | 30 +++++ .../get-world-to-local-matrix.md | 29 ++++ .../inverse-transform-direction.md | 35 +++++ .../inverse-transform-point.md | 35 +++++ .../components/transform-component/look-at.md | 28 ++++ .../components/transform-component/rotate.md | 29 ++++ .../set-as-first-sibling.md | 22 +++ .../set-as-last-sibling.md | 22 +++ .../set-local-euler-angles.md | 30 +++++ .../transform-component/set-local-position.md | 31 +++++ .../transform-component/set-local-rotation.md | 32 +++++ .../transform-component/set-local-scale.md | 30 +++++ .../transform-component/set-parent.md | 31 +++++ .../transform-component/set-position.md | 31 +++++ .../transform-component/set-rotation.md | 32 +++++ .../transform-component/set-scale.md | 31 +++++ .../transform-component/set-sibling-index.md | 27 ++++ .../transform-component.md | 126 ++++++++++++++++++ .../transform-direction.md | 35 +++++ .../transform-component/transform-point.md | 35 +++++ .../transform-component/translate.md | 26 ++++ docs/api/main.md | 6 +- docs/api/scene/scene-manager/create-scene.md | 31 +++++ .../scene/scene-manager/get-active-scene.md | 29 ++++ .../api/scene/scene-manager/get-all-scenes.md | 28 ++++ docs/api/scene/scene-manager/get-scene.md | 33 +++++ docs/api/scene/scene-manager/get.md | 25 ++++ .../scene/scene-manager/load-scene-async.md | 34 +++++ docs/api/scene/scene-manager/load-scene.md | 31 +++++ .../scene-manager/on-active-scene-changed.md | 33 +++++ .../scene/scene-manager/on-scene-loaded.md | 33 +++++ .../scene/scene-manager/on-scene-unloaded.md | 33 +++++ docs/api/scene/scene-manager/scene-manager.md | 74 ++++++++++ .../scene/scene-manager/set-active-scene.md | 32 +++++ docs/api/scene/scene-manager/unload-scene.md | 33 +++++ docs/api/scene/scene.md | 46 +++++++ docs/api/scene/scene/create-game-object.md | 35 +++++ docs/api/scene/scene/destroy-game-object.md | 29 ++++ .../scene/scene/find-game-object-with-tag.md | 36 +++++ docs/api/scene/scene/find.md | 36 +++++ docs/api/scene/scene/fixed-update.md | 30 +++++ docs/api/scene/scene/get-name.md | 26 ++++ docs/api/scene/scene/get-root-game-objects.md | 27 ++++ docs/api/scene/scene/is-active.md | 27 ++++ docs/api/scene/scene/late-update.md | 30 +++++ docs/api/scene/scene/load.md | 29 ++++ .../api/scene/scene/on-game-object-created.md | 31 +++++ .../scene/scene/on-game-object-destroyed.md | 31 +++++ docs/api/scene/scene/save.md | 29 ++++ docs/api/scene/scene/scene.md | 90 +++++++++++++ docs/api/scene/scene/set-active.md | 25 ++++ docs/api/scene/scene/set-name.md | 25 ++++ docs/api/scene/scene/update.md | 25 ++++ 105 files changed, 3003 insertions(+), 7 deletions(-) create mode 100644 docs/api/components/component/component.md create mode 100644 docs/api/components/component/get-game-object.md create mode 100644 docs/api/components/component/get-name.md create mode 100644 docs/api/components/component/get-scene.md create mode 100644 docs/api/components/component/is-enabled.md create mode 100644 docs/api/components/component/set-enabled.md create mode 100644 docs/api/components/component/transform.md create mode 100644 docs/api/components/game-object/add-component.md create mode 100644 docs/api/components/game-object/awake.md create mode 100644 docs/api/components/game-object/destroy.md create mode 100644 docs/api/components/game-object/detach-children.md create mode 100644 docs/api/components/game-object/fixed-update.md create mode 100644 docs/api/components/game-object/game-object.md create mode 100644 docs/api/components/game-object/get-child-count.md create mode 100644 docs/api/components/game-object/get-child.md create mode 100644 docs/api/components/game-object/get-children.md create mode 100644 docs/api/components/game-object/get-component-in-children.md create mode 100644 docs/api/components/game-object/get-component-in-parent.md create mode 100644 docs/api/components/game-object/get-component.md create mode 100644 docs/api/components/game-object/get-components-in-children.md create mode 100644 docs/api/components/game-object/get-components.md create mode 100644 docs/api/components/game-object/get-id.md create mode 100644 docs/api/components/game-object/get-name.md create mode 100644 docs/api/components/game-object/get-parent.md create mode 100644 docs/api/components/game-object/get-scene.md create mode 100644 docs/api/components/game-object/get-transform.md create mode 100644 docs/api/components/game-object/is-active-in-hierarchy.md create mode 100644 docs/api/components/game-object/is-active.md create mode 100644 docs/api/components/game-object/late-update.md create mode 100644 docs/api/components/game-object/on-destroy.md create mode 100644 docs/api/components/game-object/set-active.md create mode 100644 docs/api/components/game-object/set-name.md create mode 100644 docs/api/components/game-object/set-parent.md create mode 100644 docs/api/components/game-object/start.md create mode 100644 docs/api/components/game-object/update.md create mode 100644 docs/api/components/transform-component/detach-children.md create mode 100644 docs/api/components/transform-component/find.md create mode 100644 docs/api/components/transform-component/get-child-count.md create mode 100644 docs/api/components/transform-component/get-child.md create mode 100644 docs/api/components/transform-component/get-forward.md create mode 100644 docs/api/components/transform-component/get-local-euler-angles.md create mode 100644 docs/api/components/transform-component/get-local-position.md create mode 100644 docs/api/components/transform-component/get-local-rotation.md create mode 100644 docs/api/components/transform-component/get-local-scale.md create mode 100644 docs/api/components/transform-component/get-local-to-world-matrix.md create mode 100644 docs/api/components/transform-component/get-parent.md create mode 100644 docs/api/components/transform-component/get-position.md create mode 100644 docs/api/components/transform-component/get-right.md create mode 100644 docs/api/components/transform-component/get-rotation.md create mode 100644 docs/api/components/transform-component/get-scale.md create mode 100644 docs/api/components/transform-component/get-sibling-index.md create mode 100644 docs/api/components/transform-component/get-up.md create mode 100644 docs/api/components/transform-component/get-world-to-local-matrix.md create mode 100644 docs/api/components/transform-component/inverse-transform-direction.md create mode 100644 docs/api/components/transform-component/inverse-transform-point.md create mode 100644 docs/api/components/transform-component/look-at.md create mode 100644 docs/api/components/transform-component/rotate.md create mode 100644 docs/api/components/transform-component/set-as-first-sibling.md create mode 100644 docs/api/components/transform-component/set-as-last-sibling.md create mode 100644 docs/api/components/transform-component/set-local-euler-angles.md create mode 100644 docs/api/components/transform-component/set-local-position.md create mode 100644 docs/api/components/transform-component/set-local-rotation.md create mode 100644 docs/api/components/transform-component/set-local-scale.md create mode 100644 docs/api/components/transform-component/set-parent.md create mode 100644 docs/api/components/transform-component/set-position.md create mode 100644 docs/api/components/transform-component/set-rotation.md create mode 100644 docs/api/components/transform-component/set-scale.md create mode 100644 docs/api/components/transform-component/set-sibling-index.md create mode 100644 docs/api/components/transform-component/transform-component.md create mode 100644 docs/api/components/transform-component/transform-direction.md create mode 100644 docs/api/components/transform-component/transform-point.md create mode 100644 docs/api/components/transform-component/translate.md create mode 100644 docs/api/scene/scene-manager/create-scene.md create mode 100644 docs/api/scene/scene-manager/get-active-scene.md create mode 100644 docs/api/scene/scene-manager/get-all-scenes.md create mode 100644 docs/api/scene/scene-manager/get-scene.md create mode 100644 docs/api/scene/scene-manager/get.md create mode 100644 docs/api/scene/scene-manager/load-scene-async.md create mode 100644 docs/api/scene/scene-manager/load-scene.md create mode 100644 docs/api/scene/scene-manager/on-active-scene-changed.md create mode 100644 docs/api/scene/scene-manager/on-scene-loaded.md create mode 100644 docs/api/scene/scene-manager/on-scene-unloaded.md create mode 100644 docs/api/scene/scene-manager/scene-manager.md create mode 100644 docs/api/scene/scene-manager/set-active-scene.md create mode 100644 docs/api/scene/scene-manager/unload-scene.md create mode 100644 docs/api/scene/scene.md create mode 100644 docs/api/scene/scene/create-game-object.md create mode 100644 docs/api/scene/scene/destroy-game-object.md create mode 100644 docs/api/scene/scene/find-game-object-with-tag.md create mode 100644 docs/api/scene/scene/find.md create mode 100644 docs/api/scene/scene/fixed-update.md create mode 100644 docs/api/scene/scene/get-name.md create mode 100644 docs/api/scene/scene/get-root-game-objects.md create mode 100644 docs/api/scene/scene/is-active.md create mode 100644 docs/api/scene/scene/late-update.md create mode 100644 docs/api/scene/scene/load.md create mode 100644 docs/api/scene/scene/on-game-object-created.md create mode 100644 docs/api/scene/scene/on-game-object-destroyed.md create mode 100644 docs/api/scene/scene/save.md create mode 100644 docs/api/scene/scene/scene.md create mode 100644 docs/api/scene/scene/set-active.md create mode 100644 docs/api/scene/scene/set-name.md create mode 100644 docs/api/scene/scene/update.md diff --git a/docs/api/components/component/component.md b/docs/api/components/component/component.md new file mode 100644 index 00000000..8ea4175c --- /dev/null +++ b/docs/api/components/component/component.md @@ -0,0 +1,67 @@ +# Component + +**命名空间**: `XCEngine::Components` + +**类型**: `class (abstract)` + +**头文件**: `XCEngine/Components/Component.h` + +**描述**: ECS 组件基类，定义所有组件的公共接口和生命周期。 + +## 概述 + +Component 是 XCEngine ECS 架构中的组件基类，所有具体组件（如 TransformComponent、AudioSourceComponent）都继承自此类。它定义了组件的通用生命周期方法（Awake、Start、Update、OnEnable、OnDisable、OnDestroy）以及获取所属 GameObject 和场景的接口。组件通过友元类 GameObject 自动管理其所属游戏对象。 + +## 公共方法 + +| 方法 | 描述 | +|------|------| +| [`GetName`](get-name.md) | 获取组件名称（纯虚函数） | +| [`GetGameObject`](get-game-object.md) | 获取所属 GameObject | +| [`transform`](transform.md) | 获取变换组件引用 | +| [`GetScene`](get-scene.md) | 获取所属场景 | +| [`IsEnabled`](is-enabled.md) | 检查组件是否启用 | +| [`SetEnabled`](set-enabled.md) | 设置组件启用状态 | + +## 虚方法（生命周期） + +| 方法 | 描述 | +|------|------| +| `virtual void Awake()` | 组件创建后首次启用时调用 | +| `virtual void Start()` | 在首次更新前调用 | +| `virtual void Update(float deltaTime)` | 每帧更新 | +| `virtual void FixedUpdate()` | 固定频率更新（物理） | +| `virtual void LateUpdate(float deltaTime)` | 晚于 Update 更新 | +| `virtual void OnEnable()` | 启用时调用 | +| `virtual void OnDisable()` | 禁用时调用 | +| `virtual void OnDestroy()` | 销毁时调用 | + +## 使用示例 + +```cpp +#include +#include + +using namespace XCEngine::Components; + +class MyComponent : public Component { +public: + void Awake() override { + printf("Awake: %s\n", GetName().c_str()); + } + + void Update(float deltaTime) override { + // 每帧逻辑 + } + + std::string GetName() const override { + return "MyComponent"; + } +}; +``` + +## 相关文档 + +- [Components 模块总览](../components.md) - Components 模块总览 +- [GameObject](game-object/game-object.md) - 游戏对象 +- [TransformComponent](transform-component/transform-component.md) - 变换组件 diff --git a/docs/api/components/component/get-game-object.md b/docs/api/components/component/get-game-object.md new file mode 100644 index 00000000..e1b76829 --- /dev/null +++ b/docs/api/components/component/get-game-object.md @@ -0,0 +1,13 @@ +# Component::GetGameObject + +获取所属的 GameObject。 + +```cpp +GameObject* GetGameObject() const; +``` + +**返回：** `GameObject*` - 所属游戏对象指针，如果组件未附加到游戏对象则返回 nullptr + +## 相关文档 + +- [Component 总览](component.md) diff --git a/docs/api/components/component/get-name.md b/docs/api/components/component/get-name.md new file mode 100644 index 00000000..cc57f0d0 --- /dev/null +++ b/docs/api/components/component/get-name.md @@ -0,0 +1,13 @@ +# Component::GetName + +获取组件名称。 + +```cpp +virtual std::string GetName() const = 0; +``` + +**返回：** `std::string` - 组件名称 + +## 相关文档 + +- [Component 总览](component.md) diff --git a/docs/api/components/component/get-scene.md b/docs/api/components/component/get-scene.md new file mode 100644 index 00000000..2ea02c23 --- /dev/null +++ b/docs/api/components/component/get-scene.md @@ -0,0 +1,14 @@ +# Component::GetScene + +获取所属的场景。 + +```cpp +Scene* GetScene() const; +``` + +**返回：** `Scene*` - 所属场景指针，如果组件未附加到游戏对象则返回 nullptr + +## 相关文档 + +- [Component 总览](component.md) +- [Scene](../scene/scene/scene.md) diff --git a/docs/api/components/component/is-enabled.md b/docs/api/components/component/is-enabled.md new file mode 100644 index 00000000..bdc8c1d1 --- /dev/null +++ b/docs/api/components/component/is-enabled.md @@ -0,0 +1,14 @@ +# Component::IsEnabled + +检查组件是否启用。 + +```cpp +bool IsEnabled() const; +``` + +**返回：** `bool` - 如果组件启用则返回 true + +## 相关文档 + +- [Component 总览](component.md) +- [SetEnabled](set-enabled.md) diff --git a/docs/api/components/component/set-enabled.md b/docs/api/components/component/set-enabled.md new file mode 100644 index 00000000..418b04be --- /dev/null +++ b/docs/api/components/component/set-enabled.md @@ -0,0 +1,17 @@ +# Component::SetEnabled + +设置组件启用状态。 + +```cpp +void SetEnabled(bool enabled); +``` + +当启用状态发生变化时，会自动调用 OnEnable 或 OnDisable 回调。 + +**参数：** +- `enabled` - true 为启用，false 为禁用 + +## 相关文档 + +- [Component 总览](component.md) +- [IsEnabled](is-enabled.md) diff --git a/docs/api/components/component/transform.md b/docs/api/components/component/transform.md new file mode 100644 index 00000000..cf7e7664 --- /dev/null +++ b/docs/api/components/component/transform.md @@ -0,0 +1,16 @@ +# Component::transform + +获取变换组件引用。 + +```cpp +TransformComponent& transform() const; +``` + +**返回：** `TransformComponent&` - 所属 GameObject 的变换组件引用 + +**注意：** 如果组件未附加到 GameObject 或 GameObject 没有 TransformComponent，可能导致未定义行为。 + +## 相关文档 + +- [Component 总览](component.md) +- [TransformComponent](transform-component/transform-component.md) diff --git a/docs/api/components/components.md b/docs/api/components/components.md index c361599a..ee3d0175 100644 --- a/docs/api/components/components.md +++ b/docs/api/components/components.md @@ -12,6 +12,19 @@ Components 模块是 XCEngine ECS 架构中的组件层，提供各种游戏对 ## 模块内容 +### 核心组件 + +| 组件 | 文件 | 描述 | +|------|------|------| +| [Component](component/component.md) | `Component.h` | 组件基类，所有组件的父类 | +| [GameObject](game-object/game-object.md) | `GameObject.h` | 游戏对象实体 | + +### 变换组件 + +| 组件 | 文件 | 描述 | +|------|------|------| +| [TransformComponent](transform-component/transform-component.md) | `TransformComponent.h` | 变换组件，包含位置、旋转、缩放 | + ### 音频组件 | 组件 | 文件 | 描述 | @@ -19,12 +32,6 @@ Components 模块是 XCEngine ECS 架构中的组件层，提供各种游戏对 | [AudioSourceComponent](audio-source/audio-source-component.md) | `AudioSourceComponent.h` | 音频源组件，负责播放音频 | | [AudioListenerComponent](audio-listener/audio-listener-component.md) | `AudioListenerComponent.h` | 音频监听器组件，接收声音 | -### 变换组件 - -| 组件 | 文件 | 描述 | -|------|------|------| -| TransformComponent | `TransformComponent.h` | 变换组件，包含位置、旋转、缩放 | - ## 使用示例 ```cpp diff --git a/docs/api/components/game-object/add-component.md b/docs/api/components/game-object/add-component.md new file mode 100644 index 00000000..23af5776 --- /dev/null +++ b/docs/api/components/game-object/add-component.md @@ -0,0 +1,23 @@ +# GameObject::AddComponent + +向游戏对象添加组件。 + +```cpp +template +T* AddComponent(Args&&... args); +``` + +模板参数 T 必须继承自 Component。组件被添加后，其 m_gameObject 成员会自动设置为该 GameObject。 + +**模板参数：** +- `T` - 组件类型 + +**参数：** +- `args` - 传递给组件构造函数的参数 + +**返回：** `T*` - 创建的组件指针 + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [Component](component/component.md) diff --git a/docs/api/components/game-object/awake.md b/docs/api/components/game-object/awake.md new file mode 100644 index 00000000..387fcb22 --- /dev/null +++ b/docs/api/components/game-object/awake.md @@ -0,0 +1,14 @@ +# GameObject::Awake + +唤醒游戏对象及其所有组件。 + +```cpp +void Awake(); +``` + +在对象创建后首次添加到活动场景时调用，用于初始化组件状态。 + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [Start](start.md) diff --git a/docs/api/components/game-object/destroy.md b/docs/api/components/game-object/destroy.md new file mode 100644 index 00000000..8adacf2e --- /dev/null +++ b/docs/api/components/game-object/destroy.md @@ -0,0 +1,14 @@ +# GameObject::Destroy + +销毁游戏对象。 + +```cpp +void Destroy(); +``` + +将对象标记为待销毁，在当前帧结束时实际销毁。 + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [OnDestroy](on-destroy.md) diff --git a/docs/api/components/game-object/detach-children.md b/docs/api/components/game-object/detach-children.md new file mode 100644 index 00000000..0ab4a04a --- /dev/null +++ b/docs/api/components/game-object/detach-children.md @@ -0,0 +1,14 @@ +# GameObject::DetachChildren + +分离所有子对象。 + +```cpp +void DetachChildren(); +``` + +将所有子对象从当前 GameObject 分离，使它们成为根对象。 + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [SetParent](set-parent.md) diff --git a/docs/api/components/game-object/fixed-update.md b/docs/api/components/game-object/fixed-update.md new file mode 100644 index 00000000..db0a69e0 --- /dev/null +++ b/docs/api/components/game-object/fixed-update.md @@ -0,0 +1,14 @@ +# GameObject::FixedUpdate + +固定频率更新游戏对象及其所有组件（用于物理）。 + +```cpp +void FixedUpdate(); +``` + +以固定时间间隔调用，适合物理模拟更新。 + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [Update](update.md) diff --git a/docs/api/components/game-object/game-object.md b/docs/api/components/game-object/game-object.md new file mode 100644 index 00000000..01b48f88 --- /dev/null +++ b/docs/api/components/game-object/game-object.md @@ -0,0 +1,118 @@ +# GameObject + +**命名空间**: `XCEngine::Components` + +**类型**: `class` + +**头文件**: `XCEngine/Components/GameObject.h` + +**描述**: ECS 架构中的游戏对象实体，可附加组件并形成层级结构。 + +## 概述 + +GameObject 是 XCEngine ECS 架构中的实体（Entity）类，代表游戏世界中的一个个对象（如角色、道具、光源等）。每个 GameObject 可以通过 AddComponent 附加各种组件（如 TransformComponent、AudioSourceComponent）来定义其行为和数据。GameObject 支持层级结构（父子关系）、名称查找、标签系统和生命周期管理。 + +## 类型别名 + +| 别名 | 类型 | 描述 | +|------|------|------| +| `ID` | `uint64_t` | 游戏对象唯一标识符类型 | +| `INVALID_ID` | `static constexpr ID` | 无效 ID 常量，值为 0 | + +## 公共方法 + +### 基础信息 + +| 方法 | 描述 | +|------|------| +| [`GetID`](get-id.md) | 获取唯一标识符 | +| [`GetName`](get-name.md) | 获取名称 | +| [`SetName`](set-name.md) | 设置名称 | +| [`GetScene`](get-scene.md) | 获取所属场景 | + +### 组件系统 + +| 方法 | 描述 | +|------|------| +| [`GetTransform`](get-transform.md) | 获取变换组件 | +| [`AddComponent`](add-component.md) | 添加组件（模板方法） | +| [`GetComponent`](get-component.md) | 获取组件（模板方法） | +| [`GetComponents`](get-components.md) | 获取所有指定类型组件（模板方法） | +| [`GetComponentInChildren`](get-component-in-children.md) | 在子对象中查找组件 | +| [`GetComponentInParent`](get-component-in-parent.md) | 在父对象中查找组件 | +| [`GetComponentsInChildren`](get-components-in-children.md) | 获取所有子对象的指定组件 | + +### 层级结构 + +| 方法 | 描述 | +|------|------| +| [`GetParent`](get-parent.md) | 获取父对象 | +| [`SetParent`](set-parent.md) | 设置父对象 | +| [`GetChildCount`](get-child-count.md) | 获取子对象数量 | +| [`GetChild`](get-child.md) | 获取指定索引的子对象 | +| [`GetChildren`](get-children.md) | 获取所有子对象 | +| [`DetachChildren`](detach-children.md) | 分离所有子对象 | + +### 激活状态 + +| 方法 | 描述 | +|------|------| +| [`IsActive`](is-active.md) | 检查自身激活状态 | +| [`SetActive`](set-active.md) | 设置激活状态 | +| [`IsActiveInHierarchy`](is-active-in-hierarchy.md) | 检查在层级中的激活状态 | + +### 静态查找 + +| 方法 | 描述 | +|------|------| +| `static Find(name)` | 查找指定名称的对象 | +| `static FindObjectsOfType()` | 查找所有对象 | +| `static FindGameObjectsWithTag(tag)` | 查找具有指定标签的对象 | + +### 生命周期 + +| 方法 | 描述 | +|------|------| +| [`Awake`](awake.md) | 唤醒对象 | +| [`Start`](start.md) | 开始对象 | +| [`Update`](update.md) | 每帧更新 | +| [`FixedUpdate`](fixed-update.md) | 固定频率更新 | +| [`LateUpdate`](late-update.md) | 晚更新 | +| [`OnDestroy`](on-destroy.md) | 销毁回调 | +| [`Destroy`](destroy.md) | 销毁对象 | + +## 使用示例 + +```cpp +#include +#include +#include + +using namespace XCEngine::Components; + +void CreatePlayer() { + GameObject* player = new GameObject("Player"); + + auto transform = player->AddComponent(); + transform->SetPosition(Vector3(0, 0, 0)); + + auto audio = player->AddComponent(); + audio->SetVolume(0.8f); + + player->SetParent(cameraObject); +} + +void FindAndOperate() { + GameObject* enemy = GameObject::Find("Enemy"); + if (enemy) { + enemy->SetActive(false); + } +} +``` + +## 相关文档 + +- [Components 模块总览](../components.md) - Components 模块总览 +- [Component](component/component.md) - 组件基类 +- [TransformComponent](transform-component/transform-component.md) - 变换组件 +- [Scene](../scene/scene/scene.md) - 场景 diff --git a/docs/api/components/game-object/get-child-count.md b/docs/api/components/game-object/get-child-count.md new file mode 100644 index 00000000..f779b097 --- /dev/null +++ b/docs/api/components/game-object/get-child-count.md @@ -0,0 +1,14 @@ +# GameObject::GetChildCount + +获取子对象数量。 + +```cpp +size_t GetChildCount() const; +``` + +**返回：** `size_t` - 子对象数量 + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [GetChild](get-child.md) diff --git a/docs/api/components/game-object/get-child.md b/docs/api/components/game-object/get-child.md new file mode 100644 index 00000000..4958fda9 --- /dev/null +++ b/docs/api/components/game-object/get-child.md @@ -0,0 +1,17 @@ +# GameObject::GetChild + +获取指定索引的子对象。 + +```cpp +GameObject* GetChild(size_t index) const; +``` + +**参数：** +- `index` - 子对象索引 + +**返回：** `GameObject*` - 指定索引的子对象，如果索引无效则返回 nullptr + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [GetChildren](get-children.md) diff --git a/docs/api/components/game-object/get-children.md b/docs/api/components/game-object/get-children.md new file mode 100644 index 00000000..32229e65 --- /dev/null +++ b/docs/api/components/game-object/get-children.md @@ -0,0 +1,14 @@ +# GameObject::GetChildren + +获取所有子对象。 + +```cpp +std::vector GetChildren() const; +``` + +**返回：** `std::vector` - 包含所有子对象的向量 + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [GetChild](get-child.md) diff --git a/docs/api/components/game-object/get-component-in-children.md b/docs/api/components/game-object/get-component-in-children.md new file mode 100644 index 00000000..9bd4fd16 --- /dev/null +++ b/docs/api/components/game-object/get-component-in-children.md @@ -0,0 +1,20 @@ +# GameObject::GetComponentInChildren + +在子对象中查找指定类型的组件。 + +```cpp +template +T* GetComponentInChildren(); +``` + +递归搜索所有子对象（深度优先），返回找到的第一个匹配组件。 + +**模板参数：** +- `T` - 组件类型 + +**返回：** `T*` - 找到的组件指针，如果未找到则返回 nullptr + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [GetComponentsInChildren](get-components-in-children.md) diff --git a/docs/api/components/game-object/get-component-in-parent.md b/docs/api/components/game-object/get-component-in-parent.md new file mode 100644 index 00000000..4258eb10 --- /dev/null +++ b/docs/api/components/game-object/get-component-in-parent.md @@ -0,0 +1,20 @@ +# GameObject::GetComponentInParent + +在父对象链中查找指定类型的组件。 + +```cpp +template +T* GetComponentInParent(); +``` + +递归向上搜索父对象及其父对象，返回找到的第一个匹配组件。 + +**模板参数：** +- `T` - 组件类型 + +**返回：** `T*` - 找到的组件指针，如果未找到则返回 nullptr + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [GetComponentInChildren](get-component-in-children.md) diff --git a/docs/api/components/game-object/get-component.md b/docs/api/components/game-object/get-component.md new file mode 100644 index 00000000..db3a496c --- /dev/null +++ b/docs/api/components/game-object/get-component.md @@ -0,0 +1,23 @@ +# GameObject::GetComponent + +获取游戏对象上指定类型的组件。 + +```cpp +template +T* GetComponent(); + +template +const T* GetComponent() const; +``` + +使用 dynamic_cast 在组件列表中查找匹配类型的第一个组件。 + +**模板参数：** +- `T` - 组件类型 + +**返回：** `T*` - 找到的组件指针，如果未找到则返回 nullptr + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [GetComponents](get-components.md) diff --git a/docs/api/components/game-object/get-components-in-children.md b/docs/api/components/game-object/get-components-in-children.md new file mode 100644 index 00000000..fa03bf94 --- /dev/null +++ b/docs/api/components/game-object/get-components-in-children.md @@ -0,0 +1,20 @@ +# GameObject::GetComponentsInChildren + +获取所有子对象中指定类型的组件。 + +```cpp +template +std::vector GetComponentsInChildren(); +``` + +递归搜索所有子对象，返回所有匹配类型的组件。 + +**模板参数：** +- `T` - 组件类型 + +**返回：** `std::vector` - 包含所有匹配组件的向量 + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [GetComponentInChildren](get-component-in-children.md) diff --git a/docs/api/components/game-object/get-components.md b/docs/api/components/game-object/get-components.md new file mode 100644 index 00000000..27b085cc --- /dev/null +++ b/docs/api/components/game-object/get-components.md @@ -0,0 +1,21 @@ +# GameObject::GetComponents + +获取游戏对象上所有指定类型的组件。 + +```cpp +template +std::vector GetComponents(); + +template +std::vector GetComponents() const; +``` + +**模板参数：** +- `T` - 组件类型 + +**返回：** `std::vector` - 包含所有匹配组件的向量 + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [GetComponent](get-component.md) diff --git a/docs/api/components/game-object/get-id.md b/docs/api/components/game-object/get-id.md new file mode 100644 index 00000000..ce95cf3a --- /dev/null +++ b/docs/api/components/game-object/get-id.md @@ -0,0 +1,13 @@ +# GameObject::GetID + +获取游戏对象的唯一标识符。 + +```cpp +ID GetID() const; +``` + +**返回：** `ID` - 游戏对象的唯一标识符 + +## 相关文档 + +- [GameObject 总览](game-object.md) diff --git a/docs/api/components/game-object/get-name.md b/docs/api/components/game-object/get-name.md new file mode 100644 index 00000000..aae44046 --- /dev/null +++ b/docs/api/components/game-object/get-name.md @@ -0,0 +1,14 @@ +# GameObject::GetName + +获取游戏对象的名称。 + +```cpp +const std::string& GetName() const; +``` + +**返回：** `const std::string&` - 游戏对象名称引用 + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [SetName](set-name.md) diff --git a/docs/api/components/game-object/get-parent.md b/docs/api/components/game-object/get-parent.md new file mode 100644 index 00000000..edd5bc83 --- /dev/null +++ b/docs/api/components/game-object/get-parent.md @@ -0,0 +1,14 @@ +# GameObject::GetParent + +获取父游戏对象。 + +```cpp +GameObject* GetParent() const; +``` + +**返回：** `GameObject*` - 父对象指针，如果无父对象则返回 nullptr + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [SetParent](set-parent.md) diff --git a/docs/api/components/game-object/get-scene.md b/docs/api/components/game-object/get-scene.md new file mode 100644 index 00000000..766a6a1b --- /dev/null +++ b/docs/api/components/game-object/get-scene.md @@ -0,0 +1,14 @@ +# GameObject::GetScene + +获取游戏对象所属的场景。 + +```cpp +Scene* GetScene() const; +``` + +**返回：** `Scene*` - 所属场景指针，如果对象未属于任何场景则返回 nullptr + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [Scene](../scene/scene/scene.md) diff --git a/docs/api/components/game-object/get-transform.md b/docs/api/components/game-object/get-transform.md new file mode 100644 index 00000000..ed30aa95 --- /dev/null +++ b/docs/api/components/game-object/get-transform.md @@ -0,0 +1,15 @@ +# GameObject::GetTransform + +获取游戏对象的变换组件。 + +```cpp +TransformComponent* GetTransform(); +const TransformComponent* GetTransform() const; +``` + +**返回：** `TransformComponent*` - 变换组件指针 + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [TransformComponent](transform-component/transform-component.md) diff --git a/docs/api/components/game-object/is-active-in-hierarchy.md b/docs/api/components/game-object/is-active-in-hierarchy.md new file mode 100644 index 00000000..85e4a09f --- /dev/null +++ b/docs/api/components/game-object/is-active-in-hierarchy.md @@ -0,0 +1,16 @@ +# GameObject::IsActiveInHierarchy + +检查游戏对象在层级中的激活状态。 + +```cpp +bool IsActiveInHierarchy() const; +``` + +如果对象本身激活但父对象（或更上层的祖先）被禁用，则返回 false。只有当对象及其所有祖先都激活时，才返回 true。 + +**返回：** `bool` - 如果对象在层级中激活则返回 true + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [IsActive](is-active.md) diff --git a/docs/api/components/game-object/is-active.md b/docs/api/components/game-object/is-active.md new file mode 100644 index 00000000..f747bfbc --- /dev/null +++ b/docs/api/components/game-object/is-active.md @@ -0,0 +1,15 @@ +# GameObject::IsActive + +检查游戏对象的自身激活状态。 + +```cpp +bool IsActive() const; +``` + +**返回：** `bool` - 如果对象自身激活则返回 true + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [SetActive](set-active.md) +- [IsActiveInHierarchy](is-active-in-hierarchy.md) diff --git a/docs/api/components/game-object/late-update.md b/docs/api/components/game-object/late-update.md new file mode 100644 index 00000000..3e48e191 --- /dev/null +++ b/docs/api/components/game-object/late-update.md @@ -0,0 +1,17 @@ +# GameObject::LateUpdate + +晚更新游戏对象及其所有组件。 + +```cpp +void LateUpdate(float deltaTime); +``` + +在所有 Update 调用之后调用，适合处理依赖于其他对象更新的逻辑。 + +**参数：** +- `deltaTime` - 距离上一帧的时间（秒） + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [Update](update.md) diff --git a/docs/api/components/game-object/on-destroy.md b/docs/api/components/game-object/on-destroy.md new file mode 100644 index 00000000..628535d9 --- /dev/null +++ b/docs/api/components/game-object/on-destroy.md @@ -0,0 +1,14 @@ +# GameObject::OnDestroy + +销毁回调。 + +```cpp +void OnDestroy(); +``` + +在对象被销毁前调用，用于清理资源。 + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [Destroy](destroy.md) diff --git a/docs/api/components/game-object/set-active.md b/docs/api/components/game-object/set-active.md new file mode 100644 index 00000000..39fbcc57 --- /dev/null +++ b/docs/api/components/game-object/set-active.md @@ -0,0 +1,15 @@ +# GameObject::SetActive + +设置游戏对象的激活状态。 + +```cpp +void SetActive(bool active); +``` + +**参数：** +- `active` - true 激活，false 禁用 + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [IsActive](is-active.md) diff --git a/docs/api/components/game-object/set-name.md b/docs/api/components/game-object/set-name.md new file mode 100644 index 00000000..6fad9083 --- /dev/null +++ b/docs/api/components/game-object/set-name.md @@ -0,0 +1,15 @@ +# GameObject::SetName + +设置游戏对象的名称。 + +```cpp +void SetName(const std::string& name); +``` + +**参数：** +- `name` - 新的名称 + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [GetName](get-name.md) diff --git a/docs/api/components/game-object/set-parent.md b/docs/api/components/game-object/set-parent.md new file mode 100644 index 00000000..9217dcfe --- /dev/null +++ b/docs/api/components/game-object/set-parent.md @@ -0,0 +1,19 @@ +# GameObject::SetParent + +设置父游戏对象。 + +```cpp +void SetParent(GameObject* parent); +void SetParent(GameObject* parent, bool worldPositionStays); +``` + +将当前 GameObject 的父对象设置为指定对象。 + +**参数：** +- `parent` - 新的父对象，nullptr 表示成为根对象 +- `worldPositionStays` - true 保持世界坐标不变，false 保持本地坐标不变 + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [GetParent](get-parent.md) diff --git a/docs/api/components/game-object/start.md b/docs/api/components/game-object/start.md new file mode 100644 index 00000000..618d1904 --- /dev/null +++ b/docs/api/components/game-object/start.md @@ -0,0 +1,15 @@ +# GameObject::Start + +开始游戏对象及其所有组件。 + +```cpp +void Start(); +``` + +在首次 Update 之前调用，用于在游戏逻辑开始前完成初始化。 + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [Awake](awake.md) +- [Update](update.md) diff --git a/docs/api/components/game-object/update.md b/docs/api/components/game-object/update.md new file mode 100644 index 00000000..6ad01cc4 --- /dev/null +++ b/docs/api/components/game-object/update.md @@ -0,0 +1,15 @@ +# GameObject::Update + +每帧更新游戏对象及其所有组件。 + +```cpp +void Update(float deltaTime); +``` + +**参数：** +- `deltaTime` - 距离上一帧的时间（秒） + +## 相关文档 + +- [GameObject 总览](game-object.md) +- [LateUpdate](late-update.md) diff --git a/docs/api/components/transform-component/detach-children.md b/docs/api/components/transform-component/detach-children.md new file mode 100644 index 00000000..15f5852f --- /dev/null +++ b/docs/api/components/transform-component/detach-children.md @@ -0,0 +1,26 @@ +# DetachChildren + +Detach all child transforms. + +## Syntax + +```cpp +void DetachChildren(); +``` + +## Remarks + +Removes all children from this transform. The children become root-level transforms (their parent is set to `nullptr`). + +## See Also + +- [SetParent](set-parent) +- [GetChild](get-child) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + transform->DetachChildren(); +} +``` diff --git a/docs/api/components/transform-component/find.md b/docs/api/components/transform-component/find.md new file mode 100644 index 00000000..85d4ab91 --- /dev/null +++ b/docs/api/components/transform-component/find.md @@ -0,0 +1,33 @@ +# Find + +Find a child transform by name. + +## Syntax + +```cpp +TransformComponent* Find(const std::string& name) const; +``` + +## Parameters + +- `name` - The name of the child transform to find. + +## Returns + +Returns a pointer to the child transform with the specified name, or `nullptr` if not found. Only searches direct children, not the entire hierarchy. + +## See Also + +- [GetChild](get-child) +- [GetChildCount](get-child-count) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + TransformComponent* child = transform->Find("Weapon"); + if (child) { + XC_LOG_INFO("Found child: {}", child->GetName()); + } +} +``` diff --git a/docs/api/components/transform-component/get-child-count.md b/docs/api/components/transform-component/get-child-count.md new file mode 100644 index 00000000..36052196 --- /dev/null +++ b/docs/api/components/transform-component/get-child-count.md @@ -0,0 +1,27 @@ +# GetChildCount + +Get the number of child transforms. + +## Syntax + +```cpp +size_t GetChildCount() const; +``` + +## Returns + +Returns the number of direct child transforms. + +## See Also + +- [GetChild](get-child) +- [GetParent](get-parent) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + size_t count = transform->GetChildCount(); + XC_LOG_INFO("Child count: {}", count); +} +``` diff --git a/docs/api/components/transform-component/get-child.md b/docs/api/components/transform-component/get-child.md new file mode 100644 index 00000000..34083920 --- /dev/null +++ b/docs/api/components/transform-component/get-child.md @@ -0,0 +1,32 @@ +# GetChild + +Get a child transform by index. + +## Syntax + +```cpp +TransformComponent* GetChild(size_t index) const; +``` + +## Parameters + +- `index` - The index of the child transform (0-based). + +## Returns + +Returns a pointer to the child transform at the specified index, or `nullptr` if the index is out of range. + +## See Also + +- [GetChildCount](get-child-count) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + TransformComponent* firstChild = transform->GetChild(0); + if (firstChild) { + XC_LOG_INFO("First child: {}", firstChild->GetName()); + } +} +``` diff --git a/docs/api/components/transform-component/get-forward.md b/docs/api/components/transform-component/get-forward.md new file mode 100644 index 00000000..3e9f13a8 --- /dev/null +++ b/docs/api/components/transform-component/get-forward.md @@ -0,0 +1,31 @@ +# GetForward + +Get the forward direction vector in world space. + +## Syntax + +```cpp +Math::Vector3 GetForward() const; +``` + +## Returns + +Returns the forward direction vector as a `Math::Vector3`. + +## Remarks + +Returns the forward direction of this transform in world space, based on the world rotation. By convention, forward is typically the negative Z axis direction. + +## See Also + +- [GetRight](get-right) +- [GetUp](get-up) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + Math::Vector3 forward = transform->GetForward(); + XC_LOG_INFO("Forward: ({}, {}, {})", forward.x, forward.y, forward.z); +} +``` diff --git a/docs/api/components/transform-component/get-local-euler-angles.md b/docs/api/components/transform-component/get-local-euler-angles.md new file mode 100644 index 00000000..c64ed009 --- /dev/null +++ b/docs/api/components/transform-component/get-local-euler-angles.md @@ -0,0 +1,31 @@ +# GetLocalEulerAngles + +Get the local rotation as Euler angles in degrees. + +## Syntax + +```cpp +Math::Vector3 GetLocalEulerAngles() const; +``` + +## Returns + +Returns the local rotation as Euler angles `(x, y, z)` in degrees. + +## Remarks + +Converts the local quaternion rotation to Euler angles representation. The angles represent rotation around the X, Y, and Z axes respectively. + +## See Also + +- [SetLocalEulerAngles](set-local-euler-angles) +- [GetLocalRotation](get-local-rotation) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + Math::Vector3 eulers = transform->GetLocalEulerAngles(); + XC_LOG_INFO("Local euler angles: ({}, {}, {})", eulers.x, eulers.y, eulers.z); +} +``` diff --git a/docs/api/components/transform-component/get-local-position.md b/docs/api/components/transform-component/get-local-position.md new file mode 100644 index 00000000..b36ca2f9 --- /dev/null +++ b/docs/api/components/transform-component/get-local-position.md @@ -0,0 +1,33 @@ +# GetLocalPosition + +Get the position of this transform relative to the parent transform. + +## Syntax + +```cpp +const Math::Vector3& GetLocalPosition() const; +``` + +## Returns + +Returns the local position as a `Math::Vector3` reference. The returned reference remains valid until the transform is modified. + +## Remarks + +Local position represents the position of this transform in parent space. If this transform has no parent, local position is the same as world position. + +## See Also + +- [SetLocalPosition](set-local-position) +- [GetPosition](get-position) +- [SetPosition](set-position) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + const Math::Vector3& localPos = transform->GetLocalPosition(); + XC_LOG_INFO("Local position: ({}, {}, {})", + localPos.x, localPos.y, localPos.z); +} +``` diff --git a/docs/api/components/transform-component/get-local-rotation.md b/docs/api/components/transform-component/get-local-rotation.md new file mode 100644 index 00000000..028ce20a --- /dev/null +++ b/docs/api/components/transform-component/get-local-rotation.md @@ -0,0 +1,33 @@ +# GetLocalRotation + +Get the rotation of this transform relative to the parent transform. + +## Syntax + +```cpp +const Math::Quaternion& GetLocalRotation() const; +``` + +## Returns + +Returns the local rotation as a `Math::Quaternion` reference. + +## Remarks + +Local rotation represents the rotation of this transform in parent space. If this transform has no parent, local rotation is the same as world rotation. + +## See Also + +- [SetLocalRotation](set-local-rotation) +- [GetRotation](get-rotation) +- [SetRotation](set-rotation) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + const Math::Quaternion& localRot = transform->GetLocalRotation(); + XC_LOG_INFO("Local rotation: ({}, {}, {}, {})", + localRot.x, localRot.y, localRot.z, localRot.w); +} +``` diff --git a/docs/api/components/transform-component/get-local-scale.md b/docs/api/components/transform-component/get-local-scale.md new file mode 100644 index 00000000..00422003 --- /dev/null +++ b/docs/api/components/transform-component/get-local-scale.md @@ -0,0 +1,31 @@ +# GetLocalScale + +Get the scale of this transform relative to the parent transform. + +## Syntax + +```cpp +const Math::Vector3& GetLocalScale() const; +``` + +## Returns + +Returns the local scale as a `Math::Vector3` reference. + +## Remarks + +Local scale represents the scale of this transform in parent space. If this transform has no parent, local scale is the same as world scale. + +## See Also + +- [SetLocalScale](set-local-scale) +- [GetScale](get-scale) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + const Math::Vector3& scale = transform->GetLocalScale(); + XC_LOG_INFO("Local scale: ({}, {}, {})", scale.x, scale.y, scale.z); +} +``` diff --git a/docs/api/components/transform-component/get-local-to-world-matrix.md b/docs/api/components/transform-component/get-local-to-world-matrix.md new file mode 100644 index 00000000..53341950 --- /dev/null +++ b/docs/api/components/transform-component/get-local-to-world-matrix.md @@ -0,0 +1,29 @@ +# GetLocalToWorldMatrix + +Get the transformation matrix from local space to world space. + +## Syntax + +```cpp +const Math::Matrix4x4& GetLocalToWorldMatrix() const; +``` + +## Returns + +Returns the local-to-world transformation matrix as a `Math::Matrix4x4` reference. + +## Remarks + +Returns the matrix that transforms a point from local space to world space. The matrix is computed from the local position, rotation, and scale combined with the parent's world transform. Uses lazy evaluation and is cached until the transform is marked dirty. + +## See Also + +- [GetWorldToLocalMatrix](get-world-to-local-matrix) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + const Math::Matrix4x4& matrix = transform->GetLocalToWorldMatrix(); +} +``` diff --git a/docs/api/components/transform-component/get-parent.md b/docs/api/components/transform-component/get-parent.md new file mode 100644 index 00000000..d221e643 --- /dev/null +++ b/docs/api/components/transform-component/get-parent.md @@ -0,0 +1,32 @@ +# GetParent + +Get the parent transform. + +## Syntax + +```cpp +TransformComponent* GetParent() const; +``` + +## Returns + +Returns a pointer to the parent `TransformComponent`, or `nullptr` if this transform has no parent. + +## Remarks + +Returns the parent transform in the transform hierarchy. The parent transform affects this transform's world position, rotation, and scale. + +## See Also + +- [SetParent](set-parent) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + TransformComponent* parent = transform->GetParent(); + if (parent) { + XC_LOG_INFO("Has parent: {}", parent->GetName()); + } +} +``` diff --git a/docs/api/components/transform-component/get-position.md b/docs/api/components/transform-component/get-position.md new file mode 100644 index 00000000..171673c8 --- /dev/null +++ b/docs/api/components/transform-component/get-position.md @@ -0,0 +1,33 @@ +# GetPosition + +Get the world position of this transform. + +## Syntax + +```cpp +Math::Vector3 GetPosition() const; +``` + +## Returns + +Returns the world position as a `Math::Vector3`. + +## Remarks + +Returns the world-space position of this transform. If this transform has a parent, the world position is computed by combining the local position with the parent's world position. + +## See Also + +- [GetLocalPosition](get-local-position) +- [SetLocalPosition](set-local-position) +- [SetPosition](set-position) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + Math::Vector3 worldPos = transform->GetPosition(); + XC_LOG_INFO("World position: ({}, {}, {})", + worldPos.x, worldPos.y, worldPos.z); +} +``` diff --git a/docs/api/components/transform-component/get-right.md b/docs/api/components/transform-component/get-right.md new file mode 100644 index 00000000..197421c1 --- /dev/null +++ b/docs/api/components/transform-component/get-right.md @@ -0,0 +1,30 @@ +# GetRight + +Get the right direction vector in world space. + +## Syntax + +```cpp +Math::Vector3 GetRight() const; +``` + +## Returns + +Returns the right direction vector as a `Math::Vector3`. + +## Remarks + +Returns the right direction of this transform in world space, based on the world rotation. By convention, right is typically the positive X axis direction. + +## See Also + +- [GetForward](get-forward) +- [GetUp](get-up) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + Math::Vector3 right = transform->GetRight(); +} +``` diff --git a/docs/api/components/transform-component/get-rotation.md b/docs/api/components/transform-component/get-rotation.md new file mode 100644 index 00000000..e0f20e8b --- /dev/null +++ b/docs/api/components/transform-component/get-rotation.md @@ -0,0 +1,31 @@ +# GetRotation + +Get the world rotation of this transform. + +## Syntax + +```cpp +Math::Quaternion GetRotation() const; +``` + +## Returns + +Returns the world rotation as a `Math::Quaternion`. + +## Remarks + +Returns the world-space rotation of this transform. If this transform has a parent, the world rotation is computed by combining the local rotation with the parent's world rotation. + +## See Also + +- [GetLocalRotation](get-local-rotation) +- [SetLocalRotation](set-local-rotation) +- [SetRotation](set-rotation) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + Math::Quaternion worldRot = transform->GetRotation(); +} +``` diff --git a/docs/api/components/transform-component/get-scale.md b/docs/api/components/transform-component/get-scale.md new file mode 100644 index 00000000..74991d6a --- /dev/null +++ b/docs/api/components/transform-component/get-scale.md @@ -0,0 +1,31 @@ +# GetScale + +Get the world scale of this transform. + +## Syntax + +```cpp +Math::Vector3 GetScale() const; +``` + +## Returns + +Returns the world scale as a `Math::Vector3`. + +## Remarks + +Returns the world-space scale of this transform. If this transform has a parent, the world scale is computed by multiplying the local scale with the parent's world scale. + +## See Also + +- [GetLocalScale](get-local-scale) +- [SetLocalScale](set-local-scale) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + Math::Vector3 worldScale = transform->GetScale(); + XC_LOG_INFO("World scale: ({}, {}, {})", worldScale.x, worldScale.y, worldScale.z); +} +``` diff --git a/docs/api/components/transform-component/get-sibling-index.md b/docs/api/components/transform-component/get-sibling-index.md new file mode 100644 index 00000000..adbdd359 --- /dev/null +++ b/docs/api/components/transform-component/get-sibling-index.md @@ -0,0 +1,28 @@ +# GetSiblingIndex + +Get the sibling index of this transform among siblings. + +## Syntax + +```cpp +int GetSiblingIndex() const; +``` + +## Returns + +Returns the sibling index of this transform. + +## See Also + +- [SetSiblingIndex](set-sibling-index) +- [SetAsFirstSibling](set-as-first-sibling) +- [SetAsLastSibling](set-as-last-sibling) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + int index = transform->GetSiblingIndex(); + XC_LOG_INFO("Sibling index: {}", index); +} +``` diff --git a/docs/api/components/transform-component/get-up.md b/docs/api/components/transform-component/get-up.md new file mode 100644 index 00000000..6d2e4bf7 --- /dev/null +++ b/docs/api/components/transform-component/get-up.md @@ -0,0 +1,30 @@ +# GetUp + +Get the up direction vector in world space. + +## Syntax + +```cpp +Math::Vector3 GetUp() const; +``` + +## Returns + +Returns the up direction vector as a `Math::Vector3`. + +## Remarks + +Returns the up direction of this transform in world space, based on the world rotation. By convention, up is typically the positive Y axis direction. + +## See Also + +- [GetForward](get-forward) +- [GetRight](get-right) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + Math::Vector3 up = transform->GetUp(); +} +``` diff --git a/docs/api/components/transform-component/get-world-to-local-matrix.md b/docs/api/components/transform-component/get-world-to-local-matrix.md new file mode 100644 index 00000000..6b4d03be --- /dev/null +++ b/docs/api/components/transform-component/get-world-to-local-matrix.md @@ -0,0 +1,29 @@ +# GetWorldToLocalMatrix + +Get the transformation matrix from world space to local space. + +## Syntax + +```cpp +Math::Matrix4x4 GetWorldToLocalMatrix() const; +``` + +## Returns + +Returns the world-to-local transformation matrix as a `Math::Matrix4x4`. + +## Remarks + +Returns the matrix that transforms a point from world space to local space. This is the inverse of `GetLocalToWorldMatrix()`. + +## See Also + +- [GetLocalToWorldMatrix](get-local-to-world-matrix) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + Math::Matrix4x4 worldToLocal = transform->GetWorldToLocalMatrix(); +} +``` diff --git a/docs/api/components/transform-component/inverse-transform-direction.md b/docs/api/components/transform-component/inverse-transform-direction.md new file mode 100644 index 00000000..14542764 --- /dev/null +++ b/docs/api/components/transform-component/inverse-transform-direction.md @@ -0,0 +1,35 @@ +# InverseTransformDirection + +Transform a direction from world space to local space. + +## Syntax + +```cpp +Math::Vector3 InverseTransformDirection(const Math::Vector3& direction) const; +``` + +## Parameters + +- `direction` - The world space direction to transform. + +## Returns + +Returns the transformed direction in local space. + +## Remarks + +Transforms a direction from world space to local space. Unlike `InverseTransformPoint`, this does not consider translation. Only rotation and scale are applied. + +## See Also + +- [TransformDirection](transform-direction) +- [InverseTransformPoint](inverse-transform-point) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + Math::Vector3 worldDir(1.0f, 0.0f, 0.0f); + Math::Vector3 localDir = transform->InverseTransformDirection(worldDir); +} +``` diff --git a/docs/api/components/transform-component/inverse-transform-point.md b/docs/api/components/transform-component/inverse-transform-point.md new file mode 100644 index 00000000..946fa46e --- /dev/null +++ b/docs/api/components/transform-component/inverse-transform-point.md @@ -0,0 +1,35 @@ +# InverseTransformPoint + +Transform a point from world space to local space. + +## Syntax + +```cpp +Math::Vector3 InverseTransformPoint(const Math::Vector3& point) const; +``` + +## Parameters + +- `point` - The world space point to transform. + +## Returns + +Returns the transformed point in local space. + +## Remarks + +Transforms a point from world space to local space using the transform's world-to-local matrix. + +## See Also + +- [TransformPoint](transform-point) +- [InverseTransformDirection](inverse-transform-direction) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + Math::Vector3 worldPoint(10.0f, 0.0f, 0.0f); + Math::Vector3 localPoint = transform->InverseTransformPoint(worldPoint); +} +``` diff --git a/docs/api/components/transform-component/look-at.md b/docs/api/components/transform-component/look-at.md new file mode 100644 index 00000000..bb4b76ca --- /dev/null +++ b/docs/api/components/transform-component/look-at.md @@ -0,0 +1,28 @@ +# LookAt + +Rotate the transform to face a target position. + +## Syntax + +```cpp +void LookAt(const Math::Vector3& target); +void LookAt(const Math::Vector3& target, const Math::Vector3& up); +``` + +## Parameters + +- `target` - The position to look at. +- `up` - The up vector to use (defaults to world up). + +## Remarks + +Rotates the transform so its forward direction points toward the target position. The optional `up` vector defines which direction is considered up. + +## Examples + +```cpp +void Example(TransformComponent* transform) { + Math::Vector3 targetPos(10.0f, 0.0f, 5.0f); + transform->LookAt(targetPos); +} +``` diff --git a/docs/api/components/transform-component/rotate.md b/docs/api/components/transform-component/rotate.md new file mode 100644 index 00000000..978acece --- /dev/null +++ b/docs/api/components/transform-component/rotate.md @@ -0,0 +1,29 @@ +# Rotate + +Rotate the transform by the specified angles. + +## Syntax + +```cpp +void Rotate(const Math::Vector3& eulers, Space relativeTo = Space::Self); +void Rotate(const Math::Vector3& axis, float angle, Space relativeTo = Space::Self); +``` + +## Parameters + +- `eulers` - The Euler angles of rotation (x, y, z). +- `axis` - The axis of rotation. +- `angle` - The angle of rotation in degrees. +- `relativeTo` - Whether the rotation is relative to self or world space. + +## Remarks + +Applies a rotation to the transform. When `relativeTo` is `Space::Self`, the rotation is applied in local space. When `Space::World`, the rotation is applied in world space. + +## Examples + +```cpp +void Example(TransformComponent* transform) { + transform->Rotate(Math::Vector3(0.0f, 45.0f, 0.0f), Space::Self); +} +``` diff --git a/docs/api/components/transform-component/set-as-first-sibling.md b/docs/api/components/transform-component/set-as-first-sibling.md new file mode 100644 index 00000000..fa9b6395 --- /dev/null +++ b/docs/api/components/transform-component/set-as-first-sibling.md @@ -0,0 +1,22 @@ +# SetAsFirstSibling + +Set this transform as the first sibling (index 0). + +## Syntax + +```cpp +void SetAsFirstSibling(); +``` + +## See Also + +- [SetSiblingIndex](set-sibling-index) +- [SetAsLastSibling](set-as-last-sibling) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + transform->SetAsFirstSibling(); +} +``` diff --git a/docs/api/components/transform-component/set-as-last-sibling.md b/docs/api/components/transform-component/set-as-last-sibling.md new file mode 100644 index 00000000..0d31519a --- /dev/null +++ b/docs/api/components/transform-component/set-as-last-sibling.md @@ -0,0 +1,22 @@ +# SetAsLastSibling + +Set this transform as the last sibling. + +## Syntax + +```cpp +void SetAsLastSibling(); +``` + +## See Also + +- [SetSiblingIndex](set-sibling-index) +- [SetAsFirstSibling](set-as-first-sibling) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + transform->SetAsLastSibling(); +} +``` diff --git a/docs/api/components/transform-component/set-local-euler-angles.md b/docs/api/components/transform-component/set-local-euler-angles.md new file mode 100644 index 00000000..98fd3b42 --- /dev/null +++ b/docs/api/components/transform-component/set-local-euler-angles.md @@ -0,0 +1,30 @@ +# SetLocalEulerAngles + +Set the local rotation using Euler angles in degrees. + +## Syntax + +```cpp +void SetLocalEulerAngles(const Math::Vector3& eulers); +``` + +## Parameters + +- `eulers` - The Euler angles `(x, y, z)` in degrees. + +## Remarks + +Sets the local rotation by converting the Euler angles to a quaternion. The angles represent rotation around the X, Y, and Z axes respectively. + +## See Also + +- [GetLocalEulerAngles](get-local-euler-angles) +- [SetLocalRotation](set-local-rotation) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + transform->SetLocalEulerAngles(Math::Vector3(45.0f, 90.0f, 0.0f)); +} +``` diff --git a/docs/api/components/transform-component/set-local-position.md b/docs/api/components/transform-component/set-local-position.md new file mode 100644 index 00000000..003aca7c --- /dev/null +++ b/docs/api/components/transform-component/set-local-position.md @@ -0,0 +1,31 @@ +# SetLocalPosition + +Set the position of this transform relative to the parent transform. + +## Syntax + +```cpp +void SetLocalPosition(const Math::Vector3& position); +``` + +## Parameters + +- `position` - The new local position as a `Math::Vector3`. + +## Remarks + +Sets the local position of this transform. If this transform has no parent, local position is the same as world position. This marks the transform as dirty, requiring world transform recalculation. + +## See Also + +- [GetLocalPosition](get-local-position) +- [GetPosition](get-position) +- [SetPosition](set-position) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + transform->SetLocalPosition(Math::Vector3(10.0f, 0.0f, 5.0f)); +} +``` diff --git a/docs/api/components/transform-component/set-local-rotation.md b/docs/api/components/transform-component/set-local-rotation.md new file mode 100644 index 00000000..660dad3a --- /dev/null +++ b/docs/api/components/transform-component/set-local-rotation.md @@ -0,0 +1,32 @@ +# SetLocalRotation + +Set the rotation of this transform relative to the parent transform. + +## Syntax + +```cpp +void SetLocalRotation(const Math::Quaternion& rotation); +``` + +## Parameters + +- `rotation` - The new local rotation as a `Math::Quaternion`. + +## Remarks + +Sets the local rotation of this transform. If this transform has no parent, local rotation is the same as world rotation. This marks the transform as dirty. + +## See Also + +- [GetLocalRotation](get-local-rotation) +- [GetRotation](get-rotation) +- [SetRotation](set-rotation) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + Math::Quaternion rotation = Math::Quaternion::FromEuler(0.0f, 90.0f, 0.0f); + transform->SetLocalRotation(rotation); +} +``` diff --git a/docs/api/components/transform-component/set-local-scale.md b/docs/api/components/transform-component/set-local-scale.md new file mode 100644 index 00000000..62dafe94 --- /dev/null +++ b/docs/api/components/transform-component/set-local-scale.md @@ -0,0 +1,30 @@ +# SetLocalScale + +Set the scale of this transform relative to the parent transform. + +## Syntax + +```cpp +void SetLocalScale(const Math::Vector3& scale); +``` + +## Parameters + +- `scale` - The new local scale as a `Math::Vector3`. + +## Remarks + +Sets the local scale of this transform. If this transform has no parent, local scale is the same as world scale. This marks the transform as dirty. + +## See Also + +- [GetLocalScale](get-local-scale) +- [GetScale](get-scale) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + transform->SetLocalScale(Math::Vector3(2.0f, 2.0f, 2.0f)); +} +``` diff --git a/docs/api/components/transform-component/set-parent.md b/docs/api/components/transform-component/set-parent.md new file mode 100644 index 00000000..6a72601a --- /dev/null +++ b/docs/api/components/transform-component/set-parent.md @@ -0,0 +1,31 @@ +# SetParent + +Set the parent transform. + +## Syntax + +```cpp +void SetParent(TransformComponent* parent, bool worldPositionStays = true); +``` + +## Parameters + +- `parent` - The new parent transform, or `nullptr` to detach from parent. +- `worldPositionStays` - If `true`, the world position remains unchanged after reparenting. + +## Remarks + +Sets the parent of this transform. When `worldPositionStays` is `true`, the world position is preserved, which may adjust the local position. When `false`, the local position is preserved, which may adjust the world position. + +## See Also + +- [GetParent](get-parent) +- [DetachChildren](detach-children) + +## Examples + +```cpp +void Example(TransformComponent* child, TransformComponent* newParent) { + child->SetParent(newParent, true); +} +``` diff --git a/docs/api/components/transform-component/set-position.md b/docs/api/components/transform-component/set-position.md new file mode 100644 index 00000000..bf82f5d1 --- /dev/null +++ b/docs/api/components/transform-component/set-position.md @@ -0,0 +1,31 @@ +# SetPosition + +Set the world position of this transform. + +## Syntax + +```cpp +void SetPosition(const Math::Vector3& position); +``` + +## Parameters + +- `position` - The new world position as a `Math::Vector3`. + +## Remarks + +Sets the world-space position of this transform. If this transform has a parent, the local position is computed by transforming the world position into parent space. + +## See Also + +- [GetPosition](get-position) +- [GetLocalPosition](get-local-position) +- [SetLocalPosition](set-local-position) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + transform->SetPosition(Math::Vector3(100.0f, 50.0f, 25.0f)); +} +``` diff --git a/docs/api/components/transform-component/set-rotation.md b/docs/api/components/transform-component/set-rotation.md new file mode 100644 index 00000000..6b171faa --- /dev/null +++ b/docs/api/components/transform-component/set-rotation.md @@ -0,0 +1,32 @@ +# SetRotation + +Set the world rotation of this transform. + +## Syntax + +```cpp +void SetRotation(const Math::Quaternion& rotation); +``` + +## Parameters + +- `rotation` - The new world rotation as a `Math::Quaternion`. + +## Remarks + +Sets the world-space rotation of this transform. If this transform has a parent, the local rotation is computed by transforming the world rotation into parent space. + +## See Also + +- [GetRotation](get-rotation) +- [GetLocalRotation](get-local-rotation) +- [SetLocalRotation](set-local-rotation) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + Math::Quaternion rot = Math::Quaternion::FromEuler(0.0f, 180.0f, 0.0f); + transform->SetRotation(rot); +} +``` diff --git a/docs/api/components/transform-component/set-scale.md b/docs/api/components/transform-component/set-scale.md new file mode 100644 index 00000000..17575288 --- /dev/null +++ b/docs/api/components/transform-component/set-scale.md @@ -0,0 +1,31 @@ +# SetScale + +Set the world scale of this transform. + +## Syntax + +```cpp +void SetScale(const Math::Vector3& scale); +``` + +## Parameters + +- `scale` - The new world scale as a `Math::Vector3`. + +## Remarks + +Sets the world-space scale of this transform. If this transform has a parent, the local scale is computed accordingly. + +## See Also + +- [GetScale](get-scale) +- [GetLocalScale](get-local-scale) +- [SetLocalScale](set-local-scale) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + transform->SetScale(Math::Vector3(1.5f, 1.5f, 1.5f)); +} +``` diff --git a/docs/api/components/transform-component/set-sibling-index.md b/docs/api/components/transform-component/set-sibling-index.md new file mode 100644 index 00000000..fc4cbbd5 --- /dev/null +++ b/docs/api/components/transform-component/set-sibling-index.md @@ -0,0 +1,27 @@ +# SetSiblingIndex + +Set the sibling index of this transform. + +## Syntax + +```cpp +void SetSiblingIndex(int index); +``` + +## Parameters + +- `index` - The new sibling index. + +## See Also + +- [GetSiblingIndex](get-sibling-index) +- [SetAsFirstSibling](set-as-first-sibling) +- [SetAsLastSibling](set-as-last-sibling) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + transform->SetSiblingIndex(0); +} +``` diff --git a/docs/api/components/transform-component/transform-component.md b/docs/api/components/transform-component/transform-component.md new file mode 100644 index 00000000..d28801f9 --- /dev/null +++ b/docs/api/components/transform-component/transform-component.md @@ -0,0 +1,126 @@ +# TransformComponent + +**命名空间**: `XCEngine::Components` + +**类型**: `class` + +**头文件**: `XCEngine/Components/TransformComponent.h` + +**描述**: 游戏对象变换组件，管理位置、旋转、缩放和层级关系。 + +## 概述 + +TransformComponent 是 XCEngine ECS 系统中的变换组件，每个 GameObject 都拥有一个 TransformComponent。它管理对象的局部空间（Local）和世界空间（World）位置、旋转（四元数）和缩放，支持父子层级变换、方向向量计算（前后左右上下）、矩阵运算和坐标变换。变换组件使用延迟更新机制，只有在需要时才重新计算世界变换矩阵。 + +## 枚举 + +| 枚举值 | 描述 | +|--------|------| +| `Space::Self` | 相对于自身空间 | +| `Space::World` | 相对于世界空间 | + +## 公共方法 + +### 局部空间 + +| 方法 | 描述 | +|------|------| +| [`GetLocalPosition`](get-local-position.md) | 获取局部位置 | +| [`SetLocalPosition`](set-local-position.md) | 设置局部位置 | +| [`GetLocalRotation`](get-local-rotation.md) | 获取局部旋转 | +| [`SetLocalRotation`](set-local-rotation.md) | 设置局部旋转 | +| [`GetLocalScale`](get-local-scale.md) | 获取局部缩放 | +| [`SetLocalScale`](set-local-scale.md) | 设置局部缩放 | +| [`GetLocalEulerAngles`](get-local-euler-angles.md) | 获取局部欧拉角 | +| [`SetLocalEulerAngles`](set-local-euler-angles.md) | 设置局部欧拉角 | + +### 世界空间 + +| 方法 | 描述 | +|------|------| +| [`GetPosition`](get-position.md) | 获取世界位置 | +| [`SetPosition`](set-position.md) | 设置世界位置 | +| [`GetRotation`](get-rotation.md) | 获取世界旋转 | +| [`SetRotation`](set-rotation.md) | 设置世界旋转 | +| [`GetScale`](get-scale.md) | 获取世界缩放 | +| [`SetScale`](set-scale.md) | 设置世界缩放 | + +### 方向向量 + +| 方法 | 描述 | +|------|------| +| [`GetForward`](get-forward.md) | 获取前方方向 | +| [`GetRight`](get-right.md) | 获取右方方向 | +| [`GetUp`](get-up.md) | 获取上方方向 | + +### 矩阵运算 + +| 方法 | 描述 | +|------|------| +| [`GetLocalToWorldMatrix`](get-local-to-world-matrix.md) | 获取局部到世界矩阵 | +| [`GetWorldToLocalMatrix`](get-world-to-local-matrix.md) | 获取世界到局部矩阵 | + +### 层级结构 + +| 方法 | 描述 | +|------|------| +| [`GetParent`](get-parent.md) | 获取父变换 | +| [`SetParent`](set-parent.md) | 设置父变换 | +| [`GetChildCount`](get-child-count.md) | 获取子对象数量 | +| [`GetChild`](get-child.md) | 获取指定索引的子变换 | +| [`Find`](find.md) | 按名称查找子变换 | +| [`DetachChildren`](detach-children.md) | 分离所有子变换 | + +### 同级顺序 + +| 方法 | 描述 | +|------|------| +| [`GetSiblingIndex`](get-sibling-index.md) | 获取同级索引 | +| [`SetSiblingIndex`](set-sibling-index.md) | 设置同级索引 | +| [`SetAsFirstSibling`](set-as-first-sibling.md) | 设为第一个同级 | +| [`SetAsLastSibling`](set-as-last-sibling.md) | 设为最后一个同级 | + +### 变换操作 + +| 方法 | 描述 | +|------|------| +| [`LookAt`](look-at.md) | 指向目标 | +| [`Rotate`](rotate.md) | 旋转 | +| [`Translate`](translate.md) | 平移 | + +### 坐标变换 + +| 方法 | 描述 | +|------|------| +| [`TransformPoint`](transform-point.md) | 变换点坐标 | +| [`InverseTransformPoint`](inverse-transform-point.md) | 逆变换点坐标 | +| [`TransformDirection`](transform-direction.md) | 变换方向向量 | +| [`InverseTransformDirection`](inverse-transform-direction.md) | 逆变换方向向量 | + +## 使用示例 + +```cpp +#include + +using namespace XCEngine::Components; + +void TransformExample(TransformComponent* transform) { + transform->SetPosition(Vector3(10, 0, 0)); + transform->SetRotation(Quaternion::FromEuler(0, 90, 0)); + + Vector3 forward = transform->GetForward(); + Vector3 right = transform->GetRight(); + + transform->Translate(Vector3(0, 0, 5), Space::Self); + transform->Rotate(Vector3(0, 45, 0), Space::World); + + Vector3 worldPos = transform->GetPosition(); + Matrix4x4 l2w = transform->GetLocalToWorldMatrix(); +} +``` + +## 相关文档 + +- [Components 模块总览](../components.md) - Components 模块总览 +- [Component](component/component.md) - 组件基类 +- [GameObject](game-object/game-object.md) - 游戏对象 diff --git a/docs/api/components/transform-component/transform-direction.md b/docs/api/components/transform-component/transform-direction.md new file mode 100644 index 00000000..a7751cd5 --- /dev/null +++ b/docs/api/components/transform-component/transform-direction.md @@ -0,0 +1,35 @@ +# TransformDirection + +Transform a direction from local space to world space. + +## Syntax + +```cpp +Math::Vector3 TransformDirection(const Math::Vector3& direction) const; +``` + +## Parameters + +- `direction` - The local space direction to transform. + +## Returns + +Returns the transformed direction in world space. + +## Remarks + +Transforms a direction from local space to world space. Unlike `TransformPoint`, this does not consider translation. Only rotation and scale are applied. + +## See Also + +- [InverseTransformDirection](inverse-transform-direction) +- [TransformPoint](transform-point) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + Math::Vector3 localDir(1.0f, 0.0f, 0.0f); + Math::Vector3 worldDir = transform->TransformDirection(localDir); +} +``` diff --git a/docs/api/components/transform-component/transform-point.md b/docs/api/components/transform-component/transform-point.md new file mode 100644 index 00000000..1f93e5b6 --- /dev/null +++ b/docs/api/components/transform-component/transform-point.md @@ -0,0 +1,35 @@ +# TransformPoint + +Transform a point from local space to world space. + +## Syntax + +```cpp +Math::Vector3 TransformPoint(const Math::Vector3& point) const; +``` + +## Parameters + +- `point` - The local space point to transform. + +## Returns + +Returns the transformed point in world space. + +## Remarks + +Transforms a point from local space to world space using the transform's local-to-world matrix. + +## See Also + +- [InverseTransformPoint](inverse-transform-point) +- [TransformDirection](transform-direction) + +## Examples + +```cpp +void Example(TransformComponent* transform) { + Math::Vector3 localPoint(1.0f, 0.0f, 0.0f); + Math::Vector3 worldPoint = transform->TransformPoint(localPoint); +} +``` diff --git a/docs/api/components/transform-component/translate.md b/docs/api/components/transform-component/translate.md new file mode 100644 index 00000000..f0d15dc2 --- /dev/null +++ b/docs/api/components/transform-component/translate.md @@ -0,0 +1,26 @@ +# Translate + +Move the transform by the specified translation. + +## Syntax + +```cpp +void Translate(const Math::Vector3& translation, Space relativeTo = Space::Self); +``` + +## Parameters + +- `translation` - The translation vector. +- `relativeTo` - Whether the translation is relative to self or world space. + +## Remarks + +Moves the transform by the specified amount. When `relativeTo` is `Space::Self`, the translation is applied in local space. When `Space::World`, the translation is applied in world space. + +## Examples + +```cpp +void Example(TransformComponent* transform) { + transform->Translate(Math::Vector3(0.0f, 0.0f, 10.0f), Space::Self); +} +``` diff --git a/docs/api/main.md b/docs/api/main.md index 6dd12fe0..46bb6257 100644 --- a/docs/api/main.md +++ b/docs/api/main.md @@ -20,6 +20,7 @@ | **Resources** | [resources/](resources/resources.md) | 资源管理系统 | | **Audio** | [audio/](audio/audio.md) | 音频系统 | | **Components** | [components/](components/components.md) | ECS 组件系统 | +| **Scene** | [scene/](scene/scene.md) | 场景管理系统 | --- @@ -86,7 +87,10 @@ Math::Matrix4 transform = Math::Matrix4::TRS(position, rotation, scale); | Debug | 9 | | Core | 6 | | Containers | 4 | -| **总计** | **124** | +| Audio | 10 | +| Components | 36 | +| Scene | 19 | +| **总计** | **143** | --- diff --git a/docs/api/scene/scene-manager/create-scene.md b/docs/api/scene/scene-manager/create-scene.md new file mode 100644 index 00000000..e9f5be01 --- /dev/null +++ b/docs/api/scene/scene-manager/create-scene.md @@ -0,0 +1,31 @@ +# CreateScene + +Create a new scene with the specified name. + +## Syntax + +```cpp +Scene* CreateScene(const std::string& name); +``` + +## Parameters + +- `name` - The name for the new scene. + +## Returns + +Returns a pointer to the newly created `Scene`. + +## See Also + +- [LoadScene](load-scene) +- [UnloadScene](unload-scene) + +## Examples + +```cpp +void Example() { + SceneManager& manager = SceneManager::Get(); + Scene* newScene = manager.CreateScene("Level1"); +} +``` diff --git a/docs/api/scene/scene-manager/get-active-scene.md b/docs/api/scene/scene-manager/get-active-scene.md new file mode 100644 index 00000000..a01e1040 --- /dev/null +++ b/docs/api/scene/scene-manager/get-active-scene.md @@ -0,0 +1,29 @@ +# GetActiveScene + +Get the currently active scene. + +## Syntax + +```cpp +Scene* GetActiveScene() const; +``` + +## Returns + +Returns a pointer to the currently active `Scene`, or `nullptr` if no scene is active. + +## See Also + +- [SetActiveScene](set-active-scene) + +## Examples + +```cpp +void Example() { + SceneManager& manager = SceneManager::Get(); + Scene* active = manager.GetActiveScene(); + if (active) { + XC_LOG_INFO("Active scene: {}", active->GetName()); + } +} +``` diff --git a/docs/api/scene/scene-manager/get-all-scenes.md b/docs/api/scene/scene-manager/get-all-scenes.md new file mode 100644 index 00000000..4bbf4a32 --- /dev/null +++ b/docs/api/scene/scene-manager/get-all-scenes.md @@ -0,0 +1,28 @@ +# GetAllScenes + +Get all loaded scenes. + +## Syntax + +```cpp +std::vector GetAllScenes() const; +``` + +## Returns + +Returns a `std::vector` containing pointers to all loaded scenes. + +## See Also + +- [GetScene](get-scene) + +## Examples + +```cpp +void Example() { + SceneManager& manager = SceneManager::Get(); + for (Scene* scene : manager.GetAllScenes()) { + XC_LOG_INFO("Scene: {}", scene->GetName()); + } +} +``` diff --git a/docs/api/scene/scene-manager/get-scene.md b/docs/api/scene/scene-manager/get-scene.md new file mode 100644 index 00000000..bf7bd398 --- /dev/null +++ b/docs/api/scene/scene-manager/get-scene.md @@ -0,0 +1,33 @@ +# GetScene + +Get a scene by name. + +## Syntax + +```cpp +Scene* GetScene(const std::string& name) const; +``` + +## Parameters + +- `name` - The name of the scene. + +## Returns + +Returns a pointer to the scene with the specified name, or `nullptr` if not found. + +## See Also + +- [GetAllScenes](get-all-scenes) + +## Examples + +```cpp +void Example() { + SceneManager& manager = SceneManager::Get(); + Scene* scene = manager.GetScene("Level1"); + if (scene) { + XC_LOG_INFO("Found scene: {}", scene->GetName()); + } +} +``` diff --git a/docs/api/scene/scene-manager/get.md b/docs/api/scene/scene-manager/get.md new file mode 100644 index 00000000..69d09a21 --- /dev/null +++ b/docs/api/scene/scene-manager/get.md @@ -0,0 +1,25 @@ +# Get + +Get the singleton SceneManager instance. + +## Syntax + +```cpp +static SceneManager& Get(); +``` + +## Returns + +Returns a reference to the singleton `SceneManager` instance. + +## Remarks + +Access the SceneManager singleton through this static method. The SceneManager is created on first access. + +## Examples + +```cpp +void Example() { + SceneManager& manager = SceneManager::Get(); +} +``` diff --git a/docs/api/scene/scene-manager/load-scene-async.md b/docs/api/scene/scene-manager/load-scene-async.md new file mode 100644 index 00000000..28deff8f --- /dev/null +++ b/docs/api/scene/scene-manager/load-scene-async.md @@ -0,0 +1,34 @@ +# LoadSceneAsync + +Load a scene from a file asynchronously. + +## Syntax + +```cpp +void LoadSceneAsync(const std::string& filePath, std::function callback); +``` + +## Parameters + +- `filePath` - The path to the scene file. +- `callback` - Callback function called when loading is complete, receives the loaded Scene. + +## Remarks + +Loads a scene from the specified file path asynchronously. The callback is invoked when loading is complete with a pointer to the loaded scene. + +## See Also + +- [LoadScene](load-scene) + +## Examples + +```cpp +void Example() { + SceneManager& manager = SceneManager::Get(); + manager.LoadSceneAsync("assets/scenes/level1.scene", [](Scene* scene) { + XC_LOG_INFO("Scene loaded: {}", scene->GetName()); + manager.SetActiveScene(scene); + }); +} +``` diff --git a/docs/api/scene/scene-manager/load-scene.md b/docs/api/scene/scene-manager/load-scene.md new file mode 100644 index 00000000..878476aa --- /dev/null +++ b/docs/api/scene/scene-manager/load-scene.md @@ -0,0 +1,31 @@ +# LoadScene + +Load a scene from a file synchronously. + +## Syntax + +```cpp +void LoadScene(const std::string& filePath); +``` + +## Parameters + +- `filePath` - The path to the scene file. + +## Remarks + +Loads a scene from the specified file path. This is a synchronous operation and will block until the scene is fully loaded. + +## See Also + +- [LoadSceneAsync](load-scene-async) +- [CreateScene](create-scene) + +## Examples + +```cpp +void Example() { + SceneManager& manager = SceneManager::Get(); + manager.LoadScene("assets/scenes/level1.scene"); +} +``` diff --git a/docs/api/scene/scene-manager/on-active-scene-changed.md b/docs/api/scene/scene-manager/on-active-scene-changed.md new file mode 100644 index 00000000..a709256f --- /dev/null +++ b/docs/api/scene/scene-manager/on-active-scene-changed.md @@ -0,0 +1,33 @@ +# OnActiveSceneChanged + +Event triggered when the active scene changes. + +## Syntax + +```cpp +Core::Event& OnActiveSceneChanged(); +``` + +## Returns + +Returns a reference to the `Core::Event` for this event. + +## Remarks + +Subscribe to this event to be notified when the active scene changes. + +## See Also + +- [SetActiveScene](set-active-scene) +- [GetActiveScene](get-active-scene) + +## Examples + +```cpp +void Example() { + SceneManager& manager = SceneManager::Get(); + manager.OnActiveSceneChanged().AddCallback([](Scene* scene) { + XC_LOG_INFO("Active scene changed: {}", scene->GetName()); + }); +} +``` diff --git a/docs/api/scene/scene-manager/on-scene-loaded.md b/docs/api/scene/scene-manager/on-scene-loaded.md new file mode 100644 index 00000000..1ecf5343 --- /dev/null +++ b/docs/api/scene/scene-manager/on-scene-loaded.md @@ -0,0 +1,33 @@ +# OnSceneLoaded + +Event triggered when a scene is loaded. + +## Syntax + +```cpp +Core::Event& OnSceneLoaded(); +``` + +## Returns + +Returns a reference to the `Core::Event` for this event. + +## Remarks + +Subscribe to this event to be notified when a scene is loaded. + +## See Also + +- [OnSceneUnloaded](on-scene-unloaded) +- [OnActiveSceneChanged](on-active-scene-changed) + +## Examples + +```cpp +void Example() { + SceneManager& manager = SceneManager::Get(); + manager.OnSceneLoaded().AddCallback([](Scene* scene) { + XC_LOG_INFO("Scene loaded: {}", scene->GetName()); + }); +} +``` diff --git a/docs/api/scene/scene-manager/on-scene-unloaded.md b/docs/api/scene/scene-manager/on-scene-unloaded.md new file mode 100644 index 00000000..80526095 --- /dev/null +++ b/docs/api/scene/scene-manager/on-scene-unloaded.md @@ -0,0 +1,33 @@ +# OnSceneUnloaded + +Event triggered when a scene is unloaded. + +## Syntax + +```cpp +Core::Event& OnSceneUnloaded(); +``` + +## Returns + +Returns a reference to the `Core::Event` for this event. + +## Remarks + +Subscribe to this event to be notified when a scene is unloaded. + +## See Also + +- [OnSceneLoaded](on-scene-loaded) +- [OnActiveSceneChanged](on-active-scene-changed) + +## Examples + +```cpp +void Example() { + SceneManager& manager = SceneManager::Get(); + manager.OnSceneUnloaded().AddCallback([](Scene* scene) { + XC_LOG_INFO("Scene unloaded: {}", scene->GetName()); + }); +} +``` diff --git a/docs/api/scene/scene-manager/scene-manager.md b/docs/api/scene/scene-manager/scene-manager.md new file mode 100644 index 00000000..5692ffda --- /dev/null +++ b/docs/api/scene/scene-manager/scene-manager.md @@ -0,0 +1,74 @@ +# SceneManager + +**命名空间**: `XCEngine::Components` + +**类型**: `class (singleton)` + +**头文件**: `XCEngine/Scene/SceneManager.h` + +**描述**: 场景管理器单例，管理所有场景和活动场景。 + +## 概述 + +SceneManager 是 XCEngine 中的场景管理器单例，负责管理所有加载的场景、场景切换（同步/异步）、设置活动场景，以及发布场景加载/卸载事件。它是场景系统的入口点，提供场景创建、加载、卸载和切换的接口。 + +## 单例访问 + +| 方法 | 描述 | +|------|------| +| `static SceneManager& Get()` | 获取场景管理器单例实例 | + +## 公共方法 + +### 场景管理 + +| 方法 | 描述 | +|------|------| +| [`CreateScene`](create-scene.md) | 创建新场景 | +| [`LoadScene`](load-scene.md) | 同步加载场景 | +| [`LoadSceneAsync`](load-scene-async.md) | 异步加载场景 | +| [`UnloadScene`](unload-scene.md) | 卸载场景 | + +### 活动场景 + +| 方法 | 描述 | +|------|------| +| [`SetActiveScene`](set-active-scene.md) | 设置活动场景 | +| [`GetActiveScene`](get-active-scene.md) | 获取当前活动场景 | + +### 查找 + +| 方法 | 描述 | +|------|------| +| [`GetScene`](get-scene.md) | 按名称获取场景 | +| [`GetAllScenes`](get-all-scenes.md) | 获取所有场景 | + +### 事件 + +| 方法 | 描述 | +|------|------| +| [`OnSceneLoaded`](on-scene-loaded.md) | 场景加载完成事件 | +| [`OnSceneUnloaded`](on-scene-unloaded.md) | 场景卸载完成事件 | +| [`OnActiveSceneChanged`](on-active-scene-changed.md) | 活动场景变更事件 | + +## 使用示例 + +```cpp +#include + +using namespace XCEngine::Components; + +void SceneManagerExample() { + Scene* scene = SceneManager::Get().CreateScene("GameLevel"); + SceneManager::Get().SetActiveScene(scene); + + SceneManager::Get().LoadSceneAsync("levels/menu.json", [](Scene* loadedScene) { + printf("Scene loaded: %s\n", loadedScene->GetName().c_str()); + }); +} +``` + +## 相关文档 + +- [Scene 模块总览](../scene.md) - Scene 模块总览 +- [Scene](scene/scene.md) - 场景类 diff --git a/docs/api/scene/scene-manager/set-active-scene.md b/docs/api/scene/scene-manager/set-active-scene.md new file mode 100644 index 00000000..5d75ff4a --- /dev/null +++ b/docs/api/scene/scene-manager/set-active-scene.md @@ -0,0 +1,32 @@ +# SetActiveScene + +Set the currently active scene. + +## Syntax + +```cpp +void SetActiveScene(Scene* scene); +void SetActiveScene(const std::string& sceneName); +``` + +## Parameters + +- `scene` - Pointer to the scene to set as active. +- `sceneName` - Name of the scene to set as active. + +## Remarks + +Sets which scene is currently active. The active scene is the one that receives updates. + +## See Also + +- [GetActiveScene](get-active-scene) + +## Examples + +```cpp +void Example() { + SceneManager& manager = SceneManager::Get(); + manager.SetActiveScene("Level1"); +} +``` diff --git a/docs/api/scene/scene-manager/unload-scene.md b/docs/api/scene/scene-manager/unload-scene.md new file mode 100644 index 00000000..88d125c2 --- /dev/null +++ b/docs/api/scene/scene-manager/unload-scene.md @@ -0,0 +1,33 @@ +# UnloadScene + +Unload a scene. + +## Syntax + +```cpp +void UnloadScene(Scene* scene); +void UnloadScene(const std::string& sceneName); +``` + +## Parameters + +- `scene` - Pointer to the scene to unload. +- `sceneName` - Name of the scene to unload. + +## Remarks + +Removes a scene from the SceneManager. The scene and all its GameObjects will be destroyed. + +## See Also + +- [CreateScene](create-scene) +- [LoadScene](load-scene) + +## Examples + +```cpp +void Example() { + SceneManager& manager = SceneManager::Get(); + manager.UnloadScene("Level1"); +} +``` diff --git a/docs/api/scene/scene.md b/docs/api/scene/scene.md new file mode 100644 index 00000000..850f2c1a --- /dev/null +++ b/docs/api/scene/scene.md @@ -0,0 +1,46 @@ +# Scene 模块概览 + +**命名空间**: `XCEngine::Components` + +**类型**: `module` + +**描述**: XCEngine 的场景管理模块，提供场景创建、加载和 GameObject 管理功能。 + +## 概述 + +Scene 模块是 XCEngine 中管理游戏场景的核心模块。它提供了 Scene 类用于管理场景中的所有 GameObject，以及 SceneManager 单例用于管理多个场景、场景切换和生命周期。场景是 GameObject 的容器，支持场景保存/加载、子对象查找、事件通知等功能。 + +## 模块内容 + +### 核心类 + +| 组件 | 文件 | 描述 | +|------|------|------| +| [Scene](scene/scene.md) | `Scene.h` | 场景类，管理 GameObject 层级和生命周期 | +| [SceneManager](scene-manager/scene-manager.md) | `SceneManager.h` | 场景管理器单例，管理所有场景 | + +## 使用示例 + +```cpp +#include +#include +#include + +using namespace XCEngine::Components; + +void CreateNewScene() { + Scene* scene = SceneManager::Get().CreateScene("MainMenu"); + SceneManager::Get().SetActiveScene(scene); + + GameObject* camera = scene->CreateGameObject("MainCamera"); +} + +void LoadSceneExample() { + SceneManager::Get().LoadScene("levels/gameplay.json"); +} +``` + +## 相关文档 + +- [Components 模块](../components/components.md) - Components 模块总览 +- [GameObject](../components/game-object/game-object.md) - 游戏对象 diff --git a/docs/api/scene/scene/create-game-object.md b/docs/api/scene/scene/create-game-object.md new file mode 100644 index 00000000..037d7989 --- /dev/null +++ b/docs/api/scene/scene/create-game-object.md @@ -0,0 +1,35 @@ +# CreateGameObject + +Create a new GameObject in this scene. + +## Syntax + +```cpp +GameObject* CreateGameObject(const std::string& name, GameObject* parent = nullptr); +``` + +## Parameters + +- `name` - The name of the new GameObject. +- `parent` - Optional parent GameObject (defaults to `nullptr`). + +## Returns + +Returns a pointer to the newly created `GameObject`. + +## Remarks + +Creates a new GameObject with the specified name and optionally sets its parent. The GameObject is owned by the scene and will be destroyed when the scene is destroyed. + +## See Also + +- [DestroyGameObject](destroy-game-object) + +## Examples + +```cpp +void Example(Scene* scene) { + GameObject* player = scene->CreateGameObject("Player"); + GameObject* weapon = scene->CreateGameObject("Sword", player); +} +``` diff --git a/docs/api/scene/scene/destroy-game-object.md b/docs/api/scene/scene/destroy-game-object.md new file mode 100644 index 00000000..94901c62 --- /dev/null +++ b/docs/api/scene/scene/destroy-game-object.md @@ -0,0 +1,29 @@ +# DestroyGameObject + +Destroy a GameObject in this scene. + +## Syntax + +```cpp +void DestroyGameObject(GameObject* gameObject); +``` + +## Parameters + +- `gameObject` - Pointer to the GameObject to destroy. + +## Remarks + +Destroys the specified GameObject and all its components. The GameObject will be destroyed at the end of the current frame. + +## See Also + +- [CreateGameObject](create-game-object) + +## Examples + +```cpp +void Example(Scene* scene, GameObject* enemy) { + scene->DestroyGameObject(enemy); +} +``` diff --git a/docs/api/scene/scene/find-game-object-with-tag.md b/docs/api/scene/scene/find-game-object-with-tag.md new file mode 100644 index 00000000..4685e02c --- /dev/null +++ b/docs/api/scene/scene/find-game-object-with-tag.md @@ -0,0 +1,36 @@ +# FindGameObjectWithTag + +Find the first GameObject with the specified tag. + +## Syntax + +```cpp +GameObject* FindGameObjectWithTag(const std::string& tag) const; +``` + +## Parameters + +- `tag` - The tag to search for. + +## Returns + +Returns a pointer to the first GameObject with the specified tag, or `nullptr` if not found. + +## Remarks + +Searches the scene for a GameObject with the specified tag. Tags must be set on individual GameObjects. + +## See Also + +- [Find](find) + +## Examples + +```cpp +void Example(Scene* scene) { + GameObject* enemy = scene->FindGameObjectWithTag("Enemy"); + if (enemy) { + XC_LOG_INFO("Found enemy!"); + } +} +``` diff --git a/docs/api/scene/scene/find.md b/docs/api/scene/scene/find.md new file mode 100644 index 00000000..4f6335fb --- /dev/null +++ b/docs/api/scene/scene/find.md @@ -0,0 +1,36 @@ +# Find + +Find a GameObject by name. + +## Syntax + +```cpp +GameObject* Find(const std::string& name) const; +``` + +## Parameters + +- `name` - The name of the GameObject to find. + +## Returns + +Returns a pointer to the GameObject with the specified name, or `nullptr` if not found. + +## Remarks + +Searches the scene for a GameObject with the specified name. The search includes all root GameObjects and their children. + +## See Also + +- [FindGameObjectWithTag](find-game-object-with-tag) + +## Examples + +```cpp +void Example(Scene* scene) { + GameObject* player = scene->Find("Player"); + if (player) { + XC_LOG_INFO("Found player!"); + } +} +``` diff --git a/docs/api/scene/scene/fixed-update.md b/docs/api/scene/scene/fixed-update.md new file mode 100644 index 00000000..ea6a0c2d --- /dev/null +++ b/docs/api/scene/scene/fixed-update.md @@ -0,0 +1,30 @@ +# FixedUpdate + +Perform fixed update on all GameObjects in this scene. + +## Syntax + +```cpp +void FixedUpdate(float fixedDeltaTime); +``` + +## Parameters + +- `fixedDeltaTime` - The fixed time step in seconds. + +## Remarks + +Calls `FixedUpdate` on all GameObjects and their components. This is typically called at a fixed time interval for physics updates. + +## See Also + +- [Update](update) +- [LateUpdate](late-update) + +## Examples + +```cpp +void Example(Scene* scene) { + scene->FixedUpdate(0.02f); +} +``` diff --git a/docs/api/scene/scene/get-name.md b/docs/api/scene/scene/get-name.md new file mode 100644 index 00000000..4b982fba --- /dev/null +++ b/docs/api/scene/scene/get-name.md @@ -0,0 +1,26 @@ +# GetName + +Get the name of this scene. + +## Syntax + +```cpp +const std::string& GetName() const; +``` + +## Returns + +Returns the scene name as a `std::string` reference. + +## See Also + +- [SetName](set-name) + +## Examples + +```cpp +void Example(Scene* scene) { + const std::string& name = scene->GetName(); + XC_LOG_INFO("Scene name: {}", name); +} +``` diff --git a/docs/api/scene/scene/get-root-game-objects.md b/docs/api/scene/scene/get-root-game-objects.md new file mode 100644 index 00000000..307ebce4 --- /dev/null +++ b/docs/api/scene/scene/get-root-game-objects.md @@ -0,0 +1,27 @@ +# GetRootGameObjects + +Get all root-level GameObjects in this scene. + +## Syntax + +```cpp +std::vector GetRootGameObjects() const; +``` + +## Returns + +Returns a `std::vector` containing pointers to all root-level GameObjects. + +## Remarks + +Root-level GameObjects are those without a parent within the scene hierarchy. + +## Examples + +```cpp +void Example(Scene* scene) { + for (GameObject* go : scene->GetRootGameObjects()) { + XC_LOG_INFO("Root object: {}", go->GetName()); + } +} +``` diff --git a/docs/api/scene/scene/is-active.md b/docs/api/scene/scene/is-active.md new file mode 100644 index 00000000..08ecf734 --- /dev/null +++ b/docs/api/scene/scene/is-active.md @@ -0,0 +1,27 @@ +# IsActive + +Check if this scene is active. + +## Syntax + +```cpp +bool IsActive() const; +``` + +## Returns + +Returns `true` if the scene is active, `false` otherwise. + +## See Also + +- [SetActive](set-active) + +## Examples + +```cpp +void Example(Scene* scene) { + if (scene->IsActive()) { + XC_LOG_INFO("Scene is active"); + } +} +``` diff --git a/docs/api/scene/scene/late-update.md b/docs/api/scene/scene/late-update.md new file mode 100644 index 00000000..8b841498 --- /dev/null +++ b/docs/api/scene/scene/late-update.md @@ -0,0 +1,30 @@ +# LateUpdate + +Perform late update on all GameObjects in this scene. + +## Syntax + +```cpp +void LateUpdate(float deltaTime); +``` + +## Parameters + +- `deltaTime` - The time elapsed since the last frame in seconds. + +## Remarks + +Calls `LateUpdate` on all GameObjects and their components. This is typically called after `Update` for operations that need to run after other updates. + +## See Also + +- [Update](update) +- [FixedUpdate](fixed-update) + +## Examples + +```cpp +void Example(Scene* scene) { + scene->LateUpdate(0.016f); +} +``` diff --git a/docs/api/scene/scene/load.md b/docs/api/scene/scene/load.md new file mode 100644 index 00000000..f6113000 --- /dev/null +++ b/docs/api/scene/scene/load.md @@ -0,0 +1,29 @@ +# Load + +Load a scene from a file. + +## Syntax + +```cpp +void Load(const std::string& filePath); +``` + +## Parameters + +- `filePath` - The path to the scene file. + +## Remarks + +Deserializes the scene from the specified file path, replacing the current scene contents. + +## See Also + +- [Save](save) + +## Examples + +```cpp +void Example(Scene* scene) { + scene->Load("assets/scenes/my_scene.scene"); +} +``` diff --git a/docs/api/scene/scene/on-game-object-created.md b/docs/api/scene/scene/on-game-object-created.md new file mode 100644 index 00000000..824d5e1d --- /dev/null +++ b/docs/api/scene/scene/on-game-object-created.md @@ -0,0 +1,31 @@ +# OnGameObjectCreated + +Event triggered when a GameObject is created in this scene. + +## Syntax + +```cpp +Core::Event& OnGameObjectCreated(); +``` + +## Returns + +Returns a reference to the `Core::Event` for this event. + +## Remarks + +Subscribe to this event to be notified when a GameObject is created in the scene. The event passes the newly created GameObject as a parameter. + +## See Also + +- [OnGameObjectDestroyed](on-game-object-destroyed) + +## Examples + +```cpp +void Example(Scene* scene) { + scene->OnGameObjectCreated().AddCallback([](GameObject* go) { + XC_LOG_INFO("GameObject created: {}", go->GetName()); + }); +} +``` diff --git a/docs/api/scene/scene/on-game-object-destroyed.md b/docs/api/scene/scene/on-game-object-destroyed.md new file mode 100644 index 00000000..71eb886d --- /dev/null +++ b/docs/api/scene/scene/on-game-object-destroyed.md @@ -0,0 +1,31 @@ +# OnGameObjectDestroyed + +Event triggered when a GameObject is destroyed in this scene. + +## Syntax + +```cpp +Core::Event& OnGameObjectDestroyed(); +``` + +## Returns + +Returns a reference to the `Core::Event` for this event. + +## Remarks + +Subscribe to this event to be notified when a GameObject is destroyed in the scene. The event passes the destroyed GameObject as a parameter. + +## See Also + +- [OnGameObjectCreated](on-game-object-created) + +## Examples + +```cpp +void Example(Scene* scene) { + scene->OnGameObjectDestroyed().AddCallback([](GameObject* go) { + XC_LOG_INFO("GameObject destroyed: {}", go->GetName()); + }); +} +``` diff --git a/docs/api/scene/scene/save.md b/docs/api/scene/scene/save.md new file mode 100644 index 00000000..822f8e01 --- /dev/null +++ b/docs/api/scene/scene/save.md @@ -0,0 +1,29 @@ +# Save + +Save this scene to a file. + +## Syntax + +```cpp +void Save(const std::string& filePath); +``` + +## Parameters + +- `filePath` - The path to save the scene file. + +## Remarks + +Serializes the scene and all its GameObjects to the specified file path. + +## See Also + +- [Load](load) + +## Examples + +```cpp +void Example(Scene* scene) { + scene->Save("assets/scenes/my_scene.scene"); +} +``` diff --git a/docs/api/scene/scene/scene.md b/docs/api/scene/scene/scene.md new file mode 100644 index 00000000..a2be9074 --- /dev/null +++ b/docs/api/scene/scene/scene.md @@ -0,0 +1,90 @@ +# Scene + +**命名空间**: `XCEngine::Components` + +**类型**: `class` + +**头文件**: `XCEngine/Scene/Scene.h` + +**描述**: 场景类，管理场景中的所有 GameObject 和层级结构。 + +## 概述 + +Scene 是 XCEngine 中的场景类，代表一个独立的游戏空间（如主菜单、游戏关卡、过场动画等）。每个 Scene 包含一个 GameObject 层级树，通过根对象（Root GameObjects）组织。Scene 负责创建和销毁 GameObject，提供查找功能，支持场景保存/加载，并发布 GameObject 创建和销毁事件。 + +## 类型别名 + +| 别名 | 类型 | 描述 | +|------|------|------| +| `GameObjectID` | `uint64_t` | 游戏对象唯一标识符类型 | +| `INVALID_GAMEOBJECT_ID` | `static constexpr GameObjectID` | 无效 ID 常量，值为 0 | + +## 公共方法 + +### 基础信息 + +| 方法 | 描述 | +|------|------| +| [`GetName`](get-name.md) | 获取场景名称 | +| [`SetName`](set-name.md) | 设置场景名称 | +| [`IsActive`](is-active.md) | 检查场景是否激活 | +| [`SetActive`](set-active.md) | 设置场景激活状态 | + +### GameObject 管理 + +| 方法 | 描述 | +|------|------| +| [`CreateGameObject`](create-game-object.md) | 创建游戏对象 | +| [`DestroyGameObject`](destroy-game-object.md) | 销毁游戏对象 | + +### 查找 + +| 方法 | 描述 | +|------|------| +| [`Find`](find.md) | 按名称查找 GameObject | +| [`FindGameObjectWithTag`](find-game-object-with-tag.md) | 按标签查找 GameObject | +| [`FindObjectOfType`](find-object-of-type.md) | 查找指定类型的组件 | +| [`FindObjectsOfType`](find-objects-of-type.md) | 查找所有指定类型的组件 | +| [`GetRootGameObjects`](get-root-game-objects.md) | 获取所有根对象 | + +### 生命周期 + +| 方法 | 描述 | +|------|------| +| [`Update`](update.md) | 每帧更新场景 | +| [`FixedUpdate`](fixed-update.md) | 固定频率更新 | +| [`LateUpdate`](late-update.md) | 晚更新 | +| [`Load`](load.md) | 加载场景 | +| [`Save`](save.md) | 保存场景 | + +### 事件 + +| 方法 | 描述 | +|------|------| +| [`OnGameObjectCreated`](on-game-object-created.md) | GameObject 创建事件 | +| [`OnGameObjectDestroyed`](on-game-object-destroyed.md) | GameObject 销毁事件 | + +## 使用示例 + +```cpp +#include +#include + +using namespace XCEngine::Components; + +void SceneExample(Scene* scene) { + GameObject* player = scene->CreateGameObject("Player"); + GameObject* enemy = scene->CreateGameObject("Enemy"); + + scene->SetActive(true); + + GameObject* found = scene->Find("Player"); + auto cameras = scene->FindObjectsOfType(); +} +``` + +## 相关文档 + +- [Scene 模块总览](../scene.md) - Scene 模块总览 +- [SceneManager](scene-manager/scene-manager.md) - 场景管理器 +- [GameObject](../components/game-object/game-object.md) - 游戏对象 diff --git a/docs/api/scene/scene/set-active.md b/docs/api/scene/scene/set-active.md new file mode 100644 index 00000000..5b4cc7b8 --- /dev/null +++ b/docs/api/scene/scene/set-active.md @@ -0,0 +1,25 @@ +# SetActive + +Set whether this scene is active. + +## Syntax + +```cpp +void SetActive(bool active); +``` + +## Parameters + +- `active` - Whether to activate or deactivate the scene. + +## See Also + +- [IsActive](is-active) + +## Examples + +```cpp +void Example(Scene* scene) { + scene->SetActive(false); +} +``` diff --git a/docs/api/scene/scene/set-name.md b/docs/api/scene/scene/set-name.md new file mode 100644 index 00000000..04ec246a --- /dev/null +++ b/docs/api/scene/scene/set-name.md @@ -0,0 +1,25 @@ +# SetName + +Set the name of this scene. + +## Syntax + +```cpp +void SetName(const std::string& name); +``` + +## Parameters + +- `name` - The new scene name. + +## See Also + +- [GetName](get-name) + +## Examples + +```cpp +void Example(Scene* scene) { + scene->SetName("MainScene"); +} +``` diff --git a/docs/api/scene/scene/update.md b/docs/api/scene/scene/update.md new file mode 100644 index 00000000..333f1803 --- /dev/null +++ b/docs/api/scene/scene/update.md @@ -0,0 +1,25 @@ +# Update + +Update all GameObjects in this scene. + +## Syntax + +```cpp +void Update(float deltaTime); +``` + +## Parameters + +- `deltaTime` - The time elapsed since the last frame in seconds. + +## Remarks + +Calls `Update` on all GameObjects and their components. This is typically called once per frame from the main game loop. + +## Examples + +```cpp +void Example(Scene* scene) { + scene->Update(0.016f); +} +```