xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: expand editor scripting asset and viewport flow

Browse Source
This commit is contained in:
ssdfasd
2026-04-03 13:22:30 +08:00
parent ed8c27fde2
commit a05d0b80a2
124 changed files with 10397 additions and 1737 deletions
Download Patch File Download Diff File Expand all files Collapse all files

297
README.md
View File

@@ -1,48 +1,39 @@
# XCEngine
XCEngine 是一个正在持续开发中的模块化 C++ 游戏引擎。当前仓库已经形成了较完整的底座：
XCEngine 是一个 Windows 优先、编辑器优先的模块化 C++ 游戏引擎工作区。当前主线已经形成 `RHI -> Rendering -> Editor Viewport -> AssetDatabase/Library -> Mono Scripting` 的可运行闭环，不再只是示例代码集合。
- `RHI` 抽象层已稳定覆盖 `D3D12 / OpenGL / Vulkan`
- `Rendering` 模块已经落地最小可用的场景渲染链路
- `editor/` 已接入基于引擎渲染链路的 Scene/Game viewport
- `managed/` 已具备基于 Mono 的 C# 运行时与托管程序集构建链路
- `tests/` 已形成按模块分层的单元测试与集成测试体系
这份 README 面向引擎用户：关注怎么进入项目、怎么构建、当前仓库各目录分别负责什么。面向构建本引擎的 coding agent，请看 [AGENT.md](AGENT.md)。
如果你是第一次进入当前仓库，先看 [AGENT.md](AGENT.md)。它更偏向“当前工程状态、协作约束与推荐入口”。
## 项目定位
## 当前状态
- 核心引擎库位于 `engine/`，包含 Audio、Components、Core、Debug、Input、Memory、Platform、Rendering、Resources、RHI、Scene、Scripting、Threading。
- RHI 当前正式支持 `D3D12 / OpenGL / Vulkan` 三后端，且抽象层与后端层测试都已经落地。
- Rendering 当前已具备 `RenderSceneExtractor`、`RenderResourceCache`、`SceneRenderer`、`CameraRenderer`、`BuiltinForwardPipeline`。
- Editor 当前是 `D3D12` 宿主应用，但场景绘制已通过引擎 `Rendering + RHI` 链路输出到离屏纹理，再接入 ImGui 面板。
- Managed scripting 当前通过 `managed/XCEngine.ScriptCore` 与 `managed/GameScripts` 构建托管程序集；默认启用 Mono 运行时集成。
- 默认示例工程位于 `project/`，已包含基础场景、背包模型与脚本资产目录。
- `engine/` 提供静态库 `XCEngine`，包含 `RHI`、`Rendering`、`Resources`、`Scene`、`Scripting` 等核心模块。
- `editor/` 提供桌面编辑器 `XCEditor`，输出文件名为 `XCEngine.exe`，默认打开仓库内的 `project/`。
- `project/` 是当前随仓库维护的示例工程，已经采用 `Assets/ + .meta + Library/` 的工程布局。
- `managed/` 负责 `XCEngine.ScriptCore.dll`、示例 `GameScripts.dll` 以及项目脚本程序集构建。
- `tests/` 已覆盖 Engine、RHI、Rendering、Editor、Scripting 等主要模块。
## 环境要求
建议在 Windows 上构建当前仓库。
当前推荐在 Windows 上使用和构建。
- Windows 10/11
- Visual Studio 2022 / MSVC v143
- CMake 3.15+
- .NET SDK
- Vulkan SDK
- .NET SDK
- Git LFS
如果启用默认脚本构建，还需要：
启用 Mono 脚本运行时时，还需要：
- `参考/Fermion/Fermion/external/mono` 下可用的 Mono 头文件、静态库与 `mscorlib.dll`
如果本地暂时没有 Mono 依赖，可以在配置时关闭脚本构建：
补充说明：
```bash
cmake -S . -B build -A x64 -DXCENGINE_ENABLE_MONO_SCRIPTING=OFF
```
- `engine/CMakeLists.txt` 当前对 `Vulkan` 是硬依赖，未配置 Vulkan SDK 时无法完成配置。
- `editor/` 和 `tests/` 首次配置会通过 `FetchContent` 从 Gitee 镜像拉取 `ImGui` 与 `googletest`；离线环境请确保已有可复用的 `_deps` 缓存。
- 如果需要 `mvs/3DGS-Unity/room.ply` 这类大文件示例，请先执行 Git LFS 拉取。
如果你需要 `mvs/3DGS-Unity/room.ply` 这类大文件样例，请确保已经执行过 Git LFS 拉取。
## 构建
## 快速开始
### 1. 配置
@@ -50,60 +41,92 @@ cmake -S . -B build -A x64 -DXCENGINE_ENABLE_MONO_SCRIPTING=OFF
cmake -S . -B build -A x64
```
### 2. 全量编译
如果本地暂时没有 Mono 依赖，可以先关闭脚本运行时：
```bash
cmake --build build --config Debug
cmake -S . -B build -A x64 -DXCENGINE_ENABLE_MONO_SCRIPTING=OFF
```
### 3. 常用增量 target
### 2. 构建常用目标
```bash
cmake --build build --config Debug --target XCEngine
cmake --build build --config Debug --target XCVolumeRendererUI2
cmake --build build --config Debug --target XCEditor
cmake --build build --config Debug --target xcengine_managed_assemblies
cmake --build build --config Debug --target rhi_all_tests
cmake --build build --config Debug --target rendering_unit_tests
cmake --build build --config Debug --target editor_tests
cmake --build build --config Debug --target scripting_tests
cmake --build build --config Debug --target xcengine_project_managed_assemblies
```
说明：
- 编辑器 CMake target 名称仍然是历史遗留的 `XCVolumeRendererUI2`，但输出文件名是 `XCEngine.exe`
- 顶层 CMake 当前会纳入 `engine/`、`editor/`、`managed/`、`mvs/RenderDoc/` 与 `tests/`
- `XCEngine` 是引擎静态库。
- `XCEditor` 是编辑器 target，输出文件名仍为 `editor/bin/<Config>/XCEngine.exe`。
- `xcengine_managed_assemblies` 生成 `managed/` 示例托管程序集。
- `xcengine_project_managed_assemblies` 会扫描 `project/Assets/**/*.cs`，并把结果输出到 `project/Library/ScriptAssemblies/`。
## 测试
### 3. 启动编辑器
推荐始终通过 CMake / CTest 驱动测试。
```bash
.\editor\bin\Debug\XCEngine.exe
```
### 列出测试
默认情况下，编辑器会自动把仓库内的 `project/` 识别为工程根目录。也可以显式指定其他工程：
```bash
.\editor\bin\Debug\XCEngine.exe --project D:\Path\To\MyProject
```
如果 Inspector 里看不到 C# 脚本类，先确认 `project/Library/ScriptAssemblies/` 中已经生成：
- `XCEngine.ScriptCore.dll`
- `GameScripts.dll`
- `mscorlib.dll`
### 4. 当前推荐验证入口
```bash
ctest --test-dir build -N -C Debug
```
### 运行全部测试
```bash
ctest --test-dir build -C Debug --output-on-failure
```
### 常用测试 target
按模块常用的构建 / 验证 target：
```bash
cmake --build build --config Debug --target rhi_abstraction_tests
cmake --build build --config Debug --target rhi_backend_tests
cmake --build build --config Debug --target rendering_unit_tests
cmake --build build --config Debug --target rhi_all_tests
cmake --build build --config Debug --target rendering_all_tests
cmake --build build --config Debug --target rendering_phase_regression
cmake --build build --config Debug --target editor_tests
cmake --build build --config Debug --target scripting_tests
```
更完整的测试规则见 [tests/TEST_SPEC.md](tests/TEST_SPEC.md)。
## 当前仓库状态
## 目录结构
### Engine
下面的目录树用于表达当前仓库的实际入口结构与模块边界。
- `RHI` 正式维护 `D3D12 / OpenGL / Vulkan` 三后端。
- `Rendering` 已形成 `SceneRenderer -> CameraRenderer -> RenderPipeline` 主链，包含 `ObjectId`、`InfiniteGrid`、`Outline`、`overlayPasses` 等能力。
- `Resources` 与 `Core/Asset` 已不只是简单加载器，当前已经具备 `Assets/.meta/Library` 风格的 `AssetDatabase` 与 artifact 缓存。
### Editor
- 当前 editor 是 `D3D12` 宿主应用，但 Scene/Game viewport 已通过引擎 `Rendering + RHI` 链路渲染到离屏纹理，再接入 ImGui。
- `Viewport` 相关代码已经进入 overlay/gizmo 正规化阶段，`SceneViewportOverlayBuilder`、`SceneViewportEditorOverlayPass`、`ObjectId` picking 都已落地。
- Inspector 已支持 `ScriptComponent` 的脚本类选择、字段元数据读取、字段重置与基础编辑。
### Project & Scripting
- 示例工程位于 `project/`，当前工程文件是 `Project.xcproject`，启动场景为 `Assets/Scenes/Main.xc`。
- `project/Assets/` 现已包含 `.meta` 文件，`project/Library/` 则维护 `SourceAssetDB`、`ArtifactDB`、`Artifacts` 与 `ScriptAssemblies`。
- `managed/` 会生成引擎脚本 API 与示例脚本程序集，项目资产下的 `.cs` 文件也会被单独编译为项目脚本程序集。
### Tests
- `tests/` 已覆盖 `Core`、`Memory`、`Threading`、`Scene`、`Resources`、`RHI`、`Rendering`、`Editor`、`Scripting` 等模块。
- `tests/Rendering/` 当前已包含 `backpack_scene`、`backpack_lit_scene`、`camera_stack_scene`、`offscreen_scene` 等集成场景。
- `tests/RHI/` 同时维护抽象层测试与后端专用测试，`D3D12 / OpenGL / Vulkan` 都有独立子树。
## 完整目录结构
以下目录树以当前工程入口为准，保留了当前 workflow 已经实际使用的生成目录；省略 `.git/`、`build/_deps/` 与临时文件。
```text
XCEngine/
@@ -112,15 +135,33 @@ XCEngine/
├── AGENT.md
├── CMakeLists.txt
├── README.md
├── build/ # 本地构建输出
├── build/ # 本地 CMake 构建输出
├── docs/
│ ├── api/ # API 文档
│ ├── issues/ # 跟踪中的设计 / 实现问题
│ ├── plan/ # 设计文档、阶段规划、归档方案
│ │ ├── Renderer模块设计与实现.md
│ │ └── end/
│ │ └── RHI模块设计与实现/
│ │ └── RHI模块总览.md
│ ├── api/
│ │ ├── XCEngine/
│ │ ├── _guides/
│ │ ├── _meta/
│ │ ├── _tools/
│ │ └── main.md
│ ├── issues/
│ ├── plan/
│ │ ├── end/
│ │ │ ├── RHI模块设计与实现/
│ │ │ │ ├── RHIFence.md
│ │ │ │ └── RHI模块总览.md
│ │ │ └── 编辑器与运行时分层架构设计.md
│ │ ├── 开题报告和任务书/
│ │ ├── 旧版题目/
│ │ ├── API文档并行更新任务池_2026-04-02.md
│ │ ├── C#脚本模块的设计与实现.md
│ │ ├── Editor架构说明.md
│ │ ├── SceneViewport_Overlay_Gizmo_Rework_Plan.md
│ │ ├── Shader与Material系统下一阶段计划.md
│ │ ├── Unity SRP API参考文档.md
│ │ ├── Unity式Library资产导入与缓存系统重构方案.md
│ │ ├── Unity式Tick系统与PlayMode运行时方案.md
│ │ ├── Unity式Tick系统与PlayMode运行时方案-阶段进展.md
│ │ └── Unity绝区零开发文档还原版.md
│ ├── used/
│ ├── api-skill.md
│ ├── blueprint-skill.md
@@ -143,13 +184,28 @@ XCEngine/
│ │ ├── UI/
│ │ ├── Utils/
│ │ ├── Viewport/
│ │ │ ├── Passes/
│ │ │ ├── SceneViewportOverlayBuilder.cpp
│ │ │ ├── SceneViewportOverlayBuilder.h
│ │ │ ├── SceneViewportOverlayRenderer.cpp
│ │ │ ├── SceneViewportOverlayRenderer.h
│ │ │ ├── SceneViewportPicker.cpp
│ │ │ ├── SceneViewportPicker.h
│ │ │ ├── SceneViewportMoveGizmo.cpp
│ │ │ ├── SceneViewportMoveGizmo.h
│ │ │ ├── SceneViewportRotateGizmo.cpp
│ │ │ ├── SceneViewportRotateGizmo.h
│ │ │ ├── SceneViewportScaleGizmo.cpp
│ │ │ ├── SceneViewportScaleGizmo.h
│ │ │ ├── ViewportHostRenderFlowUtils.h
│ │ │ └── ViewportHostService.h
│ │ ├── Application.cpp
│ │ ├── Application.h
│ │ ├── EditorApp.rc
│ │ ├── Theme.cpp
│ │ ├── Theme.h
│ │ └── main.cpp
│ └── bin/ # 编辑器输出目录，输出名为 XCEngine.exe
│ └── bin/ # 编辑器输出目录，输出名为 XCEngine.exe
├── engine/
│ ├── CMakeLists.txt
│ ├── include/
@@ -167,17 +223,24 @@ XCEngine/
│ │ ├── Platform/
│ │ │ └── Windows/
│ │ ├── Rendering/
│ │ │ ├── Passes/
│ │ │ ├── Pipelines/
│ │ │ ├── CameraRenderRequest.h
│ │ │ ├── CameraRenderer.h
│ │ │ ├── CameraRenderRequest.h
│ │ │ ├── ObjectIdEncoding.h
│ │ │ ├── ObjectIdPass.h
│ │ │ ├── RenderCameraData.h
│ │ │ ├── RenderContext.h
│ │ │ ├── RenderMaterialUtility.h
│ │ │ ├── RenderPass.h
│ │ │ ├── RenderPipeline.h
│ │ │ ├── RenderPipelineAsset.h
│ │ │ ├── RenderResourceCache.h
│ │ │ ├── RenderSceneExtractor.h
│ │ │ ├── RenderSceneUtility.h
│ │ │ ├── RenderSurface.h
│ │ │ ├── SceneRenderRequestPlanner.h
│ │ │ ├── SceneRenderRequestUtils.h
│ │ │ ├── SceneRenderer.h
│ │ │ └── VisibleRenderObject.h
│ │ ├── Resources/
@@ -189,29 +252,7 @@ XCEngine/
│ │ ├── RHI/
│ │ │ ├── D3D12/
│ │ │ ├── OpenGL/
│ │ │ ├── Vulkan/
│ │ │ ├── RHIBuffer.h
│ │ │ ├── RHICapabilities.h
│ │ │ ├── RHICommandList.h
│ │ │ ├── RHICommandQueue.h
│ │ │ ├── RHIDescriptorPool.h
│ │ │ ├── RHIDescriptorSet.h
│ │ │ ├── RHIDevice.h
│ │ │ ├── RHIEnums.h
│ │ │ ├── RHIFactory.h
│ │ │ ├── RHIFence.h
│ │ │ ├── RHIFramebuffer.h
│ │ │ ├── RHIPipelineLayout.h
│ │ │ ├── RHIPipelineState.h
│ │ │ ├── RHIRenderPass.h
│ │ │ ├── RHIResource.h
│ │ │ ├── RHIResourceView.h
│ │ │ ├── RHISampler.h
│ │ │ ├── RHIScreenshot.h
│ │ │ ├── RHIShader.h
│ │ │ ├── RHISwapChain.h
│ │ │ ├── RHITexture.h
│ │ │ └── RHITypes.h
│ │ │ └── Vulkan/
│ │ ├── Scene/
│ │ ├── Scripting/
│ │ │ └── Mono/
@@ -230,6 +271,7 @@ XCEngine/
│ │ ├── Platform/
│ │ │ └── Windows/
│ │ ├── Rendering/
│ │ │ ├── Passes/
│ │ │ └── Pipelines/
│ │ ├── Resources/
│ │ │ ├── AudioClip/
@@ -255,28 +297,45 @@ XCEngine/
│ └── renderdoc_parser/
├── managed/
│ ├── CMakeLists.txt
│ ├── GameScripts/ # 示例 / 验证脚本程序集源码
│ └── XCEngine.ScriptCore/ # 引擎托管 API
│ ├── GameScripts/
│ └── XCEngine.ScriptCore/
├── mvs/
│ ├── 3DGS-Unity/ # Unity 侧 3DGS 参考与资源
│ ├── 3DGS-Unity/
│ ├── D3D12/
│ ├── Music fluctuations/
│ ├── OpenGL/
│ ├── RenderDoc/
│ ├── Res/
│ ├── ui/
│ ├── ui/ # 早期 ImGui + D3D12 UI 原型，非当前正式 editor
│ └── VolumeRenderer/
├── project/
│ ├── .xceditor/
│ │ └── imgui_layout.ini
│ │ ├── imgui_layout.ini
│ │ └── thumbs/
│ ├── Assets/
│ │ ├── Materials/
│ │ ├── Models/
│ │ │ └── backpack/
│ │ ├── New Folder/
│ │ ├── New Folder 1/
│ │ ├── Scenes/
│ │ │ ├── Backpack.xc
│ │ │ └── Main.xc
│ │ └── Scripts/
│ │ ├── ProjectScriptProbe.cs
│ │ └── Textures/
│ ├── Library/
│ │ ├── ArtifactDB/
│ │ ├── Artifacts/
│ │ ├── ScriptAssemblies/
│ │ │ ├── GameScripts.dll
│ │ │ ├── mscorlib.dll
│ │ │ └── XCEngine.ScriptCore.dll
│ │ └── SourceAssetDB/
│ ├── Assets.meta
│ └── Project.xcproject
├── scripts/
│ └── Run-RendererPhaseRegression.ps1
├── tests/
│ ├── CMakeLists.txt
│ ├── TEST_SPEC.md
@@ -293,7 +352,9 @@ XCEngine/
│ ├── Memory/
│ ├── Rendering/
│ │ ├── integration/
│ │ │ ├── backpack_lit_scene/
│ │ │ ├── backpack_scene/
│ │ │ ├── camera_stack_scene/
│ │ │ ├── cull_material_scene/
│ │ │ ├── depth_sort_scene/
│ │ │ ├── material_state_scene/
@@ -308,66 +369,44 @@ XCEngine/
│ │ ├── Shader/
│ │ └── Texture/
│ ├── RHI/
│ │ ├── CMakeLists.txt
│ │ ├── D3D12/
│ │ │ ├── integration/
│ │ │ └── unit/
│ │ ├── OpenGL/
│ │ │ ├── integration/
│ │ │ └── unit/
│ │ ├── Vulkan/
│ │ │ ├── integration/
│ │ │ ├── unit/
│ │ │ └── TEST_SPEC.md
│ │ ├── integration/
│ │ │ ├── backpack/
│ │ │ ├── fixtures/
│ │ │ ├── minimal/
│ │ │ ├── quad/
│ │ │ ├── sphere/
│ │ │ ├── triangle/
│ │ │ ├── compare_ppm.py
│ │ │ ├── README.md
│ │ │ └── run_integration_test.py
│ │ └── unit/
│ │ │ └── triangle/
│ │ ├── OpenGL/
│ │ │ ├── integration/
│ │ │ └── unit/
│ │ ├── unit/
│ │ └── Vulkan/
│ │ ├── integration/
│ │ └── unit/
│ ├── Scene/
│ ├── Scripting/
│ └── Threading/
├── 参考/
│ └── TransformGizmo/
│ ├── Fermion/
│ ├── TransformGizmo/
│ ├── unity editor/
│ ├── unity-editor-icons/
│ ├── unity-icons/
│ └── UnityRuntimeSceneGizmo-master/
└── .vscode/
```
## 模块概览
### Engine
- `RHI`：统一图形 API 抽象，当前三后端并行维护
- `Rendering`：位于 Scene/Resources 与 RHI 之间，负责把场景提取成真实 draw path
- `Resources`：Mesh / Texture / Material / Shader / AudioClip 导入与加载
- `Scene + Components`：游戏对象、相机、灯光、网格与脚本组件
- `Scripting`：原生脚本运行时与 Mono 托管桥接
### Editor
- 当前是 D3D12 桌面宿主应用
- Scene/Game viewport 已走引擎离屏渲染链路
- 包含 Actions、Commands、Panels、Viewport、Managers 等编辑器子系统
### Tests
- `tests/RHI/`：RHI 抽象层与三后端测试
- `tests/Rendering/`：渲染链路单元与场景级集成测试
- `tests/Scripting/`：脚本运行时与托管程序集集成测试
- `tests/Editor/`：编辑器动作路由与 Scene viewport 相机控制测试
## 关键文档入口
- 当前工程协作入口：[AGENT.md](AGENT.md)
- RHI 核心设计文档：[docs/plan/end/RHI模块设计与实现/RHI模块总览.md](docs/plan/end/RHI模块设计与实现/RHI模块总览.md)
- Renderer 规划与实现说明：[docs/plan/Renderer模块设计与实现.md](docs/plan/Renderer模块设计与实现.md)
- 协作基线与 coding agent 入口：[AGENT.md](AGENT.md)
- RHI 基线设计：[docs/plan/end/RHI模块设计与实现/RHI模块总览.md](docs/plan/end/RHI模块设计与实现/RHI模块总览.md)
- 当前 Shader / Material 主线：[docs/plan/Shader与Material系统下一阶段计划.md](docs/plan/Shader与Material系统下一阶段计划.md)
- Scene viewport overlay 重构：[docs/plan/SceneViewport_Overlay_Gizmo_Rework_Plan.md](docs/plan/SceneViewport_Overlay_Gizmo_Rework_Plan.md)
- 测试规范：[tests/TEST_SPEC.md](tests/TEST_SPEC.md)
## 许可证
当前仓库根目录未看到单独的顶层许可证文件；涉及第三方库时请分别遵循对应依赖目录中的许可证说明。
当前仓库根目录未看到独立的顶层许可证文件。涉及第三方库时，请分别遵循其所在目录中的许可证或随附说明。