XCEngine/docs/api/_guides/Editor/Editor-Architecture-And-Workflow.md

Editor Architecture And Workflow

先建立正确心智模型

docs/api/XCEngine/Editor/** 对应的是编辑器应用层，而不是引擎运行时 public API。
它更接近 Unity Editor、Unreal Editor 这类“工具壳层”的实现文档，而不是给游戏逻辑直接链接的稳定 SDK。

可以把当前架构粗略理解成六层：

1. Platform 负责 Win32 进程、窗口消息、崩溃日志和 D3D12 窗口渲染。
2. UI 负责 ImGui 会话、主题、面板 chrome 和通用控件。
3. Core 负责上下文、事件总线、动作路由、选择和撤销。
4. Managers 负责项目和场景服务的默认实现。
5. Actions 负责把按钮、菜单和快捷键翻译成“可执行动作”。
6. Commands 负责真正修改项目、场景、实体和组件状态。

panels、Layout 和 ComponentEditors 则横向挂在这些层之间：

• panels 是用户直接看到的编辑器窗口
• Layout 决定这些窗口如何 Dock
• ComponentEditors 决定 Inspector 如何按组件类型渲染

为什么要拆成 Actions 和 Commands

这是当前 Editor 文档里最重要的一条设计线。
如果不拆，最常见的退化就是：

• 菜单栏自己写一套保存逻辑
• 快捷键自己写一套删除逻辑
• 右键菜单再写一套复制粘贴逻辑

时间一长，你会得到三个入口、三份行为、三种 bug。

当前实现把它拆成：

• EditorActions 定义动作名称、快捷键和启用状态
• ActionRouting 和 EditorActionRoute 决定当前动作应该作用在哪个面板上下文
• *ActionRouter 负责具体入口的 UI 交互
• Commands 负责真正修改状态

这就是商业编辑器很常见的分层方式。Unity 用户会很容易理解这件事：
菜单项、快捷键和 Inspector 按钮看起来入口不同，但背后应该落到同一条编辑命令语义上。

为什么 Inspector 不走完全反射，而是组件专用 editor

当前 Inspector 采用的是：

• IComponentEditor
• ComponentEditorRegistry
• TransformComponentEditor
• CameraComponentEditor
• LightComponentEditor

这条路线更接近 Unity 的 custom inspector / property drawer 思想，而不是“把所有字段自动反射成一张表”。

这样做的好处是：

• 条件式 UI 更自然，例如 Camera 的透视/正交分支
• 撤销、字段分组和按钮布局更可控
• 组件编辑体验可以按照组件语义而不是成员变量顺序组织

代价是：

• 每个组件都要写专门 editor
• 通用自动化程度较低

但对当前阶段的编辑器，这是更稳妥的商业级做法，因为它优先保证可解释性和可维护性。

从一次用户点击看整条链路

以 Hierarchy 中“右键删除实体”为例，当前主路径大致是：

1. HierarchyPanel 负责渲染树和弹出上下文菜单。
2. HierarchyActionRouter 负责把“Delete”菜单项映射为删除动作。
3. EntityCommands::DeleteEntity 负责发起真正的场景修改。
4. UndoUtils 和 UndoManager 负责录制撤销快照。
5. SceneManager 负责真正删除实体并发布事件。
6. SelectionManager、InspectorPanel 等其它系统通过事件感知更新。

这条链路说明了一个核心原则：
面板不应该直接修改场景，面板应该只描述用户意图。

为什么当前大量使用小型 helper header

很多用户第一次看会觉得：为什么 UI、Actions、Commands 下有这么多小头文件？

这是 Dear ImGui 风格编辑器常见的工程取舍。原因很现实：

• 即时模式 UI 很容易把一切都塞进 Render()
• 一旦不拆 helper，单个面板 cpp 会迅速膨胀
• 把“交互语义”“控件语义”“状态容器”拆成小头文件后，代码更容易复用和迁移

所以这些 header 不是“碎片化设计”，而是在对抗 UI 工具代码天然容易失控的问题。

当前架构最像 Unity 的部分

• HierarchyPanel / ProjectPanel / InspectorPanel / ConsolePanel 这组窗口组合很像 Unity Editor 的基本工作区。
• ComponentEditors 很像 Unity 的 custom inspector。
• SceneCommands + UndoManager 很像 Unity 编辑态里对场景对象做结构修改时的命令路径。

当前又明显还不像 Unity 的地方

• 当前只有 Windows + D3D12 + ImGui 主路径。
• Project 面板还不是完整资产导入系统。
• Inspector 还没有脚本组件、搜索式 Add Component、批量多选混合值等成熟体验。
• Console 还是轻量列表，不是完整诊断中心。

所以更准确的表述应该是：
它采用了很多 Unity 风格的编辑器设计理念，但当前实现仍然是一个处在快速重构期的、轻量但方向正确的编辑器壳层。

如果你要继续扩展这个编辑器，推荐从哪层下手

新增一个全新面板

通常顺序是：

1. 在 panels 下建立新 Panel 类型。
2. 优先复用 PanelWindowScope / PanelToolbarScope / PanelContentScope。
3. 如果面板需要上下文敏感快捷键，再接入 ActionRouting。
4. 如果面板要真正修改数据，优先写 Commands，不要直接改 manager。

给 Inspector 新增一个组件编辑器

推荐顺序是：

1. 实现新的 IComponentEditor。
2. 在 ComponentEditorRegistry 注册。
3. 优先通过 PropertyGrid、ScalarControls、VectorControls 组装 UI。
4. 涉及结构性变化时，通过 ComponentCommands 或新的命令 helper 进入撤销链。

给菜单栏或快捷键新增动作

推荐顺序是：

1. 在 EditorActions 中先定义动作描述。
2. 在合适的 *ActionRouter 中接 UI 入口。
3. 真实变更落到 Commands。
4. 如果动作取决于当前焦点面板，再考虑是否需要新的 EditorActionRoute。

当前文档应该怎么读

如果你是第一次接触这一套代码，推荐按这个顺序：

1. Editor
2. Application
3. Core
4. Actions
5. Commands
6. panels
7. ComponentEditors
8. UI

这能让你先看清系统骨架，再下钻到具体类型页，而不是一开始就陷进某个 helper 文件里。