# UI-Editor 设计与实现文档

> **版本**: 1.0  
> **日期**: 2026-03-20  
> **目标**: 为 XCEngine 游戏引擎搭建 UI 编辑器框架

---

## 第一章 概述

### 1.1 UI编辑器目标与定位

UI 编辑器是 XCEngine 游戏引擎的编辑器前端，用于可视化编辑游戏场景、场景层级、检视组件属性、控制台输出等核心功能。

**核心目标**：
1. 提供独立的 UI 编辑器可执行程序（基于 ImGui + D3D12）
2. UI 编辑器的数据结构与引擎核心类型对齐
3. 引擎核心已有的类型直接复用，引擎核心未实现的则在 UI 编辑器中临时实现但保持接口一致
4. 支持场景层级管理、实体创建删除、组件编辑等基础功能

**定位**：
- UI 编辑器作为引擎的独立模块，不直接耦合引擎渲染管线
- 通过 Engine 核心的抽象接口与引擎通信
- 当前阶段以独立开发为主，待引擎核心完善后进行对接

### 1.2 与引擎核心的对齐策略

| Engine 类型 | 状态 | UI 编辑器策略 |
|------------|------|-------------|
| `XCEngine::Core::Event<T>` | ✅ 已实现 | 直接复用 |
| `XCEngine::Core::uint64` | ✅ 已实现 | 直接复用 |
| `XCEngine::Debug::Logger` | ✅ 已实现 | 直接复用 |
| `XCEngine::Debug::LogLevel` | ✅ 已实现 | 直接复用 |
| `XCEngine::Debug::LogEntry` | ✅ 已实现 | 直接复用 |
| `XCEngine::Math::Vector3` 等 | 仅有设计文档 | UI 编辑器临时实现但接口对齐 |
| `Component` | 仅有设计文档 | UI 编辑器自行实现 `UI::Component` |
| `GameObject` | 仅有设计文档 | UI 编辑器自行实现 `UI::Entity` |
| `TransformComponent` | 仅有设计文档 | UI 编辑器自行实现 `UI::TransformComponent` |
| `Scene` / `SceneManager` | 仅有设计文档 | UI 编辑器自行实现 `UI::SceneManager` |

**对齐原则**：
- Engine 已有类型：直接 `#include <XCEngine/...>` 并使用
- Engine 暂无类型：在 UI 编辑器中实现，但类名、成员变量、成员函数命名与设计文档保持一致
- Engine 实现后：UI 编辑器可平滑迁移到 Engine 类型

### 1.3 技术选型

**渲染后端：D3D12**
- 与引擎核心渲染管线技术栈一致
- 支持多窗口、多渲染目标
- 提供高性能的 GPU 命令提交

**UI 框架：Dear ImGui**
- 轻量级、可扩展的即时模式 UI
- 支持主题定制
- 成熟的 D3D12 集成示例
- 高效的 UI 渲染管线

**架构模式：模块化 Manager + Panel**
- Manager：负责数据管理和业务逻辑
- Panel：负责 UI 展示和用户交互
- 清晰的职责分离便于维护和扩展

---

## 第二章 架构设计

### 2.1 整体架构图

