docs: sync api and planning docs

2026-04-08 16:07:03 +08:00
parent 08c3278e10
commit 31756847ab
1826 changed files with 44502 additions and 29645 deletions
--- a/docs/api/_guides/Editor/Editor-Architecture-And-Workflow.md
+++ b/docs/api/_guides/Editor/Editor-Architecture-And-Workflow.md
@@ -2,152 +2,354 @@

 ## 先建立正确心智模型

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

-可以把当前架构粗略理解成六层：
+当前这套 Editor 已经不是“只有窗口壳和几块早期 ImGui 面板”的状态。按 `editor/src/**`、`project/` 和当前脚本程序集目录来看，它已经形成了一条真实闭环：

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

-`panels`、`Layout` 和 `ComponentEditors` 则横向挂在这些层之间：
+同时还和项目目录结构直接对接：

- `panels` 是用户直接看到的编辑器窗口
- `Layout` 决定这些窗口如何 Dock
- `ComponentEditors` 决定 Inspector 如何按组件类型渲染
+- `Project.xcproject`
+- `Assets/`
+- `.meta`
+- `Library/SourceAssetDB`
+- `Library/ArtifactDB`
+- `Library/Artifacts`
+- `Library/ScriptAssemblies`

-## 为什么要拆成 Actions 和 Commands
+因此这组文档的重点，不是“介绍一个理想中的未来编辑器”，而是解释当前 checkout 下这条链路已经怎么工作。

-这是当前 Editor 文档里最重要的一条设计线。  
-如果不拆，最常见的退化就是：
+## 顶层宿主是怎样启动的

- 菜单栏自己写一套保存逻辑
- 快捷键自己写一套删除逻辑
- 右键菜单再写一套复制粘贴逻辑
+[Application](../../XCEngine/Editor/Application/Application.md) 是编辑器进程的组合根。

-时间一长，你会得到三个入口、三份行为、三种 bug。
+它的启动顺序大致是：

-当前实现把它拆成：
+1. 安装崩溃过滤器并把日志重定向到可执行目录。
+2. 通过 `ResolveEditorProjectRootUtf8()` 解析项目根目录。
+3. 若命令行带 `--project` 或 `-p`，优先使用覆盖路径。
+4. 否则在工作目录或可执行目录向上查找 workspace 根，再优先落到 `<workspace>/project/`。
+5. 初始化主窗口渲染器、`ResourceManager`、`EditorContext`、脚本运行时、ImGui 和 `ViewportHostService`。
+6. 最后挂接 `EditorLayer`，开始每帧驱动。

- `EditorActions` 定义动作名称、快捷键和启用状态
- `ActionRouting` 和 `EditorActionRoute` 决定当前动作应该作用在哪个面板上下文
- `*ActionRouter` 负责具体入口的 UI 交互
- `Commands` 负责真正修改状态
+这里最关键的一点是：项目根目录不是由某个面板临时决定，而是宿主层在启动时统一解析并固定下来。当前仓库默认就是随仓维护的 `project/` 示例工程。

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

-## 为什么 Inspector 不走完全反射，而是组件专用 editor
+可以把当前实现理解成六层。

-当前 Inspector 采用的是：
+### 1. 宿主层

- `IComponentEditor`
- `ComponentEditorRegistry`
- `TransformComponentEditor`
- `CameraComponentEditor`
- `LightComponentEditor`
+- `Application`
+- `Platform`
+- `D3D12WindowRenderer`
+- `ImGuiBackendBridge`
+- `ImGuiSession`

-这条路线更接近 Unity 的 custom inspector / property drawer 思想，而不是“把所有字段自动反射成一张表”。
+这一层负责窗口、SwapChain、ImGui 帧边界、项目切换和脚本运行时重载。它不直接实现 Hierarchy、Inspector 或 Project Browser 的业务规则。

-这样做的好处是：
+### 2. 上下文与共享服务层

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

-代价是：
+`EditorContext` 是当前 Editor 的状态容器。它把事件、选择、场景、项目、撤销和 `ViewportHostService` 指针聚合起来，供面板和动作层统一访问。

- 每个组件都要写专门 editor
- 通用自动化程度较低
+### 3. 面板与布局层

