XCEngine/docs/plan/Editor架构说明.md

Editor 架构说明

1. 当前目标

当前这一轮 editor 重构，目标不是继续在各个 panel 上零散修 UI，而是先把 editor 自身的架构层次收稳：

• 把视觉样式、交互路由、编辑命令、dock 布局、面板壳层拆开。
• 把 Hierarchy / Project / Inspector / Console / MenuBar 统一到同一套 shared UI 和 action 语义上。
• 把 Scene / Game viewport 保持在当前真实主链上：ViewportHostService -> Rendering + RHI -> ImGui panel。
• 把 Assets + .meta + Library 项目工作流、脚本程序集构建与运行时状态纳入 editor 正式分层，而不是继续当外围脚本。

这意味着当前 editor 的重点已经不是“先把外壳搭出来”，而是：

• 在现有外壳分层上继续收口真实可运行的 viewport / project / scripting 主链。
• 让 panel、viewport helper、commands、managers 和引擎侧 Rendering / Resources / Scene / Scripting 的边界继续清晰化。

2. 总体分层

当前 editor 推荐按下面的依赖方向理解：

Application -> EditorLayer -> EditorWorkspace -> Panels/Viewport -> Actions -> Commands -> Managers/Core

同时还有一条横向的共享 UI 层：

Panels / Actions / ComponentEditors -> UI

以及一条 inspector 专用扩展链路：

InspectorPanel -> ComponentEditorRegistry -> IComponentEditor

以及一条已经落地的 editor 到引擎主链：

Viewport / Managers / Scripting -> Rendering / Resources / Scene / Scripting / RHI

允许依赖的基本原则：

• UI 只负责样式 token、共享控件、popup/property-grid 等表现层能力，不承担业务语义。
• Actions 负责把 button/menu/shortcut/context menu 这些 UI 意图转换为命令调用、事件请求或共享状态更新。
• Commands 负责真正修改 scene/project/component 数据，并处理 dirty/undo/selection 的业务边界。
• Panels 只保留最小的渲染壳层和少量局部瞬时状态，不直接堆业务逻辑。
• Layout 只负责 dockspace 和布局持久化，不处理 scene/project 业务。
• Core/Managers 提供 editor 运行时共享状态与数据入口。
• Viewport 是 editor 宿主和引擎渲染主链之间的正式桥接层，不是 panel 内随手拼的辅助代码。

不允许继续扩散的方向：

• 不要在 panel 里直接散落 scene/project 业务修改。
• 不要把菜单、快捷键、右键菜单逻辑分别复制到不同 panel。
• 不要把样式常量重新写回 panel 本地。
• 不要让 UI 反向依赖 Commands 或具体 panel。

3. 主要模块职责

3.1 Application / Platform

关键文件：

• editor/src/Application.cpp
• editor/src/Platform/Win32EditorHost.h
• editor/src/Platform/D3D12WindowRenderer.h
• editor/src/UI/ImGuiSession.h
• editor/src/UI/ImGuiBackendBridge.h

职责：

• 创建窗口、D3D12 renderer、ImGui session 与 backend bridge。
• 初始化 EditorContext。
• 监听 editor 级退出事件。
• 驱动 layer attach/detach/update/render 主循环。
• 更新窗口标题。

边界：

• 这里是 editor 的宿主壳层，不负责具体 panel 交互。
• 这里可以处理平台与渲染 backend 生命周期，但不应该继续写 editor 业务逻辑。

3.2 EditorLayer / EditorWorkspace

关键文件：

• editor/src/Layers/EditorLayer.cpp
• editor/src/Core/EditorWorkspace.h

职责：

• EditorLayer 只做 layer 生命周期转发。
• EditorWorkspace 负责组装 panel 集合、初始化 project panel、加载启动场景、挂接 dock layout controller。
• 统一调度 panel 的 attach/detach/update/render/event。

边界：

• EditorLayer 不能回到“自己直接维护一堆 panel 生命周期”的旧结构。
• 新增 panel 时，优先在 EditorWorkspace 里做装配，不回写到 Application。

3.3 UI Shared Layer

关键文件：

• editor/src/UI/BaseTheme.h
• editor/src/UI/StyleTokens.h
• editor/src/UI/DockHostStyle.h
• editor/src/UI/PanelChrome.h
• editor/src/UI/Widgets.h
• editor/src/UI/PopupState.h
• editor/src/UI/PropertyGrid.h
• editor/src/UI/UI.h

职责：

• 提供 editor 统一主题、尺寸、留白、颜色和面板 chrome。
• 提供 toolbar、tab、popup、dialog、property row、asset tile、empty state 等共享控件。
• 提供 inspector/property-grid 的公共表现层。

边界：