```
┌─────────────────────────────────────────────────────────────────────────────────────┐
│                              UI 编辑器架构                                           │
└─────────────────────────────────────────────────────────────────────────────────────┘

                                    ┌─────────────────┐
                                    │  Application    │  应用程序入口
                                    │  (D3D12 + ImGui)│
                                    └────────┬────────┘
                                             │
          ┌─────────────────────────────────┼─────────────────────────────────┐
          │                                 │                                 │
          ▼                                 ▼                                 ▼
┌─────────────────┐               ┌─────────────────┐               ┌─────────────────┐
│   Managers      │               │     Panels      │               │   Core Types    │
│                 │               │                 │               │                 │
│ ┌─────────────┐ │               │ ┌─────────────┐ │               │ ┌─────────────┐ │
│ │SceneManager │ │               │ │HierarchyPanel│ │               │ │   Entity    │ │
│ └─────────────┘ │               │ └─────────────┘ │               │ └─────────────┘ │
│ ┌─────────────┐ │               │ ┌─────────────┐ │               │ ┌─────────────┐ │
│ │SelectionMgr │ │◀──────────────│ │InspectorPanel│ │               │ │  Component  │ │
│ └─────────────┘ │               │ └─────────────┘ │               │ └─────────────┘ │
│ ┌─────────────┐ │               │ ┌─────────────┐ │               │ ┌─────────────┐ │
│ │  LogSystem  │ │               │ │SceneViewPanel│ │               │ │  Theme      │ │
│ └─────────────┘ │               │ └─────────────┘ │               │ └─────────────┘ │
│ ┌─────────────┐ │               │ ┌─────────────┐ │               │                 │
│ │ProjectManager│ │              │ │GameViewPanel │ │               │                 │
│ └─────────────┘ │               │ └─────────────┘ │               │                 │
│ ┌─────────────┐ │               │ ┌─────────────┐ │               │                 │
│ │ AssetItem   │ │               │ │ConsolePanel │ │               │                 │
│ └─────────────┘ │               │ └─────────────┘ │               │                 │
│                 │               │ ┌─────────────┐ │               │                 │
│                 │               │ │ ProjectPanel│ │               │                 │
│                 │               │ └─────────────┘ │               │                 │
│                 │               │ ┌─────────────┐ │               │                 │
│                 │               │ │  MenuBar    │ │               │                 │
│                 │               │ └─────────────┘ │               │                 │
└─────────────────┘               └─────────────────┘               └─────────────────┘
          │                                 │
          │         ┌───────────────────────┘
          │         │
          ▼         ▼
┌─────────────────────────────────────────────────────────────────────────────────────┐
│                           Engine Core (XCEngine)                                    │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │Event<T>      │  │Logger        │  │LogLevel      │  │LogEntry      │              │
│  │(已实现复用)   │  │(已实现复用)   │  │(已实现复用)   │  │(已实现复用)   │              │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐              │
│  │Math Types   │  │Component     │  │GameObject    │  │Scene         │              │
│  │(设计文档)    │  │(设计文档)     │  │(设计文档)     │  │(设计文档)     │              │
│  └──────────────┘  └──────────────┘  └──────────────┘  └──────────────┘              │
└─────────────────────────────────────────────────────────────────────────────────────┘
```

### 2.2 目录结构

```
ui_editor/
├── CMakeLists.txt                                    # 构建配置
├── bin/                                              # 编译输出
│   └── Release/
│       └── XCVolumeRendererUI2.exe
├── build/                                            # 中间文件
└── src/
    ├── main.cpp                                      # 程序入口
    ├── Application.h/cpp                             # 应用程序类（D3D12 + ImGui）
    │
    ├── Core/                                         # 核心数据类型
    │   ├── GameObject.h                              # Entity、Component、TransformComponent
    │   ├── LogEntry.h                                # 日志条目（复用 Engine LogLevel）
    │   └── AssetItem.h                               # 资产条目
    │
    ├── Managers/                                     # 管理器系统
    │   ├── SceneManager.h/cpp                       # 场景管理
    │   ├── SelectionManager.h                        # 选择管理
    │   ├── LogSystem.h/cpp                           # 日志系统
    │   └── ProjectManager.h/cpp                      # 项目管理
    │
    ├── panels/                                      # UI 面板
    │   ├── Panel.h/cpp                              # 面板基类
    │   ├── MenuBar.h/cpp                            # 菜单栏
    │   ├── HierarchyPanel.h/cpp                     # 层级面板
    │   ├── InspectorPanel.h/cpp                     # 检视面板
    │   ├── SceneViewPanel.h/cpp                     # 场景视图
    │   ├── GameViewPanel.h/cpp                      # 游戏视图
    │   ├── ConsolePanel.h/cpp                       # 控制台面板
    │   └── ProjectPanel.h/cpp                       # 项目面板
    │
    └── Theme.h/cpp                                  # 主题样式
```

### 2.3 核心类型与引擎核心的对齐映射表

| UI 编辑器类型 | 文件位置 | 对齐的 Engine 类型 | 说明 |
|-------------|---------|------------------|------|
| `UI::Entity` | Core/GameObject.h | `XCEngine::GameObject` | 实体，包含 ID、名称、层级关系、组件 |
| `UI::Component` | Core/GameObject.h | `XCEngine::Component` | 组件基类 |
| `UI::TransformComponent` | Core/GameObject.h | `XCEngine::TransformComponent` | 变换组件 |
| `UI::MeshRendererComponent` | Core/GameObject.h | `XCEngine::RenderMeshComponent` | 网格渲染组件 |
| `UI::EntityID` | Core/GameObject.h | `uint64_t` | 实体唯一标识符 |
| `UI::INVALID_ENTITY_ID` | Core/GameObject.h | N/A | 无效实体 ID 常量 |
| `UI::SceneManager` | Managers/SceneManager.h | `XCEngine::SceneManager` | 场景管理器 |
| `UI::LogSystem` | Managers/LogSystem.h | `XCEngine::Debug::Logger` | 日志系统 |
| `UI::LogEntry` | Core/LogEntry.h | `XCEngine::Debug::LogEntry` | 日志条目 |
| `XCEngine::Core::Event<T>` | Engine/include/... | N/A | 直接复用引擎事件系统 |

