XCEngine/editor/README.md

# 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
```