-但对当前阶段的编辑器，这是更稳妥的商业级做法，因为它优先保证可解释性和可维护性。
+- `PanelCollection`
+- `HierarchyPanel`
+- `ProjectPanel`
+- `InspectorPanel`
+- `SceneViewPanel`
+- `GameViewPanel`
+- `ConsolePanel`

-## 从一次用户点击看整条链路
+这一层负责“用户看到什么”，以及把即时模式 UI 交互采样成更稳定的意图。

-以 Hierarchy 中“右键删除实体”为例，当前主路径大致是：
+其中 `GameViewPanel` 还有一条额外职责：它会把视口里的键鼠状态采样成 `GameViewInputFrameEvent`，再通过 `PlaySessionController` 桥接到运行时 `InputManager`。这一条链路可以单独看：

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

-这条链路说明了一个核心原则：  
-面板不应该直接修改场景，面板应该只描述用户意图。
+### 4. 动作与命令层

-## 为什么当前大量使用小型 helper header
+- `Actions::*ActionRouter`
+- `Commands::*`

-很多用户第一次看会觉得：为什么 `UI`、`Actions`、`Commands` 下有这么多小头文件？
+这层负责把“菜单点击、快捷键、右键菜单、拖放、行内重命名”翻译成统一的编辑语义。典型例子是：

-这是 Dear ImGui 风格编辑器常见的工程取舍。原因很现实：
+- `HierarchyActionRouter`
+- `EntityCommands`
+- `ProjectCommands`

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

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

-## 当前架构最像 Unity 的部分
+它把 Scene/Game 视口真正接到引擎的 `Rendering + RHI` 上，同时承接 object-id picking、outline、grid 和世界空间 overlay。

- `HierarchyPanel / ProjectPanel / InspectorPanel / ConsolePanel` 这组窗口组合很像 Unity Editor 的基本工作区。
- `ComponentEditors` 很像 Unity 的 custom inspector。
- `SceneCommands + UndoManager` 很像 Unity 编辑态里对场景对象做结构修改时的命令路径。
+### 6. 引擎与资源层

-## 当前又明显还不像 Unity 的地方
+- `Rendering`
+- `ResourceManager`
+- `AssetDatabase`
+- `ScriptEngine`
+- `MonoScriptRuntime`

- 当前只有 Windows + D3D12 + ImGui 主路径。
- Project 面板还不是完整资产导入系统。
- Inspector 还没有脚本组件、搜索式 Add Component、批量多选混合值等成熟体验。
- Console 还是轻量列表，不是完整诊断中心。
+这一层不属于 Editor 自身，但 Editor 当前已经大量依赖它们提供真实能力，而不是自己维护一套独立“简化版运行时”。

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

-## 如果你要继续扩展这个编辑器，推荐从哪层下手
+很多旧文档容易忽略 [EditorActionRoute](../../XCEngine/Editor/Core/EditorActionRoute/EditorActionRoute.md)，但它对当前 Inspector 和焦点行为非常关键。

-### 新增一个全新面板
+当前只有三个 route：

-通常顺序是：
+- `None`
+- `Hierarchy`
+- `Project`

-1. 在 `panels` 下建立新 Panel 类型。
-2. 优先复用 `PanelWindowScope / PanelToolbarScope / PanelContentScope`。
-3. 如果面板需要上下文敏感快捷键，再接入 `ActionRouting`。
-4. 如果面板要真正修改数据，优先写 `Commands`，不要直接改 manager。
+这不是菜单状态，而是“最近一次明确的编辑焦点来自哪里”。

-### 给 Inspector 新增一个组件编辑器
+它直接影响 [InspectorPanel](../../XCEngine/Editor/panels/InspectorPanel/InspectorPanel.md) 的检查对象：

-推荐顺序是：
+- route 是 `Hierarchy` 时，优先检查当前选中实体。
+- route 是 `Project` 时，优先检查当前选中资源。
+- 当前只有 `Material` 资源拥有专用 inspector；其他资源走 unsupported fallback。