---

## 第三章 核心数据类型

### 3.1 Entity（对齐 Engine GameObject）

`Entity` 是 UI 编辑器中的核心对象类型，对齐 Engine 的 `GameObject` 设计。

**设计文件**：`ui_editor/src/Core/GameObject.h`

```cpp
namespace UI {

using EntityID = uint64_t;
constexpr EntityID INVALID_ENTITY_ID = 0;

class Entity {
public:
    EntityID id = INVALID_ENTITY_ID;
    std::string name;
    EntityID parent = INVALID_ENTITY_ID;           // 父实体 ID
    std::vector<EntityID> children;                // 子实体 ID 列表
    std::vector<std::unique_ptr<Component>> components;
    bool selected = false;

    template<typename T, typename... Args>
    T* AddComponent(Args&&... args) {
        auto comp = std::make_unique<T>(std::forward<Args>(args)...);
        comp->m_entity = this;
        T* ptr = comp.get();
        components.push_back(std::move(comp));
        return ptr;
    }

    template<typename T>
    T* GetComponent() {
        for (auto& comp : components) {
            if (auto casted = dynamic_cast<T*>(comp.get())) {
                return casted;
            }
        }
        return nullptr;
    }

    template<typename T>
    std::vector<T*> GetComponents() {
        std::vector<T*> result;
        for (auto& comp : components) {
            if (auto casted = dynamic_cast<T*>(comp.get())) {
                result.push_back(casted);
            }
        }
        return result;
    }
};

} // namespace UI
```

**关键设计决策**：

1. **EntityID 类型**：使用 `uint64_t` 作为实体唯一标识，与 Engine 的 `uint64_t` 一致
2. **父子关系**：通过 `parent` ID 和 `children` ID 列表维护层级关系，避免循环引用
3. **组件存储**：使用 `std::vector<std::unique_ptr<Component>>` 存储组件，支持多态
4. **选择状态**：`selected` 成员用于追踪实体是否被选中

**与 Engine GameObject 的接口对齐**：

| UI::Entity 接口 | Engine::GameObject 接口 | 对齐状态 |
|---------------|------------------------|---------|
| `id` | (无直接对应，Engine 用指针) | 接口不同但功能一致 |
| `name` | `name` | ✅ 完全对齐 |
| `parent` | `GetParent()/SetParent()` | ✅ 功能对齐 |
| `children` | `GetChildren()` | ✅ 功能对齐 |
| `AddComponent<T>()` | `AddComponent<T>()` | ✅ 接口对齐 |
| `GetComponent<T>()` | `GetComponent<T>()` | ✅ 接口对齐 |

### 3.2 Component（对齐 Engine Component）

**设计文件**：`ui_editor/src/Core/GameObject.h`

```cpp
class Component {
public:
    virtual ~Component() = default;
    virtual std::string GetName() const = 0;

    virtual void Awake() {}
    virtual void Start() {}
    virtual void Update(float deltaTime) {}
    virtual void OnDestroy() {}

    class Entity* GetEntity() const { return m_entity; }
    bool IsEnabled() const { return m_enabled; }
    void SetEnabled(bool enabled) { m_enabled = enabled; }

protected:
    class Entity* m_entity = nullptr;
    bool m_enabled = true;

    friend class Entity;
};
```

**生命周期函数**：对齐 Engine Component 的设计，包含 `Awake()`、`Start()`、`Update()`、`OnDestroy()` 等。

**TransformComponent 实现**：

```cpp
class TransformComponent : public Component {
public:
    float position[3] = {0.0f, 0.0f, 0.0f};
    float rotation[3] = {0.0f, 0.0f, 0.0f};
    float scale[3] = {1.0f, 1.0f, 1.0f};

    std::string GetName() const override { return "Transform"; }
};
```

**MeshRendererComponent 实现**：

```cpp
class MeshRendererComponent : public Component {
public:
    std::string materialName = "Default-Material";
    std::string meshName = "";

    std::string GetName() const override { return "Mesh Renderer"; }
};
```

### 3.3 ComponentRegistry（组件注册表）

组件注册表用于将组件类型与对应的 ImGui 检视函数关联。

