282 lines
8.5 KiB
Markdown
282 lines
8.5 KiB
Markdown
# XCEditor
|
||
|
||
`editor/` 是 XCEngine 当前随仓库维护的桌面编辑器模块。它不是第二套独立渲染器，而是 `D3D12` 宿主应用，用来承接引擎 `Rendering + RHI + Scene + Scripting` 主链。
|
||
|
||
如果你想了解整个工作区，先看仓库根目录的 [README.md](../README.md)；如果你要直接改 editor 或相关引擎接线，再看 [AGENT.md](../AGENT.md)。
|
||
|
||
## 当前能力
|
||
|
||
- Scene / Game viewport 离屏渲染接入
|
||
- object-id picking 与选中描边
|
||
- scene overlay / gizmo 正规化收口
|
||
- 项目根目录解析与 `Project.xcproject` 加载
|
||
- `Assets + .meta + Library` 风格项目目录接入
|
||
- `ScriptComponent` 的脚本类与字段编辑入口
|
||
- 项目脚本程序集重建与运行时重载入口
|
||
|
||
## 当前定位
|
||
|
||
理解当前 editor，推荐把它拆成四层：
|
||
|
||
1. `Win32 + D3D12` 宿主窗口与 ImGui backend
|
||
2. `ViewportHostService` 以及 Scene View helper 对引擎渲染链路的接线
|
||
3. `panels/`、`Managers/`、`ComponentEditors/` 这些编辑器业务层
|
||
4. `Scripting/` 对项目脚本程序集和运行时状态的桥接
|
||
|
||
当前不要再把 editor 当成“旧式 UI sample”。它已经是引擎工作区的正式入口之一。
|
||
|
||
## 构建
|
||
|
||
推荐始终在仓库根目录构建，而不是单独进入 `editor/` 目录。
|
||
|
||
### 前置要求
|
||
|
||
- Windows 10/11
|
||
- Visual Studio 2022 / MSVC v143
|
||
- CMake 3.15+
|
||
- Vulkan SDK
|
||
|
||
如果要启用 Mono 脚本运行时，还需要：
|
||
|
||
- .NET SDK
|
||
- `参考/Fermion/Fermion/external/mono` 下可用的 Mono 依赖
|
||
|
||
### 配置
|
||
|
||
```bash
|
||
cmake -S . -B build -A x64
|
||
```
|
||
|
||
如果本地暂时没有 Mono，可以先关闭：
|
||
|
||
```bash
|
||
cmake -S . -B build -A x64 -DXCENGINE_ENABLE_MONO_SCRIPTING=OFF
|
||
```
|
||
|
||
### 构建 editor
|
||
|
||
```bash
|
||
cmake --build build --config Debug --target XCEditor
|
||
```
|
||
|
||
说明：
|
||
|
||
- target 名称是 `XCEditor`
|
||
- 输出文件名仍然是 `XCEngine.exe`
|
||
- 输出目录是 `editor/bin/<Config>/`
|
||
|
||
## 运行
|
||
|
||
```bash
|
||
.\editor\bin\Debug\XCEngine.exe
|
||
```
|
||
|
||
默认情况下，editor 会自动把仓库内的 `project/` 识别为工程根目录。也可以显式指定工程：
|
||
|
||
```bash
|
||
.\editor\bin\Debug\XCEngine.exe --project D:\Path\To\Project
|
||
```
|
||
|
||
如果需要 C# 脚本类发现与 Inspector 字段编辑，先构建：
|
||
|
||
```bash
|
||
cmake --build build --config Debug --target xcengine_project_managed_assemblies
|
||
```
|
||
|
||
成功重建后，项目脚本程序集目录通常应包含：
|
||
|
||
- `project/Library/ScriptAssemblies/XCEngine.ScriptCore.dll`
|
||
- `project/Library/ScriptAssemblies/GameScripts.dll`
|
||
- `project/Library/ScriptAssemblies/mscorlib.dll`
|
||
|
||
当前工作树如果暂时缺少 `XCEngine.ScriptCore.dll`，通常说明项目脚本程序集还没有按最新状态完成重建，而不是 editor 只需要两个程序集。
|
||
|
||
## 当前目录结构
|
||
|
||
```text
|
||
editor/
|
||
|- CMakeLists.txt
|
||
|- README.md
|
||
|- bin/ # 输出目录，产物名仍为 XCEngine.exe
|
||
|- resources/
|
||
| `- Icons/
|
||
`- src/
|
||
|- Actions/ # 编辑器动作路由
|
||
|- Commands/ # 命令与实体操作
|
||
|- ComponentEditors/ # Inspector 组件编辑器
|
||
|- Core/ # 生命周期、日志、项目根解析、撤销、play session
|
||
|- Layers/ # EditorLayer 等高层组装
|
||
|- Layout/
|
||
|- Managers/ # SceneManager / ProjectManager / SelectionManager
|
||
|- panels/
|
||
| |- ConsolePanel.cpp
|
||
| |- ConsolePanel.h
|
||
| |- GameViewPanel.cpp
|
||
| |- GameViewPanel.h
|
||
| |- HierarchyPanel.cpp
|
||
| |- HierarchyPanel.h
|
||
| |- InspectorPanel.cpp
|
||
| |- InspectorPanel.h
|
||
| |- MenuBar.cpp
|
||
| |- MenuBar.h
|
||
| |- Panel.cpp
|
||
| |- Panel.h
|
||
| |- PanelCollection.h
|
||
| |- ProjectPanel.cpp
|
||
| |- ProjectPanel.h
|
||
| |- SceneViewPanel.cpp
|
||
| |- SceneViewPanel.h
|
||
| `- ViewportPanelContent.h
|
||
|- Platform/ # Win32 host、D3D12 backend 辅助
|
||
|- Scripting/ # 项目脚本程序集构建与运行时状态
|
||
|- UI/ # ImGui bridge 与通用 widget
|
||
|- Utils/
|
||
|- Viewport/
|
||
| |- Passes/
|
||
| | |- SceneViewportEditorOverlayPass.*
|
||
| | |- SceneViewportGridPass.*
|
||
| | `- SceneViewportSelectionOutlinePass.*
|
||
| |- IViewportHostService.h
|
||
| |- SceneViewportCameraController.h
|
||
| |- SceneViewportChrome.*
|
||
| |- SceneViewportEditorModes.h
|
||
| |- SceneViewportEditorOverlayData.h
|
||
| |- SceneViewportHudOverlay.*
|
||
| |- SceneViewportInteractionActions.*
|
||
| |- SceneViewportInteractionFrame.h
|
||
| |- SceneViewportInteractionResolver.*
|
||
| |- SceneViewportMath.h
|
||
| |- SceneViewportMoveGizmo.*
|
||
| |- SceneViewportNavigation.h
|
||
| |- SceneViewportOrientationGizmo.*
|
||
| |- SceneViewportOverlayBuilder.*
|
||
| |- SceneViewportOverlayFrameCache.*
|
||
| |- SceneViewportOverlayHandleBuilder.h
|
||
| |- SceneViewportOverlayHitTester.h
|
||
| |- SceneViewportOverlayProviders.*
|
||
| |- SceneViewportOverlaySpriteResources.*
|
||
| |- SceneViewportPassSpecs.h
|
||
| |- SceneViewportPicker.*
|
||
| |- SceneViewportRenderPlan.h
|
||
| |- SceneViewportResourcePaths.h
|
||
| |- SceneViewportRotateGizmo.*
|
||
| |- SceneViewportScaleGizmo.*
|
||
| |- SceneViewportShaderPaths.h # 兼容 include，真实 owner 已转到 ResourcePaths
|
||
| |- SceneViewportTransformGizmoCoordinator.*
|
||
| |- SceneViewportTransformGizmoFrameBuilder.h
|
||
| |- ViewportHostRenderFlowUtils.h
|
||
| |- ViewportHostRenderTargets.h
|
||
| |- ViewportHostService.h
|
||
| |- ViewportHostSurfaceUtils.h
|
||
| `- ViewportObjectIdPicker.h
|
||
|- Application.cpp
|
||
|- Application.h
|
||
|- EditorApp.rc
|
||
|- EditorResources.h
|
||
|- Theme.cpp
|
||
|- Theme.h
|
||
`- main.cpp
|
||
```
|
||
|
||
## 关键模块
|
||
|
||
### Application
|
||
|
||
- `src/Application.cpp`
|
||
- `src/Application.h`
|
||
|
||
负责：
|
||
|
||
- editor 初始化与关闭
|
||
- resource root 设置
|
||
- scripting runtime 初始化与重载
|
||
- ImGui backend 初始化
|
||
- `ViewportHostService` 接线
|
||
|
||
### Project Root
|
||
|
||
- `src/Core/ProjectRootResolver.h`
|
||
- `src/Utils/ProjectFileUtils.h`
|
||
- `src/Managers/ProjectManager.*`
|
||
|
||
负责：
|
||
|
||
- 自动识别仓库内 `project/`
|
||
- 解析 `--project`
|
||
- 读写 `Project.xcproject`
|
||
- 当前 Project 面板目录与资源操作
|
||
|
||
### Viewport
|
||
|
||
- `src/Viewport/ViewportHostService.h`
|
||
- `src/Viewport/SceneViewportChrome.h`
|
||
- `src/Viewport/SceneViewportInteractionFrame.h`
|
||
- `src/Viewport/SceneViewportNavigation.h`
|
||
- `src/Viewport/SceneViewportTransformGizmoCoordinator.h`
|
||
- `src/Viewport/SceneViewportRenderPlan.h`
|
||
- `src/Viewport/SceneViewportOverlayBuilder.*`
|
||
- `src/Viewport/SceneViewportOverlaySpriteResources.*`
|
||
- `src/Viewport/SceneViewportResourcePaths.h`
|
||
- `src/Viewport/Passes/SceneViewportEditorOverlayPass.*`
|
||
|
||
负责：
|
||
|
||
- 组装 Scene / Game viewport 渲染请求
|
||
- 把 editor overlay 接入 `CameraRenderRequest::overlayPasses`
|
||
- 处理 Scene View 的工具切换、hover / click 解析与导航输入
|
||
- 维护 gizmo overlay state、handle hit-test、HUD overlay、sprite 资源缓存与 presentation 刷新
|
||
- 提供 object-id picking、outline、grid 等 editor 视口能力
|
||
|
||
### Panels
|
||
|
||
当前主要面板：
|
||
|
||
- `HierarchyPanel`
|
||
- `SceneViewPanel`
|
||
- `GameViewPanel`
|
||
- `InspectorPanel`
|
||
- `ProjectPanel`
|
||
- `ConsolePanel`
|
||
|
||
### Component Editors
|
||
|
||
`ComponentEditors/` 不只负责基础组件，也已经包含：
|
||
|
||
- `MeshFilterComponentEditor`
|
||
- `MeshRendererComponentEditor`
|
||
- `ScriptComponentEditor`
|
||
- `AssetReferenceEditorUtils`
|
||
|
||
### Scripting
|
||
|
||
- `src/Scripting/EditorScriptAssemblyBuilder.*`
|
||
- `src/Scripting/EditorScriptAssemblyBuilderUtils.h`
|
||
- `src/Scripting/EditorScriptRuntimeStatus.h`
|
||
|
||
负责：
|
||
|
||
- 从项目脚本资产构建程序集
|
||
- 汇报脚本运行时状态
|
||
- 为 Inspector / 菜单动作提供“能否重建脚本程序集”的判断依据
|
||
|
||
## 开发约束
|
||
|
||
- editor 是宿主，不是第二套 renderer。
|
||
- 新的世界空间 overlay / gizmo，不应继续堆到旧的 ImGui world draw 路径。
|
||
- viewport 相关问题优先检查 `engine/Rendering`、`RenderSurface` 与 `ViewportHostService` 的接线，而不是直接在 panel 里复制渲染逻辑。
|
||
- 与项目资源、脚本程序集、`.meta`、`Library` 相关的问题，不要假设 editor 仍处于“无工程状态”的旧结构。
|
||
|
||
## 推荐验证
|
||
|
||
```bash
|
||
cmake --build build --config Debug --target editor_tests
|
||
cmake --build build --config Debug --target rendering_phase_regression
|
||
```
|
||
|
||
如果改动影响脚本类发现、脚本程序集重建或 Inspector 脚本字段编辑，再补：
|
||
|
||
```bash
|
||
cmake --build build --config Debug --target xcengine_project_managed_assemblies
|
||
cmake --build build --config Debug --target scripting_tests
|
||
```
|