• 这一层可以知道 ImGui，但不应该知道 scene/project 业务对象如何变化。
• 这一层输出的是“怎样画”，不是“点了以后改什么”。

3.4 Actions / Routers

关键文件：

• editor/src/Actions/EditorActions.h
• editor/src/Actions/ActionBinding.h
• editor/src/Actions/ActionRouting.h
• editor/src/Actions/EditActionRouter.h
• editor/src/Actions/MainMenuActionRouter.h
• editor/src/Actions/HierarchyActionRouter.h
• editor/src/Actions/ProjectActionRouter.h
• editor/src/Actions/InspectorActionRouter.h
• editor/src/Actions/ConsoleActionRouter.h

职责：

• 定义 editor 内部动作项的文案、快捷键、可用状态。
• 统一菜单点击、快捷键触发、toolbar 按钮、右键菜单动作。
• 处理 active route/focused route，把 Edit 类动作路由到正确 panel。
• 处理 popup 请求、rename 请求、局部状态切换等“轻量交互编排”。

边界：

• Actions 可以依赖 Commands、EventBus、UI，但不负责底层数据结构修改细节。
• Actions 不负责持久保存复杂状态；复杂状态应留给 manager 或共享 state object。
• Actions 不应该包含大量 panel 私有布局代码。

判断标准：

• 一个交互如果同时被 menu、shortcut、context menu、toolbar 复用，它应先进入 router。
• 一个交互如果只是“请求 panel 开一个 popup/进入 rename”，更适合走 Actions + EventBus/shared state。

3.5 Commands

关键文件：

• editor/src/Commands/SceneCommands.h
• editor/src/Commands/EntityCommands.h
• editor/src/Commands/ProjectCommands.h
• editor/src/Commands/ComponentCommands.h

职责：

• 处理 scene/project/component 的实际编辑行为。
• 统一 undo 快照、dirty 标记、selection reset 等业务边界。
• 统一保存、加载、复制、粘贴、重命名、重挂接、资源移动等操作。

边界：

• Commands 不依赖 ImGui。
• Commands 不直接绘制 UI。
• Commands 返回的是业务结果，不承载 popup 绘制和菜单拼装。

经验规则：

• 只要一个操作会改 scene/project 数据，就优先考虑落到 Commands。
• 只要一个操作涉及 undo/redo，就不要留在 panel 本地手写。

3.6 Core / Managers

关键文件：

• editor/src/Core/EditorContext.h
• editor/src/Core/EventBus.h
• editor/src/Core/SelectionManager.h
• editor/src/Core/UndoManager.h
• editor/src/Managers/SceneManager.h
• editor/src/Managers/ProjectManager.h

职责：

• EditorContext 聚合 event bus、selection、scene、project、undo、active action route。
• SceneManager 持有场景对象、根节点、场景路径、dirty 状态、clipboard。
• ProjectManager 扫描 Assets、维护当前目录、选择索引、文件夹导航。
• SelectionManager 统一发布 selection changed 事件。
• UndoManager 负责快照历史、interactive change 边界、undo/redo。

所有权约定：

• selection 所有权在 SelectionManager。
• undo 历史所有权在 UndoManager。
• scene dirty 与当前场景路径所有权在 SceneManager。
• 当前活动编辑路由所有权在 EditorContext。

3.7 Layout

关键文件：

• editor/src/Layout/DockLayoutController.h

职责：

• 创建 dockspace。
• 应用默认布局。
• 响应 reset layout 请求。
• 持久化 ImGui layout 到项目目录下的 .xceditor/imgui_layout.ini。

边界：

• layout controller 不应该知道 hierarchy/project/scene 的编辑业务。
• panel 是否存在由 workspace 决定，不由 layout controller 反向创建。

3.8 Panels

关键文件：

• editor/src/panels/MenuBar.cpp
• editor/src/panels/HierarchyPanel.cpp
• editor/src/panels/ProjectPanel.cpp
• editor/src/panels/InspectorPanel.cpp
• editor/src/panels/ConsolePanel.cpp

当前 panel 应保留的内容：

• 窗口壳层。
• 生命周期订阅与退订。
• 非共享的极少量局部瞬时状态。
• 调用 shared UI/widget 和 action router 进行拼装。

当前 panel 不应该再承载的内容：

• undo/dirty/selection 的业务判断。
• 菜单和快捷键的重复定义。
• 资源/实体操作的底层命令执行细节。
• 大量散落的视觉常量。

3.9 ComponentEditors

关键文件：

• editor/src/ComponentEditors/IComponentEditor.h
• editor/src/ComponentEditors/ComponentEditorRegistry.h
• editor/src/ComponentEditors/ComponentEditorRegistry.cpp
• editor/src/ComponentEditors/TransformComponentEditor.h
• editor/src/ComponentEditors/CameraComponentEditor.h
• editor/src/ComponentEditors/LightComponentEditor.h