```cpp
using ComponentInspectorFn = std::function<void(Component*)>;

struct ComponentInspectorInfo {
    std::string name;
    ComponentInspectorFn renderFn;
};

class ComponentRegistry {
public:
    static ComponentRegistry& Get() {
        static ComponentRegistry instance;
        return instance;
    }

    template<typename T>
    void RegisterComponent(const std::string& name, ComponentInspectorFn inspectorFn) {
        m_inspectors[name] = {name, inspectorFn};
        m_factories[name] = []() -> std::unique_ptr<Component> {
            return std::make_unique<T>();
        };
    }

    ComponentInspectorInfo* GetInspector(const std::string& name) {
        auto it = m_inspectors.find(name);
        if (it != m_inspectors.end()) {
            return &it->second;
        }
        return nullptr;
    }

private:
    ComponentRegistry() = default;
    std::unordered_map<std::string, ComponentInspectorInfo> m_inspectors;
    std::unordered_map<std::string, std::function<std::unique_ptr<Component>()>> m_factories;
};
```

**注册示例**（在 `InspectorPanel.cpp` 中）：

```cpp
ComponentRegistry::Get().RegisterComponent<TransformComponent>(
    "Transform",
    [](Component* comp) {
        auto* transform = dynamic_cast<TransformComponent*>(comp);
        ImGui::InputFloat3("Position", transform->position);
        ImGui::InputFloat3("Rotation", transform->rotation);
        ImGui::InputFloat3("Scale", transform->scale);
    }
);
```

### 3.4 SceneManager（对齐 Engine SceneManager）

**设计文件**：`ui_editor/src/Managers/SceneManager.h`

```cpp
class SceneManager {
public:
    static SceneManager& Get() {
        static SceneManager instance;
        return instance;
    }

    EntityID CreateEntity(const std::string& name, EntityID parent = INVALID_ENTITY_ID);

    Entity* GetEntity(EntityID id) {
        auto it = m_entities.find(id);
        if (it != m_entities.end()) {
            return &it->second;
        }
        return nullptr;
    }

    const std::vector<EntityID>& GetRootEntities() const {
        return m_rootEntities;
    }

    void DeleteEntity(EntityID id);
    void RenameEntity(EntityID id, const std::string& newName);
    void CopyEntity(EntityID id);
    EntityID PasteEntity(EntityID parent = INVALID_ENTITY_ID);
    EntityID DuplicateEntity(EntityID id);
    void MoveEntity(EntityID id, EntityID newParent);
    void CreateDemoScene();

    XCEngine::Core::Event<EntityID> OnEntityCreated;
    XCEngine::Core::Event<EntityID> OnEntityDeleted;
    XCEngine::Core::Event<EntityID> OnEntityChanged;
    XCEngine::Core::Event<> OnSceneChanged;

private:
    EntityID m_nextEntityId = 1;
    std::unordered_map<EntityID, Entity> m_entities;
    std::vector<EntityID> m_rootEntities;
    std::optional<ClipboardData> m_clipboard;
};
```

**关键设计决策**：

1. **Singleton 模式**：通过 `static SceneManager& Get()` 提供全局访问点
2. **实体存储**：`std::unordered_map<EntityID, Entity>` 提供 O(1) 的实体查找
3. **根实体列表**：`m_rootEntities` 维护所有顶层实体，用于层级面板展示
4. **剪贴板支持**：`std::optional<ClipboardData>` 支持复制/粘贴操作
5. **事件系统**：复用 Engine 的 `Event<T>` 实现观察者模式

**事件类型说明**：

| 事件 | 签名 | 触发时机 |
|-----|------|---------|
| `OnEntityCreated` | `Event<EntityID>` | 创建新实体时 |
| `OnEntityDeleted` | `Event<EntityID>` | 删除实体时 |
| `OnEntityChanged` | `Event<EntityID>` | 实体属性变化时（重命名、父子关系变化） |
| `OnSceneChanged` | `Event<>` | 场景整体变化时 |

---

## 第四章 面板系统

### 4.1 Panel 基类

所有面板继承自 `Panel` 基类，提供统一的接口。

**设计文件**：`ui_editor/src/panels/Panel.h`

```cpp
class Panel {
public:
    virtual ~Panel() = default;

    virtual void Initialize() {}
    virtual void Render() = 0;
    virtual void OnSceneChanged() {}

    const char* GetName() const { return m_name; }
    bool IsVisible() const { return m_visible; }
    void SetVisible(bool visible) { m_visible = visible; }

protected:
    const char* m_name = "Panel";
    bool m_visible = true;
};
```

**ImGui 窗口包装示例**：

```cpp
void HierarchyPanel::Render() {
    if (!m_visible) return;

    ImGui::PushID(GetName());
    if (ImGui::Begin(GetName(), &m_visible, ImGuiWindowFlags_NoCollapse)) {
        RenderContent();
    }
    ImGui::End();
    ImGui::PopID();
}
```