-1. 实现新的 `IComponentEditor`。
-2. 在 `ComponentEditorRegistry` 注册。
-3. 优先通过 `PropertyGrid`、`ScalarControls`、`VectorControls` 组装 UI。
-4. 涉及结构性变化时，通过 `ComponentCommands` 或新的命令 helper 进入撤销链。
+所以 Inspector 现在已经不是“只给 GameObject 用”的面板，而是一个带 subject 切换能力的通用检查器。

-### 给菜单栏或快捷键新增动作
+## 一条典型的 Hierarchy 链路

-推荐顺序是：
+以“在 Hierarchy 中重命名实体”为例，当前真实链路大致是：

-1. 在 `EditorActions` 中先定义动作描述。
-2. 在合适的 `*ActionRouter` 中接 UI 入口。
-3. 真实变更落到 `Commands`。
-4. 如果动作取决于当前焦点面板，再考虑是否需要新的 `EditorActionRoute`。
+1. `HierarchyPanel` 绘制树节点和行内编辑框。
+2. [HierarchyActionRouter](../../XCEngine/Editor/Actions/HierarchyActionRouter/HierarchyActionRouter.md) 负责解释点击、右键、拖放和 rename 请求。
+3. `RequestEntityRename(...)` 通过 [EventBus](../../XCEngine/Editor/Core/EventBus/EventBus.md) 发布 `EntityRenameRequestedEvent`。
+4. 行内编辑结束后，`CommitEntityRename(...)` 调用 [EntityCommands](../../XCEngine/Editor/Commands/EntityCommands/EntityCommands.md)。
+5. `EntityCommands::RenameEntity(...)` 通过 `UndoUtils::ExecuteSceneCommand(...)` 进入撤销栈。
+6. `SceneManager` 完成真正的场景修改。
+7. 其他面板通过选择状态或事件观察到变化。

-## 当前文档应该怎么读
+这条链路体现了当前 editor 的一个硬边界：