职责：

• 为某一类 component 提供 inspector 内容绘制。
• 定义该 component 的显示名、是否能添加、是否能删除、添加禁用原因。
• 通过 registry 统一注册到 inspector 与 component commands。

当前注册机制：

• ComponentEditorRegistry 是 editor 侧单例注册表。
• 注册发生在 ComponentEditorRegistry 构造函数内。
• RegisterEditor(std::unique_ptr<IComponentEditor>) 将 editor 同时放入顺序列表和按类型名索引表。
• inspector 绘制时通过 component 实例类型名查找 editor。
• Add Component 菜单通过遍历 registry 的已注册 editor 生成。
• ComponentCommands 通过相同 registry 复用 add/remove 规则，而不是在 inspector 单独硬编码。

这套机制的意义：

• inspector 的“显示逻辑”和“组件增删能力”在同一处收口。
• 新增一个 component editor 时，不需要去 panel 里到处补分支。
• 后续如果要做脚本组件、自定义组件 inspector，优先扩展 registry，而不是污染 panel。

新增 component editor 的推荐步骤：

1. 新建一个实现 IComponentEditor 的 editor。
2. 在其中定义 GetComponentTypeName / GetDisplayName / Render / CanAddTo / CanRemove。
3. 在 ComponentEditorRegistry.cpp 注册。
4. 如果涉及复杂交互，优先复用 UI::PropertyGrid 和 undo interactive change 机制。

3.10 Viewport

关键文件：

• editor/src/Viewport/ViewportHostService.h
• editor/src/Viewport/IViewportHostService.h
• editor/src/Viewport/SceneViewportChrome.h
• editor/src/Viewport/SceneViewportInteractionFrame.h
• editor/src/Viewport/SceneViewportNavigation.h
• editor/src/Viewport/SceneViewportTransformGizmoCoordinator.h
• editor/src/Viewport/SceneViewportOverlayBuilder.h
• editor/src/Viewport/SceneViewportOverlayFrameCache.h
• editor/src/Viewport/SceneViewportOverlaySpriteResources.h
• editor/src/Viewport/SceneViewportResourcePaths.h
• editor/src/Viewport/Passes/SceneViewportEditorOverlayPass.h

职责：

• 作为 editor 宿主与引擎 Rendering + RHI 的桥接层，维护 Scene / Game viewport 的离屏渲染接线。
• 维护当前 Scene View helper 主链：
  • SceneViewportChrome
  • SceneViewportInteractionFrame
  • SceneViewportNavigation
  • SceneViewportTransformGizmoCoordinator
  • ViewportHostService
• 负责 overlay builder、overlay frame cache、sprite 资源准备、object-id picking、grid、outline 和 gizmo overlay state。

边界：

• Viewport 是正式子系统，不再是“等待未来回归”的空位。
• panel 不应自己拼接一套独立渲染路径；新的 viewport 行为优先落到 helper、host service 或 overlay pass。
• SceneViewportShaderPaths.h 当前主要是兼容 include；资源路径真实 owner 已经转到 SceneViewportResourcePaths.h。

3.11 Scripting / Project Workflow

关键文件：

• editor/src/Scripting/EditorScriptAssemblyBuilder.h
• editor/src/Scripting/EditorScriptRuntimeStatus.h
• editor/src/Managers/ProjectManager.h
• editor/src/Managers/SceneManager.h
• editor/src/Utils/ProjectFileUtils.h

职责：

• 解析项目根目录、读写 Project.xcproject，并把仓库内 project/ 或 --project <path> 解析为当前工程。
• 驱动 Assets + .meta + Library 风格项目 workflow，包括项目资源浏览、脚本程序集重建入口和运行时状态反馈。
• 把项目脚本程序集与 editor/runtime 实际消费的 Library/ScriptAssemblies/ 目录连接起来。

边界：

• 与项目资产、.meta、Library、脚本程序集相关的问题，不应再按“editor 仍处于无工程状态”理解。
• ProjectManager、SceneManager、EditorScriptAssemblyBuilder 与引擎侧 ResourceManager / AssetImportService / ScriptEngine 是协作关系，不应在 panel 里各自复制一层状态机。

4. EventBus 使用规则

EventBus 现在主要承担两类职责：

• editor 范围的状态通知，例如 selection changed、entity created/deleted、scene changed。
• UI 请求类事件，例如 rename request、exit request、reset layout request。

推荐规则：

