XCEngine/editor/README.md

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 依赖

配置

cmake -S .. -B ..\build -A x64

更常见的做法是直接在仓库根目录运行：

cmake -S . -B build -A x64

如果本地暂时没有 Mono，可以先关闭：

cmake -S . -B build -A x64 -DXCENGINE_ENABLE_MONO_SCRIPTING=OFF

构建 editor

cmake --build build --config Debug --target XCEditor

说明：

• target 名称是 XCEditor
• 输出文件名仍然是 XCEngine.exe
• 输出目录是 editor/bin/<Config>/

运行

.\editor\bin\Debug\XCEngine.exe

默认情况下，editor 会自动把仓库内的 project/ 识别为工程根目录。也可以显式指定工程：

.\editor\bin\Debug\XCEngine.exe --project D:\Path\To\Project

如果需要 C# 脚本类发现与 Inspector 字段编辑，先构建：

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

当前目录结构

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 仍处于“无工程状态”的旧结构。

推荐验证

cmake --build build --config Debug --target editor_tests
cmake --build build --config Debug --target rendering_phase_regression

如果改动影响脚本类发现或 Inspector 脚本字段编辑，再补：

cmake --build build --config Debug --target xcengine_project_managed_assemblies
cmake --build build --config Debug --target scripting_tests