-如果你是第一次接触这一套代码，推荐按这个顺序：
+- 面板负责呈现和采样。
+- router 负责交互语义。
+- commands 负责稳定的编辑命令。
+- manager 负责真正的数据结构修改。
+
+## 一条典型的 Project 链路
+
+[ProjectPanel](../../XCEngine/Editor/panels/ProjectPanel/ProjectPanel.md) 不是 `AssetDatabase` 本身，而是 `IProjectManager` 的浏览器前端。
+
+当前它的主链路是：
+
+1. 左侧目录树用 `TreeView` 绘制 folder hierarchy。
+2. 右侧浏览区用 `DrawAssetTile(...)` 绘制当前目录条目。
+3. 顶部工具栏只做当前目录内搜索，不做全项目索引。
+4. 面包屑通过 `NavigateToIndex(...)` 回退到任意路径段。
+5. 重命名、创建文件夹、创建材质、移动资源、删除资源都交给 `ProjectCommands`。
+6. 打开资源、开始拖拽、背景点击等交互交给 `Actions` 层 helper。
+
+因此当前 `ProjectPanel` 的定位很清楚：
+
+- 它负责浏览和编辑入口。
+- 它不自己维护资源数据库。
+- 它依赖 project manager 和命令层维持真实状态。
+
+还要建立一个新的工作流边界认知：
+
+- Project 面板负责资源浏览与资源级编辑
+- 项目级保存和脚本程序集重建仍由主菜单触发
+- 旧文档里提到的场景资源批量迁移入口已经不在当前 editor 工作流中
+
+## Inspector 已经不只是组件列表
+
+[InspectorPanel](../../XCEngine/Editor/panels/InspectorPanel/InspectorPanel.md) 现在至少有四种 subject mode：
+
+- `None`
+- `GameObject`
+- `MaterialAsset`
+- `UnsupportedAsset`
+
+### GameObject 模式
+
+这一支仍然是最传统的 Inspector：
+
+- 遍历实体组件列表。
+- 通过 `ComponentEditorRegistry` 找到对应 `IComponentEditor`。
+- 用 `BeginComponentSection(...)` 组织 section UI。
+- 组件 editor 返回 `true` 时，标记场景 dirty。
+- `Add Component` 弹窗走 `DeferredPopupState` 和 `Actions` helper。
+
+### Material 资源模式
+
+这一支是旧文档最容易写错的地方。当前实现已经支持直接检查材质资源：
+
+- 从 `ProjectManager` 取当前选中的 `AssetItem`。
+- 仅当 `item->type == "Material"` 时进入专用 inspector。
+- 通过项目相对路径调用 `ResourceManager::Load<Material>()`。
+- 当前可编辑：
+  - Shader 路径
+  - Shader Pass
+  - Render Queue
+  - Render State
+  - Tags
+- 每次修改都会立刻写回材质文件，并尽量把变更同步到已加载的 `Material` 资源实例。
+
+所以现在 Inspector 已经承担了一部分资源编辑器职责，而不是单纯的 scene component inspector。
+
+### ScriptComponent 不是缺席状态
+
+旧表述里常见“Inspector 还没有脚本组件”之类的说法，但当前这已经不成立。
+
+[ScriptComponentEditor](../../XCEngine/Editor/ComponentEditors/ScriptComponentEditor/ScriptComponentEditor.md) 已经接入当前 Inspector 链路，支持：
+
+- 脚本类选择
+- 字段模型读取
+- 字段 override 写回
+- 运行时缺失 / 程序集缺失状态提示
+- `Rebuild Scripts` / `Reload Scripts` 入口
+
+## 脚本程序集链路已经落地
+
+当前脚本相关的关键目录是：
+
+- `managed/XCEngine.ScriptCore/`
+- `managed/GameScripts/`
+- `project/Assets/**/*.cs`
+- `project/Library/ScriptAssemblies/`
+
+[Application](../../XCEngine/Editor/Application/Application.md) 在启动、切换项目和显式 reload 时，都会把脚本程序集目录固定到：
+
+- `<Project>/Library/ScriptAssemblies/XCEngine.ScriptCore.dll`
+- `<Project>/Library/ScriptAssemblies/GameScripts.dll`
+- `<Project>/Library/ScriptAssemblies/mscorlib.dll`
+
+若程序集缺失：
+
+- Editor 不会直接崩溃。
+- `ScriptEngine` runtime 会被清空。
+- `ScriptRuntimeStatus` 会保留错误消息，供 Inspector 和其他 UI 展示。
+
+若用户触发 `RebuildScriptingAssemblies()`：
+
+1. `EditorScriptAssemblyBuilder` 重建项目程序集。
+2. 成功后立即 `ReloadScriptingRuntime()`。
+3. 新 runtime 会重新注册到 `ScriptEngine`。
+
+这条链路说明当前脚本系统已经进入“编辑器真实工作流的一部分”，而不是实验性质的旁路功能。
+
+## 视口链路也已经从面板里抽出来了
+
+旧版 editor 很容易把 SceneView 相关逻辑直接堆进面板文件里，但当前实现已经明显走向规范化。
+
+按当前结构，典型流程是：
+
+1. `Application::Render()` 建立主帧边界。
+2. `LayerStack` 和具体面板产生 Scene / Game 视口请求。
+3. `ViewportHostService::BeginFrame()` 清理并准备本帧视口状态。
+4. `RenderRequestedViewports(...)` 真正调用引擎 `SceneRenderer`。
+5. Scene View 额外接入：
+   - 编辑器私有相机
+   - object-id surface
+   - outline
+   - grid
+   - `SceneViewportOverlayProviders`
+   - `SceneViewportOverlayBuilder`
+   - `SceneViewportEditorOverlayPass`
+
+这意味着：
+
+- editor 是渲染宿主，不是第二套 renderer。
+- 新的 Scene overlay / gizmo 功能应优先沿 `overlay provider -> overlay builder -> overlay pass` 扩展。
+- 不应再把世界空间绘制逻辑继续回堆到 `SceneViewPanel` 的临时 ImGui 路径。
+
+更细一层的 Scene View 输入仲裁、pivot / center、global / local、HUD/world overlay 分层以及 gizmo overlay state 传播关系，可继续看 [SceneView Interaction And Gizmo Model](SceneView-Interaction-And-Gizmo-Model.md)。
+
+## 当前项目目录结构不是“伪工作流”
+
+当前工程目录的几个部分都已经参与真实工作流：
+
+- `project/Assets/`
+- `project/Assets.meta`
+- `project/Library/`
+- `project/Library/ScriptAssemblies/`
+- `Project.xcproject`
+
+尤其是 `project/Library/`，在当前实现里并不只是可以无脑忽略的临时目录。它至少承接：
+
+- 资源数据库缓存
+- artifact 缓存
+- 脚本程序集输出
+
+因此在 editor 文档里，不应再把 `.meta` 和 `Library/` 描述成“未来才会用到”的规划项。
+
+## 如果要继续扩展当前 Editor，应该从哪层下手
+
+### 新增一个面板
+
+优先顺序通常是：
+
+1. 在 `panels/` 下新建 panel。
+2. 复用已有 `PanelWindowScope`、`PanelToolbarScope`、`PanelContentScope`。
+3. 若面板要参与焦点切换，再接 `EditorActionRoute`。
+4. 若面板会修改项目或场景，优先接命令层而不是直改 manager。
+
+### 给 Inspector 新增一种检查对象
+
+优先顺序通常是：
+
+1. 先确认新的 subject 应由哪条 route 驱动。
+2. 在 `InspectorPanel::SyncSubject()` 里定义切换条件。
+3. 为该资源或组件准备独立渲染函数。
+4. 若涉及文件写回或场景写回，尽量复用现有 `Commands` / `ResourceManager` / `ScriptEngine`。
+
+### 给 Hierarchy / Project 增加新动作
+
+优先顺序通常是：
+
+1. 在 `Actions` 层描述入口。
+2. 在 router 里解释 UI 交互。
+3. 在 `Commands` 层集中写实际修改逻辑。
+4. 需要后续 UI 同步时，再通过 `EventBus` 发布事件。
+
+## 现在不该再沿用的旧说法
+
+以下说法已经不再适合当前活跃文档：
+
+- “Project 面板还不是完整资产导入系统”
+- “Inspector 还没有脚本组件”
+- “Editor 仍然只是轻量编辑器壳层”
+- “脚本程序集和项目目录结构还在规划中”
+
+更准确的描述应当是：
+
+- 当前 Editor 仍在持续重构，但主链路已经真实落地。
+- 高层结构已经能覆盖项目根目录解析、资源浏览、材质资源检查、脚本程序集重建与重载、Scene/Game 视口宿主和 object-id picking。
+- 接下来的工作重点是继续把这些现有能力文档化、模块化，而不是再把它描述成只有方向没有实现的雏形。
+
+## 推荐阅读顺序
+
+如果要快速建立当前 Editor 的整体认识，推荐按这个顺序读：

 1. [Editor](../../XCEngine/Editor/Editor.md)
 2. [Application](../../XCEngine/Editor/Application/Application.md)