• “请求某个 panel 进入某种 UI 状态”时，优先用事件或共享 popup state。
• “真正修改数据”时，优先走 command，不要只发 event 期待别人去改数据。
• 事件用于解耦，不用于隐藏业务路径。

一个简单判断：

• 如果动作需要 undo/dirty，通常应该先有 Command。
• 如果动作只是让某个 panel 弹窗或进入 rename，通常可以只发 Event。

5. Undo / Dirty / Selection 约定

这是 editor 最容易再次失控的地方，必须保持统一：

• scene 数据修改通过 Commands 收口。
• UndoUtils::ExecuteSceneCommand(...) 负责把一次编辑包成可回退命令。
• inspector 连续拖拽这类交互，使用 interactive change 边界，不在 panel 里手搓多次提交。
• 场景切换、新建场景、加载场景后，selection 与 undo 历史由 scene command 统一重置。
• scene dirty 由 SceneManager 维护，保存成功后归零。

禁止事项：

• 不要在 panel 里直接偷偷 MarkSceneDirty() 来替代 command。
• 不要让某个 panel 自己保存一份 selection。
• 不要让快捷键直接跨过 command 改 manager。

6. 快捷键与菜单路由规则

当前 editor 已形成两条主路由：

• MainMenuActionRouter 负责 File / View / Help / global shortcut。
• EditActionRouter 负责 Edit 菜单和 panel-focused edit shortcut。

约定：

• Global 类快捷键由 menu bar 统一分发。
• Hierarchy / Project 等焦点相关动作，先根据 EditorActionRoute 解析目标，再执行对应 action。
• panel 只负责声明自己何时成为 active route，不负责重复实现整套 edit 菜单。

这样做的收益：

• 同一个动作不会再出现“菜单能点、快捷键失效、右键菜单又是另一套”的问题。
• 后续增加新 panel 的编辑语义时，只需要接入 route，不必复制整套菜单逻辑。

7. 当前已完成与明确暂缓的部分

已完成的重点：

• 统一 UI token、panel chrome、popup/property-grid/shared widgets。
• menu/shortcut/context menu/action 的大部分共享路由。
• scene/project/entity/component 的主要编辑命令收口。
• dock layout controller 与 editor workspace 装配。
• inspector 的 component editor registry 接入。
• editor 级回归测试基础框架与关键命令测试。
• Scene / Game viewport 已经重新接回当前正式主链：引擎 Rendering + RHI 离屏输出 -> ViewportHostService -> ImGui panel。
• Assets + .meta + Library 项目工作流、Project.xcproject、脚本程序集重建与脚本运行时状态已经进入 editor 正式工作流。
• viewport helper 已按 Chrome -> InteractionFrame -> Navigation -> TransformGizmoCoordinator -> ViewportHostService 显式拆层。

当前明确暂缓：

• 把 editor 主线程上残留的同步资源兜底点继续清理到更严格的异步消费模型。
• 把 Library bootstrap / scene streaming / explicit import 的状态模型继续正式化到 UI。
• 继续减少 panel 内局部瞬时状态与 helper 间重复规则。

原因很明确：

• 前三项已经不是“没接回来的未来工作”，而是已经落地、但还要继续收口的当前主线。

8. 后续新增功能时的落点原则

如果以后继续扩 editor，推荐按下面的判断落点：

• 新视觉样式或共享控件：放 UI
• 新菜单项/快捷键/右键菜单复用：放 Actions
• 新的 scene/project/component 编辑行为：放 Commands
• 新 inspector 组件面板：放 ComponentEditors
• 新 dock/window 布局控制：放 Layout
• 新 editor 全局状态：放 Core/Managers
• 新 viewport host / overlay / interaction helper：放 Viewport
• 只是把已有能力拼进某个窗口：放 Panels

如果一个功能不知道放哪，一般先问自己：

• 它是不是只关乎“怎么画”？
• 它是不是多个入口共享的交互？
• 它是不是会真正改数据并进入 undo？

这三个问题基本能把落点判断清楚。

9. 当前收尾阶段剩余事项

从 UI 架构角度看，当前已经不是“推倒重来”阶段，而是最后的封口阶段。剩余事项主要有：

• 继续压缩少量 panel 本地瞬时状态，能下沉的继续下沉。
• 继续补命令/路由回归测试，尤其是 inspector interactive undo 边界。
• 继续补 viewport helper、project workflow、script assembly builder 与 scene streaming 相关回归测试。
• 把 Library bootstrap、显式导入、后台 scene asset streaming 这三类状态在 editor UI 上分开表达。

结论：

editor 当前已经形成稳定分层，而且这套分层已经承接了真实的 viewport / project / scripting 工作流。后面再做功能迭代时，应坚持“先看边界，再落代码”，不要回到 panel 内部堆逻辑的旧路线。