206 lines
5.7 KiB
Markdown
206 lines
5.7 KiB
Markdown
# XCEditor
|
||
|
||
`editor/` 是 XCEngine 当前随仓库维护的桌面编辑器模块。它不是一套独立渲染器，而是 `D3D12` 宿主应用，用来承接引擎 `Rendering + RHI + Scene + Scripting` 主链。
|
||
|
||
当前 editor 已经具备：
|
||
|
||
- Scene / Game viewport 离屏渲染接入
|
||
- object-id picking 与选中描边
|
||
- scene overlay / gizmo 正规化收口
|
||
- 项目根目录解析与 `Project.xcproject` 加载
|
||
- `Assets + .meta + Library` 风格项目目录接入
|
||
- `ScriptComponent` 的脚本类与字段编辑入口
|
||
|
||
## 当前定位
|
||
|
||
如果你想理解当前 editor，先把它当成三层：
|
||
|
||
1. `Win32 + D3D12` 宿主窗口与 ImGui backend
|
||
2. `ViewportHostService` 对引擎渲染链路的接线
|
||
3. `panels/`、`Managers/`、`ComponentEditors/` 这些编辑器业务层
|
||
|
||
当前不应再把 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
|
||
```
|
||
|
||
更常见的做法是直接在仓库根目录运行：
|
||
|
||
```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
|
||
```
|
||
|
||
该 target 会把程序集放到：
|
||
|
||
- `project/Library/ScriptAssemblies/XCEngine.ScriptCore.dll`
|
||
- `project/Library/ScriptAssemblies/GameScripts.dll`
|
||
- `project/Library/ScriptAssemblies/mscorlib.dll`
|
||
|
||
## 当前目录结构
|
||
|
||
```text
|
||
editor/
|
||
├── CMakeLists.txt
|
||
├── README.md
|
||
├── resources/
|
||
│ └── Icons/
|
||
├── src/
|
||
│ ├── Actions/ # 编辑器动作路由
|
||
│ ├── Commands/ # 命令与实体操作
|
||
│ ├── ComponentEditors/ # Inspector 组件编辑器
|
||
│ ├── Core/ # 应用生命周期、日志、项目根解析、撤销等
|
||
│ ├── Layers/ # EditorLayer 等高层组装
|
||
│ ├── Layout/
|
||
│ ├── Managers/ # SceneManager / ProjectManager
|
||
│ ├── panels/ # Hierarchy / Scene / Game / Inspector / Project / Console
|
||
│ ├── Platform/ # Win32 host、D3D12 backend 辅助
|
||
│ ├── UI/ # ImGui bridge 与通用 widget
|
||
│ ├── Utils/
|
||
│ ├── Viewport/
|
||
│ │ ├── Passes/ # editor viewport overlay pass
|
||
│ │ ├── SceneViewportOverlayBuilder.*
|
||
│ │ ├── SceneViewportPicker.*
|
||
│ │ ├── SceneViewportMoveGizmo.*
|
||
│ │ ├── SceneViewportRotateGizmo.*
|
||
│ │ ├── SceneViewportScaleGizmo.*
|
||
│ │ ├── ViewportHostRenderFlowUtils.h
|
||
│ │ └── ViewportHostService.h
|
||
│ ├── Application.cpp
|
||
│ ├── Application.h
|
||
│ ├── EditorApp.rc
|
||
│ ├── Theme.cpp
|
||
│ ├── Theme.h
|
||
│ └── main.cpp
|
||
└── bin/
|
||
```
|
||
|
||
## 关键模块
|
||
|
||
### 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`
|
||
|
||
负责：
|
||
|
||
- 自动识别仓库内 `project/`
|
||
- 解析 `--project`
|
||
- 读写 `Project.xcproject`
|
||
|
||
### Viewport
|
||
|
||
- `src/Viewport/ViewportHostService.h`
|
||
- `src/Viewport/ViewportHostRenderFlowUtils.h`
|
||
- `src/Viewport/SceneViewportOverlayBuilder.*`
|
||
- `src/Viewport/Passes/SceneViewportEditorOverlayPass.*`
|
||
|
||
负责：
|
||
|
||
- 组装 scene/game viewport 渲染请求
|
||
- 把 editor overlay 接入 `CameraRenderRequest::overlayPasses`
|
||
- object-id picking、outline、overlay pass 等 editor 视口能力
|
||
|
||
### Panels
|
||
|
||
当前主要面板：
|
||
|
||
- `HierarchyPanel`
|
||
- `SceneViewPanel`
|
||
- `GameViewPanel`
|
||
- `InspectorPanel`
|
||
- `ProjectPanel`
|
||
- `ConsolePanel`
|
||
|
||
### Component Editors
|
||
|
||
`ComponentEditors/` 当前不仅负责基础组件，也已经包含 `ScriptComponent` 的 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
|
||
```
|