Docs: Update UI-Editor GameObject system analysis
This commit is contained in:
@@ -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<T>` |
|
||||
| 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<TransformComponent*> 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<GameObject*>& GetChildren() const` | ❌ 缺失 | 获取子实体列表 |
|
||||
| `GetChild()` | `GameObject* GetChild(int index) const` | ❌ 缺失 | 按索引获取子实体 |
|
||||
| `SetParent(parent)` | `void SetParent(Entity* parent)` | ❌ 缺失 | 2参数版本（含 worldPositionStays） |
|
||||
| `GetChildren()` | `const std::vector<Entity*>& 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<GameObject*> FindObjectsOfType()` | ❌ 缺失 | 查找所有实体 |
|
||||
| `FindGameObjectsWithTag()` | `static std::vector<GameObject*> FindGameObjectsWithTag(const String& tag)` | ❌ 缺失 | 按标签查找 |
|
||||
| `Find()` | `static Entity* Find(const String& name)` | ❌ 缺失 | 按名称查找实体 |
|
||||
| `FindObjectsOfType()` | `static std::vector<Entity*> FindObjectsOfType()` | ❌ 缺失 | 查找所有实体 |
|
||||
| `FindGameObjectsWithTag()` | `static std::vector<Entity*> 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<GameObject*> 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<Entity*> GetRootGameObjects() const` | ❌ 缺失 | 获取根实体列表 |
|
||||
| `Find()` | `Entity* Find(const String& name) const` | ❌ 缺失 | 查找实体 |
|
||||
| `FindGameObjectWithTag()` | `Entity* FindGameObjectWithTag(const String& tag) const` | ❌ 缺失 | 按标签查找 |
|
||||
| `FindObjectsOfType<T>()` | `std::vector<T*> FindObjectsOfType() const` | ❌ 缺失 | 模板查找 |
|
||||
| `FindObjectOfType<T>()` | `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<unique_ptr<Component>>` | `vector<unique_ptr<Component>>` | ✅ 已对齐 |
|
||||
| 变换存储 | `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<T>` | ✅ 已复用 | 保持 |
|
||||
| `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<T>() → Entity.GetComponent<T>()
|
||||
GameObject.transform → Entity.GetTransform()
|
||||
GameObject.SetActive(bool) → 缺失
|
||||
GameObject.Find("name") → 缺失
|
||||
Scene.GetRootGameObjects() → 缺失
|
||||
SceneManager.GetActiveScene() → 缺失
|
||||
```
|
||||
|
||||
### UI Editor 当前实现
|
||||
|
||||
```
|
||||
SceneManager (全局单例)
|
||||
└── m_entities (unordered_map<EntityID, Entity>)
|
||||
└── Entity ("MyEntity")
|
||||
├── id, name, parent, children
|
||||
├── components (vector<unique_ptr<Component>>)
|
||||
└── selected
|
||||
|
||||
Entity.AddComponent<T>() → ✅ 已实现
|
||||
Entity.GetComponent<T>() → ✅ 已实现
|
||||
Entity.GetTransform() → ❌ 缺失
|
||||
TransformComponent 世界空间方法 → ❌ 缺失
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 九、附录：当前 GameObject.h 完整内容
|
||||
|
||||
```cpp
|
||||
// ui_editor/src/Core/GameObject.h 当前实现
|
||||
|
||||
Reference in New Issue
Block a user