feat: expand editor scripting asset and viewport flow
This commit is contained in:
326
editor/README.md
326
editor/README.md
@@ -1,183 +1,205 @@
|
||||
# UI Editor
|
||||
# XCEditor
|
||||
|
||||
Unity 风格的编辑器 UI，使用 ImGui 实现，作为 XCEngine 游戏引擎编辑器的一部分。
|
||||
`editor/` 是 XCEngine 当前随仓库维护的桌面编辑器模块。它不是一套独立渲染器，而是 `D3D12` 宿主应用，用来承接引擎 `Rendering + RHI + Scene + Scripting` 主链。
|
||||
|
||||
## 简介
|
||||
当前 editor 已经具备：
|
||||
|
||||
XCGameEngine UI 是一个仿 Unity 编辑器的桌面应用程序，提供场景管理、层级视图、属性检查器等功能。
|
||||
- Scene / Game viewport 离屏渲染接入
|
||||
- object-id picking 与选中描边
|
||||
- scene overlay / gizmo 正规化收口
|
||||
- 项目根目录解析与 `Project.xcproject` 加载
|
||||
- `Assets + .meta + Library` 风格项目目录接入
|
||||
- `ScriptComponent` 的脚本类与字段编辑入口
|
||||
|
||||
## 技术栈
|
||||
## 当前定位
|
||||
|
||||
- **渲染 API**: DirectX 12
|
||||
- **UI 框架**: ImGui
|
||||
- **语言**: C++17
|
||||
- **构建系统**: CMake
|
||||
- **依赖库**: DirectX 12 SDK
|
||||
如果你想理解当前 editor，先把它当成三层：
|
||||
|
||||
## 项目结构
|
||||
1. `Win32 + D3D12` 宿主窗口与 ImGui backend
|
||||
2. `ViewportHostService` 对引擎渲染链路的接线
|
||||
3. `panels/`、`Managers/`、`ComponentEditors/` 这些编辑器业务层
|
||||
|
||||
```
|
||||
ui/
|
||||
├── src/
|
||||
│ ├── main.cpp # 程序入口
|
||||
│ ├── Application.cpp/h # 应用主类
|
||||
│ ├── Theme.cpp/h # 主题系统
|
||||
│ ├── Core/
|
||||
│ │ ├── GameObject.h # 游戏对象
|
||||
│ │ └── LogEntry.h # 日志条目
|
||||
│ ├── Managers/
|
||||
│ │ ├── LogSystem.cpp/h # 日志系统
|
||||
│ │ ├── ProjectManager.cpp/h # 项目管理
|
||||
│ │ ├── SceneManager.cpp/h # 场景管理
|
||||
│ │ └── SelectionManager.cpp/h # 选择管理
|
||||
│ └── panels/
|
||||
│ ├── Panel.cpp/h # 面板基类
|
||||
│ ├── MenuBar.cpp/h # 菜单栏
|
||||
│ ├── HierarchyPanel.cpp/h # 层级面板
|
||||
│ ├── InspectorPanel.cpp/h # 检查器面板
|
||||
│ ├── SceneViewPanel.cpp/h # 场景视图
|
||||
│ ├── GameViewPanel.cpp/h # 游戏视图
|
||||
│ ├── ProjectPanel.cpp/h # 项目面板
|
||||
│ └── ConsolePanel.cpp/h # 控制台面板
|
||||
├── bin/Release/ # 输出目录
|
||||
│ ├── XCVolumeRendererUI2.exe # 可执行文件
|
||||
│ ├── imgui.ini # ImGui 配置
|
||||
│ └── Assets/
|
||||
│ └── Models/
|
||||
│ └── Character.fbx # 示例模型
|
||||
├── build/ # 构建目录
|
||||
└── CMakeLists.txt # CMake 配置
|
||||
```
|
||||
当前不应再把 editor 视为旧式“UI sample”。它已经是引擎工作区的正式入口之一。
|
||||
|
||||
## 构建方法
|
||||
## 构建
|
||||
|
||||
推荐直接在仓库根目录构建，而不是单独进入 `editor/` 目录。
|
||||
|
||||
### 前置要求
|
||||
|
||||
- Windows 10/11
|
||||
- Visual Studio 2019 或更高版本
|
||||
- Visual Studio 2022 / MSVC v143
|
||||
- CMake 3.15+
|
||||
- Vulkan SDK
|
||||
|
||||
### 构建步骤
|
||||
如果需要启用 Mono 脚本运行时，还需要：
|
||||
|
||||
- .NET SDK
|
||||
- `参考/Fermion/Fermion/external/mono` 下的 Mono 依赖
|
||||
|
||||
### 配置
|
||||
|
||||
```bash
|
||||
cd ui
|
||||
mkdir build && cd build
|
||||
cmake ..
|
||||
cmake --build . --config Release
|
||||
cmake -S .. -B ..\build -A x64
|
||||
```
|
||||
|
||||
### 运行
|
||||
更常见的做法是直接在仓库根目录运行：
|
||||
|
||||
```bash
|
||||
# 运行编译好的可执行文件
|
||||
.\bin\Release\XCGameEngineUI.exe
|
||||
cmake -S . -B build -A x64
|
||||
```
|
||||
|
||||
## 功能特性
|
||||
如果本地暂时没有 Mono，可以先关闭：
|
||||
|
||||
### 编辑器面板
|
||||
|
||||
#### 菜单栏（MenuBar）
|
||||
- 文件菜单（新建、打开、保存等）
|
||||
- 编辑菜单（撤销、重做等）
|
||||
- 视图菜单（面板显示/隐藏）
|
||||
- 帮助菜单
|
||||
|
||||
#### 层级面板（Hierarchy Panel）
|
||||
- 显示场景中所有游戏对象
|
||||
- 树形结构展示父子关系
|
||||
- 支持对象选择
|
||||
- 对象重命名
|
||||
|
||||
#### 检查器面板（Inspector Panel）
|
||||
- 显示选中对象的属性
|
||||
- 支持组件编辑
|
||||
- 变换组件（位置、旋转、缩放）
|
||||
- 材质组件
|
||||
|
||||
#### 场景视图（Scene View）
|
||||
- 3D 场景预览
|
||||
- 相机控制（平移、旋转、缩放）
|
||||
- 对象选择
|
||||
- 辅助工具（网格、轴心）
|
||||
|
||||
#### 游戏视图（Game View）
|
||||
- 游戏运行时的画面预览
|
||||
- 分辨率设置
|
||||
- 宽高比选择
|
||||
|
||||
#### 项目面板（Project Panel）
|
||||
- 项目文件浏览器
|
||||
- 资源组织
|
||||
- 搜索过滤
|
||||
|
||||
#### 控制台面板（Console Panel）
|
||||
- 日志输出
|
||||
- 警告和错误显示
|
||||
- 日志级别过滤
|
||||
- 清空日志
|
||||
|
||||
### 管理系统
|
||||
|
||||
#### 日志系统（LogSystem）
|
||||
- 分级日志（Info、Warning、Error）
|
||||
- 时间戳
|
||||
- 日志持久化
|
||||
|
||||
#### 项目管理（ProjectManager）
|
||||
- 项目创建/打开
|
||||
- 资源路径管理
|
||||
|
||||
#### 场景管理（SceneManager）
|
||||
- 场景加载/保存
|
||||
- 对象生命周期管理
|
||||
|
||||
#### 选择管理（SelectionManager）
|
||||
- 当前选中对象追踪
|
||||
- 多选支持
|
||||
|
||||
### 主题系统
|
||||
|
||||
- 深色主题（Dark Theme）
|
||||
- 可自定义配色方案
|
||||
|
||||
## 窗口布局
|
||||
|
||||
默认布局采用经典的 Unity 编辑器风格：
|
||||
|
||||
```
|
||||
+----------------------------------------------------------+
|
||||
| 菜单栏 |
|
||||
+----------+------------------------+----------------------+
|
||||
| | | |
|
||||
| 项目 | 场景视图 | 检查器 |
|
||||
| 面板 | | |
|
||||
| | | |
|
||||
+----------+------------------------+----------------------+
|
||||
| 层级面板 | 游戏视图 |
|
||||
| | |
|
||||
+------------------------------------+----------------------+
|
||||
| 控制台面板 |
|
||||
+----------------------------------------------------------+
|
||||
```bash
|
||||
cmake -S . -B build -A x64 -DXCENGINE_ENABLE_MONO_SCRIPTING=OFF
|
||||
```
|
||||
|
||||
## 依赖说明
|
||||
### 构建 editor
|
||||
|
||||
- ImGui - 跨平台 GUI 库
|
||||
- DirectX 12 - 渲染 API
|
||||
- Windows SDK - 窗口管理
|
||||
```bash
|
||||
cmake --build build --config Debug --target XCEditor
|
||||
```
|
||||
|
||||
## 扩展开发
|
||||
说明：
|
||||
|
||||
### 添加新面板
|
||||
- target 名称是 `XCEditor`
|
||||
- 输出文件名仍然是 `XCEngine.exe`
|
||||
- 输出目录是 `editor/bin/<Config>/`
|
||||
|
||||
1. 在 `panels/` 目录下创建新的面板类
|
||||
2. 继承 `Panel` 基类
|
||||
3. 实现 `Render()` 方法
|
||||
4. 在 `Application` 中注册新面板
|
||||
## 运行
|
||||
|
||||
### 添加新组件
|
||||
```bash
|
||||
.\editor\bin\Debug\XCEngine.exe
|
||||
```
|
||||
|
||||
1. 定义组件类
|
||||
2. 在 `GameObject` 中注册组件类型
|
||||
3. 在 `InspectorPanel` 中添加属性编辑器
|
||||
默认情况下，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
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user