From 05a57addc795b9617729b36a9303ecb05034911e Mon Sep 17 00:00:00 2001 From: ssdfasd <2156608475@qq.com> Date: Fri, 20 Mar 2026 19:43:24 +0800 Subject: [PATCH] Docs: Update UI-Editor GameObject system analysis --- docs/plan/UI-Editor-GameObject缺口分析.md | 183 ++++++++++++++++------ 1 file changed, 136 insertions(+), 47 deletions(-) diff --git a/docs/plan/UI-Editor-GameObject缺口分析.md b/docs/plan/UI-Editor-GameObject缺口分析.md index 17d760d9..ef3f8a86 100644 --- a/docs/plan/UI-Editor-GameObject缺口分析.md +++ b/docs/plan/UI-Editor-GameObject缺口分析.md @@ -6,6 +6,34 @@ --- +## 架构参考 + +XCEngine 组件系统参考 **Unity 传统架构 (GameObject-Component Pattern)**： + +- **GameObject**：场景中的实体（UI Editor 中称 `Entity`） +- **Component**：挂载到 GameObject 的功能模块（变换、渲染器等） +- **TransformComponent**：每个 GameObject 都有的变换组件，管理位置/旋转/缩放 +- **Scene/SceneManager**：场景管理和场景切换 + +--- + +## Engine 模块现状 + +| 模块 | 状态 | UI Editor 对齐情况 | +|-----|------|------------------| +| Core (Event, Types) | ✅ 已实现 | UI 编辑器已复用 `XCEngine::Core::Event` | +| Debug (Logger, LogLevel, LogEntry) | ✅ 已实现 | UI 编辑器已复用 `XCEngine::Debug::LogLevel` | +| **Math (Vector3, Quaternion, Matrix4x4, Transform, Color)** | ✅ **已实现** | **可直接复用 Engine Math 类型** | +| Memory | ✅ 已实现 | | +| Threading | ✅ 已实现 | | +| Containers | ✅ 已实现 | | +| RHI / D3D12 | ✅ 已实现 | UI 编辑器自行实现（与 Engine 技术栈一致） | +| Resources | ✅ 已实现 | | +| **Components (GameObject, Component, System)** | ❌ **缺失** | UI 编辑器自行实现，待 Engine 实现后迁移 | +| **Scene (Scene, SceneManager, SceneLoader, SceneSerializer)** | ❌ **缺失** | UI 编辑器自行实现，待 Engine 实现后迁移 | + +--- + ## 一、Component 基类缺口 | 架构设计接口 | 函数签名 | 状态 | 说明 | @@ -30,27 +58,27 @@ | 架构设计接口 | 函数签名 | 状态 | 说明 | |------------|---------|------|------| -| `GetPosition()` | `Vector3 GetPosition() const` | ❌ 缺失 | 获取世界坐标 | -| `SetPosition()` | `void SetPosition(const Vector3& position)` | ❌ 缺失 | 设置世界坐标 | -| `GetRotation()` | `Quaternion GetRotation() const` | ❌ 缺失 | 获取世界旋转 | -| `SetRotation()` | `void SetRotation(const Quaternion& rotation)` | ❌ 缺失 | 设置世界旋转 | -| `GetScale()` | `Vector3 GetScale() const` | ❌ 缺失 | 获取世界缩放 | -| `SetScale()` | `void SetScale(const Vector3& scale)` | ❌ 缺失 | 设置世界缩放 | +| `GetPosition()` | `XCEngine::Math::Vector3 GetPosition() const` | ❌ 缺失 | 获取世界坐标 | +| `SetPosition()` | `void SetPosition(const XCEngine::Math::Vector3& position)` | ❌ 缺失 | 设置世界坐标 | +| `GetRotation()` | `XCEngine::Math::Quaternion GetRotation() const` | ❌ 缺失 | 获取世界旋转 | +| `SetRotation()` | `void SetRotation(const XCEngine::Math::Quaternion& rotation)` | ❌ 缺失 | 设置世界旋转 | +| `GetScale()` | `XCEngine::Math::Vector3 GetScale() const` | ❌ 缺失 | 获取世界缩放 | +| `SetScale()` | `void SetScale(const XCEngine::Math::Vector3& scale)` | ❌ 缺失 | 设置世界缩放 | ### 2.2 方向向量 | 架构设计接口 | 函数签名 | 状态 | 说明 | |------------|---------|------|------| -| `GetForward()` | `Vector3 GetForward() const` | ❌ 缺失 | 获取前向向量 | -| `GetRight()` | `Vector3 GetRight() const` | ❌ 缺失 | 获取右向量 | -| `GetUp()` | `Vector3 GetUp() const` | ❌ 缺失 | 获取上向量 | +| `GetForward()` | `XCEngine::Math::Vector3 GetForward() const` | ❌ 缺失 | 获取前向向量 | +| `GetRight()` | `XCEngine::Math::Vector3 GetRight() const` | ❌ 缺失 | 获取右向量 | +| `GetUp()` | `XCEngine::Math::Vector3 GetUp() const` | ❌ 缺失 | 获取上向量 | ### 2.3 矩阵变换 | 架构设计接口 | 函数签名 | 状态 | 说明 | |------------|---------|------|------| -| `GetLocalToWorldMatrix()` | `const Matrix4x4& GetLocalToWorldMatrix() const` | ❌ 缺失 | 本地到世界矩阵（含缓存） | -| `GetWorldToLocalMatrix()` | `Matrix4x4 GetWorldToLocalMatrix() const` | ❌ 缺失 | 世界到本地矩阵 | +| `GetLocalToWorldMatrix()` | `const XCEngine::Math::Matrix4x4& GetLocalToWorldMatrix() const` | ❌ 缺失 | 本地到世界矩阵（含缓存） | +| `GetWorldToLocalMatrix()` | `XCEngine::Math::Matrix4x4 GetWorldToLocalMatrix() const` | ❌ 缺失 | 世界到本地矩阵 | ### 2.4 父子层级 @@ -70,28 +98,28 @@ | 架构设计接口 | 函数签名 | 状态 | 说明 | |------------|---------|------|------| -| `LookAt(target)` | `void LookAt(const Vector3& target)` | ❌ 缺失 | 朝向目标点 | -| `LookAt(target, up)` | `void LookAt(const Vector3& target, const Vector3& up)` | ❌ 缺失 | 朝向目标点（指定上向量） | -| `Rotate(eulers)` | `void Rotate(const Vector3& eulers)` | ❌ 缺失 | 欧拉角旋转 | -| `Rotate(axis, angle)` | `void Rotate(const Vector3& axis, float angle)` | ❌ 缺失 | 轴角旋转 | -| `Translate(translation)` | `void Translate(const Vector3& translation)` | ❌ 缺失 | 平移（世界空间） | -| `Translate(translation, relativeTo)` | `void Translate(const Vector3& translation, Space relativeTo)` | ❌ 缺失 | 平移（指定空间） | +| `LookAt(target)` | `void LookAt(const XCEngine::Math::Vector3& target)` | ❌ 缺失 | 朝向目标点 | +| `LookAt(target, up)` | `void LookAt(const XCEngine::Math::Vector3& target, const XCEngine::Math::Vector3& up)` | ❌ 缺失 | 朝向目标点（指定上向量） | +| `Rotate(eulers)` | `void Rotate(const XCEngine::Math::Vector3& eulers)` | ❌ 缺失 | 欧拉角旋转 | +| `Rotate(axis, angle)` | `void Rotate(const XCEngine::Math::Vector3& axis, float angle)` | ❌ 缺失 | 轴角旋转 | +| `Translate(translation)` | `void Translate(const XCEngine::Math::Vector3& translation)` | ❌ 缺失 | 平移（世界空间） | +| `Translate(translation, relativeTo)` | `void Translate(const XCEngine::Math::Vector3& translation, Space relativeTo)` | ❌ 缺失 | 平移（指定空间） | ### 2.6 点/方向变换 | 架构设计接口 | 函数签名 | 状态 | 说明 | |------------|---------|------|------| -| `TransformPoint()` | `Vector3 TransformPoint(const Vector3& point) const` | ❌ 缺失 | 变换点（含平移旋转） | -| `InverseTransformPoint()` | `Vector3 InverseTransformPoint(const Vector3& point) const` | ❌ 缺失 | 逆变换点 | -| `TransformDirection()` | `Vector3 TransformDirection(const Vector3& direction) const` | ❌ 缺失 | 变换方向（仅旋转） | -| `InverseTransformDirection()` | `Vector3 InverseTransformDirection(const Vector3& direction) const` | ❌ 缺失 | 逆变换方向 | +| `TransformPoint()` | `XCEngine::Math::Vector3 TransformPoint(const XCEngine::Math::Vector3& point) const` | ❌ 缺失 | 变换点（含平移旋转） | +| `InverseTransformPoint()` | `XCEngine::Math::Vector3 InverseTransformPoint(const XCEngine::Math::Vector3& point) const` | ❌ 缺失 | 逆变换点 | +| `TransformDirection()` | `XCEngine::Math::Vector3 TransformDirection(const XCEngine::Math::Vector3& direction) const` | ❌ 缺失 | 变换方向（仅旋转） | +| `InverseTransformDirection()` | `XCEngine::Math::Vector3 InverseTransformDirection(const XCEngine::Math::Vector3& direction) const` | ❌ 缺失 | 逆变换方向 | ### 2.7 脏标记与缓存 | 架构设计接口 | 函数签名 | 状态 | 说明 | |------------|---------|------|------| | `SetDirty()` | `void SetDirty()` | ⚠️ 局部 | UI Editor 只有简单 flag，缺少完整缓存机制 | -| 缓存成员 | `mutable Matrix4x4 m_localToWorldMatrix` 等 | ❌ 缺失 | 矩阵缓存 | +| 缓存成员 | `mutable XCEngine::Math::Matrix4x4 m_localToWorldMatrix` 等 | ❌ 缺失 | 矩阵缓存 | | 更新方法 | `void UpdateWorldTransform() const` | ❌ 缺失 | 缓存失效时重新计算 | **当前 UI Editor 实现**： @@ -105,22 +133,33 @@ public: }; ``` -**架构设计要求**： +**架构设计要求**（应使用 Engine Math 类型）： ```cpp class TransformComponent : public Component { +public: + // 使用 Engine Math 类型 + XCEngine::Math::Vector3 GetLocalPosition() const { return m_localPosition; } + void SetLocalPosition(const XCEngine::Math::Vector3& pos) { m_localPosition = pos; SetDirty(); } + + XCEngine::Math::Quaternion GetLocalRotation() const { return m_localRotation; } + void SetLocalRotation(const XCEngine::Math::Quaternion& rot) { m_localRotation = rot; SetDirty(); } + + XCEngine::Math::Vector3 GetLocalScale() const { return m_localScale; } + void SetLocalScale(const XCEngine::Math::Vector3& sc) { m_localScale = sc; SetDirty(); } + private: - Vector3 m_localPosition = Vector3::Zero(); - Quaternion m_localRotation = Quaternion::Identity(); - Vector3 m_localScale = Vector3::One(); + XCEngine::Math::Vector3 m_localPosition = XCEngine::Math::Vector3::Zero(); + XCEngine::Math::Quaternion m_localRotation = XCEngine::Math::Quaternion::Identity(); + XCEngine::Math::Vector3 m_localScale = XCEngine::Math::Vector3::One(); TransformComponent* m_parent = nullptr; std::vector m_children; - mutable Matrix4x4 m_localToWorldMatrix; - mutable Matrix4x4 m_worldToLocalMatrix; - mutable Vector3 m_worldPosition; - mutable Quaternion m_worldRotation; - mutable Vector3 m_worldScale; + mutable XCEngine::Math::Matrix4x4 m_localToWorldMatrix; + mutable XCEngine::Math::Matrix4x4 m_worldToLocalMatrix; + mutable XCEngine::Math::Vector3 m_worldPosition; + mutable XCEngine::Math::Quaternion m_worldRotation; + mutable XCEngine::Math::Vector3 m_worldScale; mutable bool m_dirty = true; void UpdateWorldTransform() const; @@ -129,7 +168,7 @@ private: --- -## 三、Entity（GameObject）缺口 +## 三、GameObject缺口 ### 3.1 基础方法 @@ -150,9 +189,9 @@ private: | 架构设计接口 | 函数签名 | 状态 | 说明 | |------------|---------|------|------| -| `SetParent(parent)` | `void SetParent(GameObject* parent)` | ❌ 缺失 | 2参数版本（含 worldPositionStays） | -| `GetChildren()` | `const std::vector& GetChildren() const` | ❌ 缺失 | 获取子实体列表 | -| `GetChild()` | `GameObject* GetChild(int index) const` | ❌ 缺失 | 按索引获取子实体 | +| `SetParent(parent)` | `void SetParent(Entity* parent)` | ❌ 缺失 | 2参数版本（含 worldPositionStays） | +| `GetChildren()` | `const std::vector& GetChildren() const` | ❌ 缺失 | 获取子实体列表 | +| `GetChild()` | `Entity* GetChild(int index) const` | ❌ 缺失 | 按索引获取子实体 | ### 3.4 激活状态 @@ -167,9 +206,9 @@ private: | 架构设计接口 | 函数签名 | 状态 | 说明 | |------------|---------|------|------| -| `Find()` | `static GameObject* Find(const String& name)` | ❌ 缺失 | 按名称查找实体 | -| `FindObjectsOfType()` | `static std::vector FindObjectsOfType()` | ❌ 缺失 | 查找所有实体 | -| `FindGameObjectsWithTag()` | `static std::vector FindGameObjectsWithTag(const String& tag)` | ❌ 缺失 | 按标签查找 | +| `Find()` | `static Entity* Find(const String& name)` | ❌ 缺失 | 按名称查找实体 | +| `FindObjectsOfType()` | `static std::vector FindObjectsOfType()` | ❌ 缺失 | 查找所有实体 | +| `FindGameObjectsWithTag()` | `static std::vector FindGameObjectsWithTag(const String& tag)` | ❌ 缺失 | 按标签查找 | ### 3.6 销毁 @@ -187,10 +226,10 @@ private: |------------|---------|------|------| | `GetName()` | `const String& GetName() const` | ❌ 缺失 | 获取场景名称 | | `SetName()` | `void SetName(const String& name)` | ❌ 缺失 | 设置场景名称 | -| `CreateGameObject(name, parent)` | `GameObject* CreateGameObject(const String& name, GameObject* parent)` | ❌ 缺失 | 带父实体创建 | -| `GetRootGameObjects()` | `std::vector GetRootGameObjects() const` | ❌ 缺失 | 获取根实体列表 | -| `Find()` | `GameObject* Find(const String& name) const` | ❌ 缺失 | 查找实体 | -| `FindGameObjectWithTag()` | `GameObject* FindGameObjectWithTag(const String& tag) const` | ❌ 缺失 | 按标签查找 | +| `CreateGameObject(name, parent)` | `Entity* CreateGameObject(const String& name, Entity* parent)` | ❌ 缺失 | 带父实体创建 | +| `GetRootGameObjects()` | `std::vector GetRootGameObjects() const` | ❌ 缺失 | 获取根实体列表 | +| `Find()` | `Entity* Find(const String& name) const` | ❌ 缺失 | 查找实体 | +| `FindGameObjectWithTag()` | `Entity* FindGameObjectWithTag(const String& tag) const` | ❌ 缺失 | 按标签查找 | | `FindObjectsOfType()` | `std::vector FindObjectsOfType() const` | ❌ 缺失 | 模板查找 | | `FindObjectOfType()` | `T* FindObjectOfType() const` | ❌ 缺失 | 查找单个 | | `IsActive()` | `bool IsActive() const` | ❌ 缺失 | 场景激活状态 | @@ -239,6 +278,8 @@ private: | Entity `GetTransform()` | Inspector 面板需要 | GameObject.h | | Component `transform()` | 组件访问变换 | GameObject.h | +**依赖**：Engine Math 模块 ✅ 已实现，可直接使用 `XCEngine::Math::Vector3` / `Quaternion` / `Matrix4x4`。 + ### P1 - 功能完整（应该实现） | 模块 | 原因 | 涉及文件 | @@ -268,8 +309,8 @@ private: | 项目 | UI Editor 当前 | 架构设计 | 对齐建议 | |-----|--------------|---------|---------| | 实体内组件存储 | `vector>` | `vector>` | ✅ 已对齐 | -| 变换存储 | `float[3]` 数组 | `Vector3` / `Quaternion` | ⚠️ UI Editor 自行实现，接口对齐即可 | -| 父子关系 | `EntityID` (uint64) | `GameObject*` 指针 | ⚠️ UI 用 ID，Engine 用指针 | +| 变换类型 | `float[3]` 数组 | `XCEngine::Math::Vector3` / `Quaternion` | ⚠️ **应改用 Engine Math** | +| 父子关系 | `EntityID` (uint64) | `Entity*` 指针 | ⚠️ UI 用 ID，Engine 用指针 | | 场景管理 | 全局单例 SceneManager | 多 Scene + SceneManager | ❌ 需要重构 | ### 6.2 命名差异 @@ -281,6 +322,16 @@ private: | `INVALID_ENTITY_ID` | N/A | UI Editor 自定义常量 | | `ComponentRegistry` | `ComponentTypeRegistry` | 功能相似，命名不同 | +### 6.3 类型复用情况 + +| Engine 类型 | UI Editor 现状 | 建议 | +|-----------|--------------|------| +| `XCEngine::Math::Vector3` | UI Editor 用 `float[3]` | **直接复用** | +| `XCEngine::Math::Quaternion` | UI Editor 用 `float[3]` (欧拉角) | **直接复用**，但欧拉角存储可保留 | +| `XCEngine::Math::Matrix4x4` | 无 | **直接复用** | +| `XCEngine::Core::Event` | ✅ 已复用 | 保持 | +| `XCEngine::Debug::LogLevel` | ✅ 已复用 | 保持 | + --- ## 七、依赖关系分析 @@ -290,8 +341,9 @@ private: P0: TransformComponent 世界空间 │ - ├── 需要: Vector3/Quaternion 数学类型 - ├── 需要: 矩阵计算方法 + ├── 需要: XCEngine::Math::Vector3 ✅ 已实现 + ├── 需要: XCEngine::Math::Quaternion ✅ 已实现 + ├── 需要: XCEngine::Math::Matrix4x4 ✅ 已实现 └── 影响: Entity::GetTransform() P0: Component::transform() @@ -318,7 +370,44 @@ P1: Scene 多场景 --- -## 八、附录：当前 GameObject.h 完整内容 +## 八、与 Unity 架构的对照 + +### Unity 传统架构 (GameObject-Component) + +``` +Scene + └── GameObject ("MyEntity") + ├── Transform + ├── MeshRenderer + └── (其他组件...) + +GameObject.GetComponent() → Entity.GetComponent() +GameObject.transform → Entity.GetTransform() +GameObject.SetActive(bool) → 缺失 +GameObject.Find("name") → 缺失 +Scene.GetRootGameObjects() → 缺失 +SceneManager.GetActiveScene() → 缺失 +``` + +### UI Editor 当前实现 + +``` +SceneManager (全局单例) + └── m_entities (unordered_map) + └── Entity ("MyEntity") + ├── id, name, parent, children + ├── components (vector>) + └── selected + +Entity.AddComponent() → ✅ 已实现 +Entity.GetComponent() → ✅ 已实现 +Entity.GetTransform() → ❌ 缺失 +TransformComponent 世界空间方法 → ❌ 缺失 +``` + +--- + +## 九、附录：当前 GameObject.h 完整内容 ```cpp // ui_editor/src/Core/GameObject.h 当前实现