### 4.2 HierarchyPanel（层级面板）

**职责**：展示场景层级结构，支持实体的创建、删除、拖拽排序、右键菜单。

**设计文件**：`ui_editor/src/panels/HierarchyPanel.h`

```cpp
class HierarchyPanel : public Panel {
public:
    void Initialize() override;
    void OnSceneChanged() override;

private:
    void RenderContent();
    void RenderEntity(EntityID entity, int& nodeIndex);
    void RenderContextMenu(EntityID entity);
    void RenderCreateMenu();
};
```

**核心功能**：

1. **树形结构展示**：递归渲染实体及其子实体
2. **选中高亮**：选中的实体以高亮显示
3. **拖拽排序**：支持通过拖拽改变实体顺序和父子关系
4. **右键菜单**：创建、删除、复制、粘贴、重命名等操作
5. **搜索过滤**：支持按名称搜索实体

**节点渲染流程**：

```
RenderEntity(EntityID id)
  │
  ├── 获取实体指针 GetEntity(id)
  │
  ├── 构建节点标签 [图标] [名称] [子节点数量]
  │
  ├── 选中状态处理
  │     └── 点击时调用 SelectionManager::Select(id)
  │
  ├── 展开/折叠状态
  │
  ├── 渲染子节点（递归）
  │     └── for child in entity.children: RenderEntity(child)
  │
  └── 渲染右键菜单（如果右键）
```

### 4.3 InspectorPanel（检视面板）

**职责**：展示选中实体的所有组件及其属性，支持编辑。

**设计文件**：`ui_editor/src/panels/InspectorPanel.h`

```cpp
class InspectorPanel : public Panel {
public:
    void Initialize() override;
    void OnSelectionChanged();

private:
    void RenderContent();
    void RenderEntityHeader(Entity* entity);
    void RenderComponent(Component* comp);
    void RenderAddComponentMenu();
};
```

**核心功能**：

1. **实体头信息**：显示实体名称，支持直接编辑
2. **组件列表**：遍历实体的所有组件
3. **组件检视**：调用 `ComponentRegistry` 获取检视函数并渲染
4. **添加组件**：显示可添加的组件类型列表

**组件检视函数注册示例**：

```cpp
void InspectorPanel::Initialize() {
    ComponentRegistry::Get().RegisterComponent<TransformComponent>(
        "Transform",
        [](Component* comp) {
            auto* transform = dynamic_cast<TransformComponent*>(comp);
            ImGui::InputFloat3("Position", transform->position);
            if (ImGui::InputFloat3("Rotation", transform->rotation)) {
                SceneManager::Get().GetEntity(transform->GetEntity()->id)
                    ->name = transform->GetEntity()->name; // 触发变更事件
            }
            ImGui::InputFloat3("Scale", transform->scale, 1.0f);
        }
    );

    ComponentRegistry::Get().RegisterComponent<MeshRendererComponent>(
        "Mesh Renderer",
        [](Component* comp) {
            auto* mesh = dynamic_cast<MeshRendererComponent*>(comp);
            ImGui::InputText("Mesh", &mesh->meshName);
            ImGui::InputText("Material", &mesh->materialName);
        }
    );
}
```

### 4.4 SceneViewPanel（场景视图）

**职责**：渲染场景视图窗口，提供视口控制。

**设计文件**：`ui_editor/src/panels/SceneViewPanel.h`

**当前实现状态**：基础框架已搭建，待扩展。

**计划功能**：
- 视口渲染（通过 Engine 渲染管线）
- 相机控制（平移、旋转、缩放）
- Gizmos 渲染（变换、旋转、缩放工具）
- 网格和辅助线显示

### 4.5 GameViewPanel（游戏视图）

**职责**：显示游戏运行时的画面。

**设计文件**：`ui_editor/src/panels/GameViewPanel.h`

**当前实现状态**：基础框架已搭建，待与 Engine 渲染管线对接。

### 4.6 ConsolePanel（控制台）

**职责**：显示日志系统收集的日志消息。

**设计文件**：`ui_editor/src/panels/ConsolePanel.h/cpp`

```cpp
class ConsolePanel : public Panel {
public:
    void Initialize() override;
    void Clear();
    void OnLogMessage(const LogEntry& entry);

private:
    void RenderContent();
    void RenderLogEntry(const LogEntry& entry);
    void RenderFilterBar();

    std::vector<LogEntry> m_logs;
    std::vector<LogEntry> m_filteredLogs;
    bool m_autoScroll = true;
    bool m_wordWrap = false;
    XCEngine::Debug::LogLevel m_minLevel = XCEngine::Debug::LogLevel::Verbose;
};
```