-3. [Core](../../XCEngine/Editor/Core/Core.md)
-4. [Actions](../../XCEngine/Editor/Actions/Actions.md)
-5. [Commands](../../XCEngine/Editor/Commands/Commands.md)
-6. [panels](../../XCEngine/Editor/panels/panels.md)
-7. [ComponentEditors](../../XCEngine/Editor/ComponentEditors/ComponentEditors.md)
-8. [UI](../../XCEngine/Editor/UI/UI.md)
+3. [EventBus](../../XCEngine/Editor/Core/EventBus/EventBus.md)
+4. [ProjectPanel](../../XCEngine/Editor/panels/ProjectPanel/ProjectPanel.md)
+5. [InspectorPanel](../../XCEngine/Editor/panels/InspectorPanel/InspectorPanel.md)
+6. [HierarchyActionRouter](../../XCEngine/Editor/Actions/HierarchyActionRouter/HierarchyActionRouter.md)
+7. [EntityCommands](../../XCEngine/Editor/Commands/EntityCommands/EntityCommands.md)
+8. [ViewportHostService](../../XCEngine/Editor/Viewport/ViewportHostService/ViewportHostService.md)
+9. [SceneView Interaction And Gizmo Model](SceneView-Interaction-And-Gizmo-Model.md)
+10. [ScriptComponentEditor](../../XCEngine/Editor/ComponentEditors/ScriptComponentEditor/ScriptComponentEditor.md)

-这能让你先看清系统骨架，再下钻到具体类型页，而不是一开始就陷进某个 helper 文件里。
+这样读下来，基本就能把“宿主层、共享状态、面板、动作命令、视口和脚本”这几条主线拼起来。