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

### 配置

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