**核心功能**：

1. **日志显示**：显示所有收集的日志条目
2. **级别过滤**：通过下拉菜单筛选日志级别
3. **自动滚动**：新日志自动滚动到底部
4. **时间戳显示**：显示每条日志的时间戳
5. **双击跳转**：双击日志可定位到相关实体（预留）

### 4.7 ProjectPanel（项目面板）

**职责**：浏览项目资源文件。

**设计文件**：`ui_editor/src/panels/ProjectPanel.h/cpp`

**当前实现状态**：基础框架已搭建，待扩展资源导入功能。

---

## 第五章 管理器系统

### 5.1 SelectionManager（选择管理器）

**设计文件**：`ui_editor/src/Managers/SelectionManager.h`

```cpp
class SelectionManager {
public:
    static SelectionManager& Get() {
        static SelectionManager instance;
        return instance;
    }

    void Select(EntityID entity);
    void Deselect(EntityID entity);
    void ToggleSelection(EntityID entity);
    void ClearSelection();
    void SetSelection(const std::vector<EntityID>& entities);

    bool IsSelected(EntityID entity) const;
    const std::vector<EntityID>& GetSelection() const { return m_selection; }
    size_t GetSelectionCount() const { return m_selection.size(); }

    XCEngine::Core::Event<EntityID> OnSelected;
    XCEngine::Core::Event<EntityID> OnDeselected;
    XCEngine::Core::Event<> OnSelectionCleared;

private:
    SelectionManager() = default;
    std::vector<EntityID> m_selection;
    std::unordered_set<EntityID> m_selectionSet;
};
```

**关键设计决策**：

1. **双向存储**：`m_selection` 保持顺序，`m_selectionSet` 提供 O(1) 查询
2. **事件系统**：选择变化时触发对应事件
3. **多选支持**：通过 `SetSelection` 支持批量选择

### 5.2 LogSystem（日志系统）

**设计文件**：`ui_editor/src/Managers/LogSystem.h/cpp`

```cpp
class LogSystem {
public:
    static LogSystem& Get() {
        static LogSystem instance;
        return instance;
    }

    void Initialize();
    void Shutdown();

    void Log(XCEngine::Debug::LogLevel level, const std::string& message,
             const std::string& file = "", int line = 0);

    void Info(const std::string& message) { Log(LogLevel::Info, message); }
    void Warning(const std::string& message) { Log(LogLevel::Warning, message); }
    void Error(const std::string& message) { Log(LogLevel::Error, message); }

    XCEngine::Core::Event<const LogEntry&> OnLog;

private:
    LogSystem() = default;
    std::vector<LogEntry> m_logs;
};
```

**日志流向**：

```
XCEngine::Debug::Logger (Engine)
        │
        ▼ (通过自定义 LogSink 拦截)
UI::LogSystem::OnLog
        │
        ▼
ConsolePanel::OnLogMessage
        │
        ▼
显示到 ConsolePanel
```

### 5.3 ProjectManager（项目管理器）

**设计文件**：`ui_editor/src/Managers/ProjectManager.h/cpp`

**职责**：
- 管理项目根目录
- 扫描和索引资源文件
- 提供资源查找接口

---

## 第六章 事件系统

### 6.1 引擎 Event<T> 的复用

UI 编辑器直接复用 Engine 的事件系统：

```cpp
#include <XCEngine/Core/Event.h>

// 使用方式
XCEngine::Core::Event<EntityID> OnEntityCreated;
XCEngine::Core::Event<EntityID> OnEntityDeleted;
XCEngine::Core::Event<EntityID> OnEntityChanged;
XCEngine::Core::Event<> OnSceneChanged;
```

**订阅示例**：

```cpp
// 在 Panel 初始化时订阅
SceneManager::Get().OnEntityCreated.AddLambda([this](EntityID id) {
    // 处理实体创建
});
```

### 6.2 UI 编辑器事件类型

| 事件源 | 事件名 | 签名 | 说明 |
|-------|-------|------|------|
| `SceneManager` | `OnEntityCreated` | `Event<EntityID>` | 实体创建 |
| `SceneManager` | `OnEntityDeleted` | `Event<EntityID>` | 实体删除 |
| `SceneManager` | `OnEntityChanged` | `Event<EntityID>` | 实体属性变化 |
| `SceneManager` | `OnSceneChanged` | `Event<>` | 场景变化 |
| `SelectionManager` | `OnSelected` | `Event<EntityID>` | 实体被选中 |
| `SelectionManager` | `OnDeselected` | `Event<EntityID>` | 实体取消选中 |
| `SelectionManager` | `OnSelectionCleared` | `Event<>` | 选择被清空 |
| `LogSystem` | `OnLog` | `Event<const LogEntry&>` | 日志消息 |

