107 lines
6.0 KiB
Markdown
107 lines
6.0 KiB
Markdown
# Editor
|
||
|
||
**命名空间**: `XCEngine::Editor`
|
||
|
||
**类型**: `app-module`
|
||
|
||
**描述**: XCEngine 独立编辑器应用层 API 文档入口，对应 `editor/src/**` 的模块结构，覆盖应用启动、上下文、面板、布局、命令、动作路由、视口基础设施、脚本工具链、UI 基础设施与 XCUI 过渡后端。
|
||
|
||
## 概述
|
||
|
||
这一组文档对应的不是 `engine/include/XCEngine/**` 那类“引擎公共运行时头文件”，而是编辑器应用本身的源码模块。换句话说，这里的 API 更接近“工具层架构说明”和“编辑器内部可复用接口”，而不是给游戏运行时代码直接依赖的稳定 SDK。
|
||
|
||
当前 Editor 的主链路可以概括为：
|
||
|
||
1. [Application](Application/Application.md)
|
||
启动 Win32 窗口、D3D12 窗口渲染器、ImGui 会话与编辑器上下文。
|
||
2. [Core](Core/Core.md)
|
||
组织事件总线、选择系统、撤销系统、场景与项目管理接口。
|
||
3. [Layers](Layers/Layers.md)
|
||
让 `EditorLayer` 承担编辑器工作区生命周期。
|
||
4. [Layout](Layout/Layout.md)
|
||
构建 dockspace、默认布局与工作区停靠关系。
|
||
5. [panels](panels/panels.md)
|
||
承载 Scene / Game / Hierarchy / Inspector / Console / Project 等主要工作面板。
|
||
6. [UI](UI/UI.md)
|
||
承载 Dear ImGui 上层的主题 token、chrome、树视图、属性布局和通用 widget。
|
||
7. [XCUIBackend](XCUIBackend/XCUIBackend.md)
|
||
承载 XCUI draw data 到当前 ImGui 宿主的过渡桥接层。
|
||
8. [Viewport](Viewport/Viewport.md)
|
||
承载 Scene / Game 视口宿主、对象 picking、overlay 与 gizmo 交互基础设施。
|
||
9. [Scripting](Scripting/Scripting.md)
|
||
承载编辑器侧脚本程序集重建与脚本运行时状态反馈。
|
||
|
||
## 架构定位
|
||
|
||
从架构视角看，`Editor` 模块解决的是“如何把引擎运行时能力组织成一个可编辑、可观察、可操作的工具应用”。
|
||
|
||
这和商业游戏引擎的常见分层非常一致：
|
||
|
||
- 引擎运行时负责场景、组件、渲染、资源和脚本能力。
|
||
- 编辑器应用负责把这些能力包装成面板、命令、菜单、工作区与交互流。
|
||
|
||
因此阅读这套文档时，最重要的前置认知是：Editor 层的很多接口是为工具体验服务的，它们允许比运行时 API 更强的耦合、更明确的 UI 约束和更直接的产品导向。
|
||
|
||
## 当前重构重点
|
||
|
||
结合当前 `editor/src` 的实现，Editor 文档当前有几个结构上非常重要的重构点：
|
||
|
||
- `UI.h` 现在明确作为 umbrella header 处理，其职责是聚合常用 UI helper，而不是声明新的运行时类型。
|
||
- `TreeView`、`PropertyLayout`、`BuiltInIcons`、`DockTabBarChrome` 等新基础设施已经成为多个面板共享的 UI 基建。
|
||
- `HierarchyPanel` 和 `ProjectPanel` 的实现已经明显转向“面板只负责呈现与路由，动作层 / 命令层负责执行业务”的分层。
|
||
|
||
这意味着 Editor 文档不能只做目录映射，还必须解释这些共享基础设施为什么存在、它们如何把编辑器代码从面板私有技巧提升为稳定的产品层模式。
|
||
|
||
## 聚合与辅助文件
|
||
|
||
并不是 `editor/src/**` 下每个文件都值得成为单独 API 页。当前有几类文件更适合在模块页说明：
|
||
|
||
- `editor/src/UI/UI.h`
|
||
这是 UI 子模块的 umbrella header，文档并入 [UI](UI/UI.md)。
|
||
- `editor/src/EditorApp.rc`、`editor/src/main.cpp`
|
||
属于应用启动与资源清单支撑文件，不是面向上层复用的编辑器 API。
|
||
|
||
这种处理方式符合当前文档规范：只有真正承担模块职责或可复用契约的文件才进入 canonical API 树；纯资源声明和应用入口支撑文件优先并入模块说明。
|
||
|
||
## 当前实现边界
|
||
|
||
- 当前编辑器主路径仍然以 Windows + D3D12 + Dear ImGui 为核心。
|
||
- 这套代码整体属于应用层源码，不应误解为已经整理成稳定插件 SDK。
|
||
- 自动审计脚本现在同时覆盖 `engine/include/XCEngine/**` 与 `new_editor/include/XCEditor/**` 的 public headers；`docs/api/XCEngine/Editor/**` 这组 source-backed 文档仍更依赖目录并行约束、链接校验和人工核对源码行为。
|
||
|
||
## 文档边界更新（2026-04-10）
|
||
|
||
- `docs/api/XCEngine/Editor/**` 当前严格对应旧 `editor/src/**`。
|
||
- `docs/api/XCEditor/**` 现在单独对应 `new_editor/include/XCEditor/**` 的新 Editor 基础层 public headers。
|
||
- `new_editor/app/**` 与 `new_editor/ui/**` 属于宿主与产品装配层，不并入这棵 public-header canonical 树。
|
||
|
||
## 目录
|
||
|
||
- [Application](Application/Application.md) - 顶层编辑器应用入口。
|
||
- [Actions](Actions/Actions.md) - 菜单、快捷键、按钮动作绑定与路由。
|
||
- [Commands](Commands/Commands.md) - 面向场景与项目操作的命令封装。
|
||
- [ComponentEditors](ComponentEditors/ComponentEditors.md) - 组件编辑器注册与实现。
|
||
- [Core](Core/Core.md) - 上下文、事件、撤销、选择与基础接口。
|
||
- [EditorResources](EditorResources/EditorResources.md) - Windows 资源脚本使用的资源 id。
|
||
- [Layers](Layers/Layers.md) - 编辑器 layer 封装。
|
||
- [Layout](Layout/Layout.md) - Dock 布局控制。
|
||
- [Managers](Managers/Managers.md) - 项目和场景管理实现。
|
||
- [panels](panels/panels.md) - 主要工作面板。
|
||
- [Platform](Platform/Platform.md) - Win32 宿主与 D3D12 窗口渲染路径。
|
||
- [Scripting](Scripting/Scripting.md) - Editor 侧脚本程序集构建与状态反馈。
|
||
- [Theme](Theme/Theme.md) - 顶层主题入口。
|
||
- [UI](UI/UI.md) - Editor UI 基础设施。
|
||
- [XCUIBackend](XCUIBackend/XCUIBackend.md) - XCUI 到 ImGui 的过渡后端。
|
||
- [Utils](Utils/Utils.md) - 场景编辑与撤销相关辅助函数。
|
||
- [Viewport](Viewport/Viewport.md) - Scene / Game 视口宿主、overlay 与 gizmo 基础设施。
|
||
|
||
## 相关文档
|
||
|
||
- [XCEngine](../XCEngine.md)
|
||
- [Scene](../Scene/Scene.md)
|
||
- [Components](../Components/Components.md)
|
||
- [Rendering](../Rendering/Rendering.md)
|
||
- [XCEditor](../../XCEditor/XCEditor.md)
|
||
- [Editor Architecture And Workflow](../../_guides/Editor/Editor-Architecture-And-Workflow.md)
|
||
- [API 总索引](../../main.md)
|