chore: sync workspace state
This commit is contained in:
@@ -4,51 +4,86 @@
|
||||
|
||||
**类型**: `app-module`
|
||||
|
||||
**描述**: 编辑器应用层 API 文档入口，镜像 `editor/src` 的目录结构，覆盖编辑器启动、上下文、面板工作区、项目浏览、场景编辑与 UI 基础设施。
|
||||
**描述**: XCEngine 独立编辑器应用层 API 文档入口，对应 `editor/src/**` 的模块结构，覆盖应用启动、上下文、面板、布局、命令、动作路由与 UI 基础设施。
|
||||
|
||||
## 概述
|
||||
|
||||
这一组文档对应的不是 `engine/include/XCEngine` 的 public engine headers，而是独立编辑器应用 `editor/src/**`。
|
||||
这一组文档对应的不是 `engine/include/XCEngine/**` 那类“引擎公共运行时头文件”，而是编辑器应用本身的源码模块。换句话说，这里的 API 更接近“工具层架构说明”和“编辑器内部可复用接口”，而不是给游戏运行时代码直接依赖的稳定 SDK。
|
||||
|
||||
因此这里需要先建立一个正确心智模型：
|
||||
当前 Editor 的主链路可以概括为：
|
||||
|
||||
- `XCEngine` 引擎模块负责运行时系统。
|
||||
- `Editor` 模块负责围绕这些运行时系统搭建编辑器应用。
|
||||
- 它更接近“应用层/工具层 API”，而不是给游戏代码直接依赖的稳定引擎 ABI。
|
||||
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。
|
||||
|
||||
当前编辑器的主链路大致是：
|
||||
## 架构定位
|
||||
|
||||
1. [Application](Application/Application.md) 启动 Win32 窗口、D3D12 窗口渲染器和 ImGui 会话。
|
||||
2. [Core::EditorContext](Core/EditorContext/EditorContext.md) 组装事件总线、场景管理、项目管理、选择管理和撤销系统。
|
||||
3. [Layers::EditorLayer](Layers/EditorLayer/EditorLayer.md) 承载编辑器工作区生命周期。
|
||||
4. [Core::EditorWorkspace](Core/EditorWorkspace/EditorWorkspace.md) 组织菜单、层级、场景视图、GameView、Inspector、Console 和 Project 等面板。
|
||||
从架构视角看，`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/EditorResources.h`
|
||||
当前只定义了 `IDI_APP_ICON 101`，用于 `EditorApp.rc` 的资源 id 绑定，更适合作为 Editor 应用资源入口说明，而不是独立类型页。
|
||||
- `editor/src/EditorApp.rc`、`editor/src/main.cpp`
|
||||
属于应用启动与资源清单支撑文件，不是面向上层复用的编辑器 API。
|
||||
|
||||
这种处理方式符合当前文档规范：只有真正承担模块职责或可复用契约的文件才进入 canonical API 树；纯资源声明和应用入口支撑文件优先并入模块说明。
|
||||
|
||||
## 当前实现边界
|
||||
|
||||
- 当前编辑器主要是 Windows + D3D12 + ImGui 路径。
|
||||
- 这组代码整体是应用层源码，不像 engine public headers 那样已经完全按稳定 SDK 方式整理。
|
||||
- 当前文档页会优先标注 `源文件`，而不是 `头文件`，以反映它们来自 `editor/src/**`。
|
||||
- 当前自动审计脚本仍以 `engine/include/XCEngine` 为主，因此 `Editor` 这组页主要靠链接完整性和人工结构约束维护。
|
||||
- 当前编辑器主路径仍然以 Windows + D3D12 + Dear ImGui 为核心。
|
||||
- 这套代码整体属于应用层源码，不应误解为已经整理成稳定插件 SDK。
|
||||
- 自动审计脚本目前主要覆盖 `engine/include/XCEngine/**` 的 public headers；Editor 这组文档更依赖目录并行约束、链接校验和人工核对源码行为。
|
||||
|
||||
## 目录
|
||||
|
||||
- [Application](Application/Application.md) - 顶层编辑器应用入口。
|
||||
- [Theme](Theme/Theme.md) - 顶层主题入口。
|
||||
- [Core](Core/Core.md) - 上下文、事件、撤销、选择与基础数据结构。
|
||||
- [Managers](Managers/Managers.md) - 项目与场景管理实现。
|
||||
- [panels](panels/panels.md) - 编辑器面板基础设施。
|
||||
- [Actions](Actions/Actions.md) - 菜单、快捷键、按钮动作绑定与路由。
|
||||
- [Commands](Commands/Commands.md) - 面向场景与项目操作的命令封装。
|
||||
- [ComponentEditors](ComponentEditors/ComponentEditors.md) - 组件编辑器注册与实现。
|
||||
- [Core](Core/Core.md) - 上下文、事件、撤销、选择与基础接口。
|
||||
- [Layers](Layers/Layers.md) - 编辑器 layer 封装。
|
||||
- [Platform](Platform/Platform.md) - Win32 窗口宿主与 D3D12 窗口渲染器。
|
||||
- [UI](UI/UI.md) - ImGui 会话与编辑器 UI 基础设施。
|
||||
- [Actions](Actions/Actions.md) - 菜单/按钮/快捷键动作绑定与路由层。
|
||||
- [Commands](Commands/Commands.md) - 面向场景与项目操作的高层命令封装。
|
||||
- [ComponentEditors](ComponentEditors/ComponentEditors.md) - 组件属性编辑器注册与实现层。
|
||||
- [Layout](Layout/Layout.md) - Dock 布局控制。
|
||||
- [Managers](Managers/Managers.md) - 项目和场景管理实现。
|
||||
- [panels](panels/panels.md) - 主要工作面板。
|
||||
- [Platform](Platform/Platform.md) - Win32 宿主与 D3D12 窗口渲染路径。
|
||||
- [Theme](Theme/Theme.md) - 顶层主题入口。
|
||||
- [UI](UI/UI.md) - Editor UI 基础设施。
|
||||
- [Utils](Utils/Utils.md) - 场景编辑与撤销相关辅助函数。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [XCEngine 根目录](../XCEngine.md)
|
||||
- [XCEngine](../XCEngine.md)
|
||||
- [Scene](../Scene/Scene.md)
|
||||
- [Components](../Components/Components.md)
|
||||
- [Rendering](../Rendering/Rendering.md)
|
||||
|
||||
Reference in New Issue
Block a user