### 6.3 事件处理时机

**同一帧内的事件处理**：

```cpp
void Application::Render() {
    // 1. 处理用户输入
    // 2. 更新 Managers
    SceneManager::Get().Update(deltaTime);

    // 3. 清空pending列表（ProcessUnsubscribes）
    // 4. 渲染 ImGui UI
    RenderUI();

    // 5. 渲染 D3D12
    RenderD3D12();
}
```

**注意**：`Event<T>::ProcessUnsubscribes()` 应在每帧适当位置调用，以确保安全的订阅取消。

---

## 第七章 渲染集成

### 7.1 D3D12 初始化流程

**设计文件**：`ui_editor/src/Application.cpp`

```
Initialize(HWND hwnd)
    │
    ├── CreateDevice()
    │     ├── D3D12CreateDevice()
    │     ├── CreateCommandQueue()
    │     ├── CreateCommandAllocator()
    │     └── CreateCommandList()
    │
    ├── CreateRenderTarget()
    │     ├── CreateDescriptorHeap (RTV)
    │     ├── CreateDescriptorHeap (SRV)
    │     └── CreateRenderTargets (3个双缓冲)
    │
    └── CreateFence()
```

### 7.2 ImGui 渲染管线

**初始化**：

```cpp
ImGui_ImplWin32_Init(hwnd);
ImGui_ImplDX12_Init(
    m_device,
    3,                              // 双缓冲帧数
    DXGI_FORMAT_R8G8B8A8_UNORM,    // 格式
    m_srvHeap,
    m_srvHeap->GetCPUDescriptorHandleForHeapStart(),
    m_srvHeap->GetGPUDescriptorHandleForHeapStart()
);
```

**渲染**：

```cpp
ImGui_ImplDX12_NewFrame();
ImGui_ImplWin32_NewFrame();
ImGui::NewFrame();

// 渲染 ImGui UI
RenderUI();

ImGui::EndFrame();
ImGui::Render();
ImGui_ImplDX12_RenderDrawData(ImGui::GetDrawData(), m_commandList);
```

### 7.3 渲染目标与交换链

**配置**：

```cpp
swapChainDesc.Width = width;
swapChainDesc.Height = height;
swapChainDesc.Format = DXGI_FORMAT_R8G8B8A8_UNORM;
swapChainDesc.BufferCount = 3;       // 三重缓冲
swapChainDesc.SampleDesc.Count = 1;
```

**_present 流程**：

```cpp
m_swapChain->Present(1, 0);
m_fenceValue++;
m_commandQueue->Signal(m_fence, m_fenceValue);
```

---

## 第八章 主题与样式

### 8.1 Theme 系统

**设计文件**：`ui_editor/src/Theme.h/cpp`

```cpp
struct Theme {
    ImVec4 colors[ImGuiCol_COUNT];

    void Apply();
    void LoadDefault();
    void LoadDark();
    void LoadLight();
};

extern Theme g_theme;
```

**默认深色主题配色**：

| 用途 | 颜色 (RGB) |
|-----|-----------|
| 背景 | (0.1, 0.1, 0.1) |
| 面板背景 | (0.15, 0.15, 0.15) |
| 边框 | (0.3, 0.3, 0.3) |
| 文字 | (0.9, 0.9, 0.9) |
| 选中 | (0.2, 0.4, 0.8) |
| 警告 | (0.9, 0.6, 0.2) |
| 错误 | (0.9, 0.2, 0.2) |

---

## 第九章 未来扩展计划

### 9.1 序列化/反序列化

**计划实现**：

```cpp
class SceneSerializer {
public:
    bool Serialize(Scene* scene, const String& filePath);
    bool Deserialize(Scene* scene, const String& filePath);
};
```

**文件格式**：JSON 或二进制（待定）

### 9.2 撤销/重做系统

**计划实现**：

```cpp
class UndoSystem {
public:
    void PushAction(std::unique_ptr<IAction> action);
    void Undo();
    void Redo();
    bool CanUndo() const;
    bool CanRedo() const;

private:
    std::vector<std::unique_ptr<IAction>> m_undoStack;
    std::vector<std::unique_ptr<IAction>> m_redoStack;
};
```

**支持的操作**：
- 实体创建/删除
- 实体重命名
- 实体移动（父子关系变更）
- 组件添加/删除
- 属性修改

### 9.3 资源导入管线

**计划实现**：

1. 资源文件监控（文件变化自动检测）
2. 资源导入器（Mesh、Texture、Material 等）
3. 资源依赖解析
4. 资源热重载

### 9.4 预制体系统

**计划实现**：

```cpp
class Prefab {
public:
    String name;
    std::vector<std::unique_ptr<Component>> components;
    std::vector<Prefab> children;
};
```

---

## 附录 A：核心类型对齐详细对照表

| UI 编辑器类型/接口 | Engine 类型/接口 | 文件位置 | 对齐状态 |
|------------------|----------------|---------|---------|
| `UI::Entity` | `XCEngine::GameObject` | GameObject.h / GameObject.h | ✅ 接口对齐 |
| `UI::EntityID` | `uint64_t` | GameObject.h / Types.h | ✅ 完全一致 |
| `UI::INVALID_ENTITY_ID = 0` | N/A | GameObject.h | ✅ 自定义常量 |
| `UI::Component` | `XCEngine::Component` | GameObject.h / Component.h | ✅ 接口对齐 |
| `UI::Component::GetEntity()` | `Component::gameObject()` | GameObject.h / Component.h | ✅ 功能一致 |
| `UI::TransformComponent` | `XCEngine::TransformComponent` | GameObject.h / TransformComponent.h | ✅ 接口对齐 |
| `UI::TransformComponent::position` | `TransformComponent::GetPosition()` | GameObject.h / TransformComponent.h | ✅ 成员/方法对齐 |
| `UI::SceneManager` | `XCEngine::SceneManager` | SceneManager.h / SceneManager.h | ✅ 接口对齐 |
| `UI::SceneManager::CreateEntity()` | `SceneManager::CreateScene()` (不同) | SceneManager.h | ⚠️ 接口有差异 |
| `UI::LogSystem` | `XCEngine::Debug::Logger` | LogSystem.h / Logger.h | ✅ 功能复用 |
| `UI::LogEntry` | `XCEngine::Debug::LogEntry` | LogEntry.h / LogEntry.h | ✅ 复用 Engine |
| `XCEngine::Core::Event<T>` | N/A | Event.h | ✅ 直接复用 |
| `XCEngine::Debug::LogLevel` | N/A | LogLevel.h | ✅ 直接复用 |

---

## 附录 B：事件类型清单

### SceneManager 事件

| 事件名 | 类型 | 参数 | 触发时机 |
|-------|------|------|---------|
| `OnEntityCreated` | `Event<EntityID>` | 新实体的 ID | `CreateEntity()` 成功后 |
| `OnEntityDeleted` | `Event<EntityID>` | 被删实体的 ID | `DeleteEntity()` 成功后 |
| `OnEntityChanged` | `Event<EntityID>` | 变化实体的 ID | `RenameEntity()`、`MoveEntity()` 等 |
| `OnSceneChanged` | `Event<>` | 无 | 场景整体变化时 |

### SelectionManager 事件

| 事件名 | 类型 | 参数 | 触发时机 |
|-------|------|------|---------|
| `OnSelected` | `Event<EntityID>` | 被选实体的 ID | `Select()` 时 |
| `OnDeselected` | `Event<EntityID>` | 取消选中的实体 ID | `Deselect()` 时 |
| `OnSelectionCleared` | `Event<>` | 无 | `ClearSelection()` 时 |

### LogSystem 事件

| 事件名 | 类型 | 参数 | 触发时机 |
|-------|------|------|---------|
| `OnLog` | `Event<const LogEntry&>` | 日志条目引用 | 任意日志产生时 |

---

## 附录 C：面板布局配置

**默认布局**（通过 ImGui Dockspace 实现）：

```
┌────────────────────────────────────────────────────────────────────┐
│                              MenuBar                               │
├──────────────┬─────────────────────────────────┬─────────────────┤
│              │                                 │                 │
│   Hierarchy  │         SceneView              │    Inspector    │
│    Panel     │          Panel                   │      Panel      │
│              │                                 │                 │
│   (200px)    │         (flex)                  │    (250px)      │
│              │                                 │                 │
├──────────────┼─────────────────────────────────┼─────────────────┤
│              │                                 │                 │
│   Project    │         GameView                │    Console      │
│    Panel     │          Panel                   │      Panel      │
│              │                                 │                 │
│   (200px)    │         (flex)                  │    (150px)      │
│              │                                 │                 │
└──────────────┴─────────────────────────────────┴─────────────────┘
```

**Dock 优先级**：
1. HierarchyPanel - 左上
2. SceneViewPanel - 中上
3. InspectorPanel - 右上
4. ProjectPanel - 左下
5. GameViewPanel - 中下
6. ConsolePanel - 右下

---

**文档结束**