XCEngine/README.md

# XCEngine

`XCEngine` 是一个 Windows-first、editor-first 的 `C++20` 游戏引擎工作区。当前代码中已经形成 `RHI`、`Rendering`、`Scene`、`Resources`、`Editor`、`Mono C# Scripting` 和 `XCUI` 相关主线；本 README 只描述当前已经实现、已经接入或已经成为正式工作流一部分的能力。

## 核心特性

### 渲染

- 内置跨后端 `RHI` 抽象层，当前支持 `D3D12`、`OpenGL`、`Vulkan`
- 当前主渲染链为 `SceneRenderer -> CameraRenderer -> BuiltinForwardPipeline`
- 已接入前向渲染主路径、透明路径和 skybox 路径
- 已具备方向光阴影通路
- 已具备 `object-id` pass，可用于编辑器拾取
- 已具备选中描边、最终颜色合成和颜色缩放后处理 pass
- 已具备无限网格 pass，可用于 Scene View
- 已接入 `NanoVDB` 体积渲染 pass
- `RenderSurface` 允许同一条渲染链服务于窗口输出、编辑器视口和离屏目标

### 场景与运行时

- 采用 `Scene / GameObject / Component` 结构
- 已具备场景更新、运行时驱动和场景序列化能力
- 内置常用组件，包括：
  - `TransformComponent`
  - `CameraComponent`
  - `LightComponent`
  - `MeshFilterComponent`
  - `MeshRendererComponent`
  - `VolumeRendererComponent`
  - `AudioSourceComponent`
  - `AudioListenerComponent`
  - `ScriptComponent`

### 资源系统

- 资源主线不是简单文件直读，而是 `AssetDatabase + Artifact + Library` 工作流
- 已具备项目资产索引、导入、重导入和缓存维护链路
- 已接入的资源类型包括：
  - `Mesh`
  - `Texture`
  - `Shader`
  - `Material`
  - `AudioClip`
  - `VolumeField`
  - `UI Document`
- 内置 `builtin://` 资源入口，可直接使用基础 mesh、材质等内置资源

### 脚本系统

- 可选启用基于 `Mono` 的 `C#` 脚本运行时
- 托管程序集分为：
  - `XCEngine.ScriptCore`
  - `GameScripts`
- 脚本组件由 `ScriptComponent` 承载
- 引擎当前支持脚本类发现、字段元数据读取、默认值读取和字段存储
- 支持脚本字段 override 持久化与运行时同步
- 编辑器已接入项目脚本程序集重建与脚本运行时重载

### 编辑器

- 当前正式编辑器是基于 `Win32 + D3D12 + ImGui` 的桌面编辑器
- 当前已具备以下基础工作流：
  - `Hierarchy`
  - `Inspector`
  - `Project`
  - `Console`
  - `Scene View`
  - `Game View`
- `Scene View` 已接入：
  - object-id picking
  - selection outline
  - overlay
  - transform gizmo
  - infinite grid
- `Inspector` 已能处理常规组件检查，也已接入 `ScriptComponent` 与材质资源检查路径
- 编辑器能够识别项目目录、加载项目资源、接通 `Library/ScriptAssemblies` 中的脚本程序集

### UI 与 XCUI

- 引擎内部包含 retained-mode UI 基础设施
- 已具备：
  - 布局系统
  - 样式系统
  - 焦点控制
  - 输入分发
  - 快捷键分发
  - 文本输入编辑
  - 选择模型
  - 拖拽交互模型
- 运行时 UI 主链包括：
  - `UIScreenDocumentHost`
  - `UIScreenPlayer`
  - `UISystem`
- `tests/UI/` 是当前 XCUI `Core / Editor / Runtime` 三层的正式基础层验证入口
- `new_editor/` 是未来正式编辑器主线，不再只是临时沙盒；当前已经包含树视图、列表视图、菜单、标签条、属性网格、字段控件、workspace / dock / viewport shell 等基础组件

### 音频

- 已具备 `AudioSystem`
- 已接入 `AudioSourceComponent` 与 `AudioListenerComponent`
- 当前代码中已包含 `AudioMixer` 和多种效果器/分析器实现入口：
  - `Equalizer`
  - `FFTFilter`
  - `Reverbation`
  - `HRTF`

### 测试

- 引擎不是“只靠手工点点看”的状态，当前已具备大规模测试树
- 覆盖范围包括：
  - Engine 基础模块
  - Rendering
  - RHI
  - Editor
  - Scripting
  - UI
- `RHI` 集成测试使用统一基准图做 golden-image 对比
- `XCUI` 当前也有独立的 unit / integration 验证链路

## 当前实现范围

- 当前正式编辑器为基于 `Win32 + D3D12 + ImGui` 的桌面编辑器
- 当前 `RHI` 后端为 `D3D12`、`OpenGL`、`Vulkan`
- 当前项目资产工作流已经接入 `AssetDatabase + Artifact + Library`
- 当前 `Mono C#` 脚本程序集与运行时链路已经接入
- 当前 `XCUI` 新编辑器路线以 `new_editor/` 为正式主线继续推进

## 快速开始

推荐环境：

- Windows 10/11
- Visual Studio 2022 / MSVC v143
- CMake 3.15+
- Vulkan SDK
- .NET SDK

配置工程：

```powershell
cmake -S . -B build -A x64
```

如果当前不需要 Mono 脚本运行时：

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

构建当前正式编辑器：

```powershell
cmake --build build --config Debug --target XCEditor
```

运行：

```powershell
.\editor\bin\Debug\XCEngine.exe
```

如需构建项目脚本程序集：

```powershell
cmake --build build --config Debug --target xcengine_project_managed_assemblies
```

如需构建 XCUI 新编辑器宿主：

```powershell
cmake --build build --config Debug --target XCUIEditorApp
```

运行 XCUI 新编辑器宿主：

```powershell
.\new_editor\bin\Debug\XCUIEditor.exe
```

## 测试入口

```powershell
ctest --test-dir build -N -C Debug
ctest --test-dir build -C Debug --output-on-failure
```

常用目标：

```powershell
cmake --build build --config Debug --target editor_tests
cmake --build build --config Debug --target rendering_all_tests
cmake --build build --config Debug --target rhi_all_tests
cmake --build build --config Debug --target scripting_tests
cmake --build build --config Debug --target core_ui_all_tests
cmake --build build --config Debug --target editor_ui_all_tests
cmake --build build --config Debug --target runtime_ui_all_tests
```

## 完整目录结构

以下目录树按当前工作树整理，保留了真实使用的生成目录与关键子树；省略了 `.git/`、`build/_deps/`、部分重复资源文件，以及 `docs/used/` 中大量历史归档的长尾条目。

```text
XCEngine/
|- .gitattributes
|- .gitignore
|- AGENT.md
|- CMakeLists.txt
|- README.md
|- build/                                      # 本地 CMake 构建输出
|- docs/
|  |- api/
|  |  |- XCEngine/
|  |  |- _guides/
|  |  |- _meta/
|  |  |- _tools/
|  |  `- main.md
|  |- issues/
|  |  `- Editor模块_Console面板错误绑定fallback sink导致运行时日志不显示4.3.md
|  |- plan/
|  |  |- end/
|  |  |  |- RHI模块设计与实现/
|  |  |  |  |- RHIFence.md
|  |  |  |  `- RHI模块总览.md
|  |  |  `- 编辑器与运行时分层架构设计.md
|  |  |- 开题报告和任务书/
|  |  |- 旧版题目/
|  |  |- 3DGS专用PLY导入器与GaussianSplat资源缓存正式化计划_2026-04-10.md
|  |  |- API文档目录结构第二轮并行任务板_2026-04-09.md
|  |  |- API文档目录结构第二轮重构计划_2026-04-09.md
|  |  |- API文档目录结构重大重构并行任务板_2026-04-09.md
|  |  |- API文档目录结构重构并行任务板_2026-04-09_第二轮.md
|  |  |- API文档目录重构计划_2026-04-09.md
|  |  |- C#脚本模块下一阶段计划.md
|  |  |- Editor架构说明.md
|  |  |- Library启动预热与运行时异步加载混合重构计划_2026-04-04.md
|  |  |- Library启动预热与运行时异步加载混合重构计划_进度更新_2026-04-04.md
|  |  |- NanoVDB体积云加载阻塞与Runtime上传修复计划_2026-04-10.md
|  |  |- Unity SRP API参考文档.md
|  |  |- Unity绝区零开发文档还原版.md
|  |  |- Unity风格模型导入与Model资产架构重构计划_2026-04-10.md
|  |  |- XCUI_NewEditor主线重建计划_2026-04-07.md
|  |  `- XCUI完整架构设计与执行计划.md
|  |- used/                                   # 历史材料、阶段归档和旧计划背景
|  |  |- API文档实时同步任务池_2026-04-03.md
|  |  |- Library资产导入与缓存系统收口计划_完成归档_2026-04-03.md
|  |  |- NanoVDB稀疏体积渲染后续正式化计划_阶段归档_2026-04-10.md
|  |  |- NanoVDB稀疏体积渲染正式集成计划_第一阶段完成归档_2026-04-09.md
|  |  |- Renderer当前阶段正式收口计划_阶段归档_2026-04-10.md
|  |  |- Renderer剩余收口与体积渲染多后端正式化计划_完成归档_2026-04-10.md
|  |  |- Renderer下一阶段_Unity风格Shader体系正式化计划_完成归档_2026-04-07.md
|  |  |- SceneViewport_Overlay_Gizmo_Rework_Plan_完成归档_2026-04-04.md
|  |  |- Unity式SceneView_Gizmo系统完整审查与正式化重构方案_完成归档_2026-04-06.md
|  |  `- XCUI_Phase_Status_2026-04-05.md
|  |- api-skill.md
|  |- blueprint-skill.md
|  `- blueprint.md
|- editor/
|  |- CMakeLists.txt
|  |- README.md
|  |- bin/
|  |- resources/
|  |  `- Icons/
|  `- src/
|     |- Actions/
|     |- Commands/
|     |- ComponentEditors/
|     |- Core/
|     |- Layers/
|     |- Layout/
|     |- Managers/
|     |- panels/
|     |- Platform/
|     |- Scripting/
|     |- UI/
|     |- Utils/
|     |- Viewport/
|     |  |- Passes/
|     |  |- SceneViewportChrome.*
|     |  |- SceneViewportInteractionFrame.h
|     |  |- SceneViewportNavigation.h
|     |  |- SceneViewportOverlayBuilder.*
|     |  |- SceneViewportOverlayFrameCache.*
|     |  |- SceneViewportOverlaySpriteResources.*
|     |  |- SceneViewportPassSpecs.h
|     |  |- SceneViewportPicker.*
|     |  |- SceneViewportResourcePaths.h
|     |  |- SceneViewportTransformGizmoCoordinator.*
|     |  `- ViewportHostService.h
|     |- Application.cpp
|     |- Application.h
|     |- Theme.cpp
|     `- main.cpp
|- engine/
|  |- CMakeLists.txt
|  |- include/
|  |  `- XCEngine/
|  |     |- Audio/
|  |     |- Components/
|  |     |- Core/
|  |     |- Debug/
|  |     |- Input/
|  |     |- Memory/
|  |     |- Platform/
|  |     |- Rendering/
|  |     |  |- Caches/
|  |     |  |- Execution/
|  |     |  |- Extraction/
|  |     |  |- FrameData/
|  |     |  |- Materials/
|  |     |  |- Passes/
|  |     |  |- Picking/
|  |     |  |- Pipelines/
|  |     |  `- Planning/
|  |     |- Resources/
|  |     |  |- AudioClip/
|  |     |  |- Material/
|  |     |  |- Mesh/
|  |     |  |- Shader/
|  |     |  |- Texture/
|  |     |  `- Volume/
|  |     |- RHI/
|  |     |  |- D3D12/
|  |     |  |- OpenGL/
|  |     |  `- Vulkan/
|  |     |- Scene/
|  |     |- Scripting/
|  |     |- Threading/
|  |     `- UI/
|  |- src/
|  |- third_party/
|  `- tools/
|- managed/
|  |- CMakeLists.txt
|  |- GameScripts/
|  `- XCEngine.ScriptCore/
|- mvs/
|  |- 3DGS-Unity/
|  |- D3D12/
|  |- OpenGL/
|  |- RenderDoc/
|  |- ui/
|  `- VolumeRenderer/
|- new_editor/
|  |- app/
|  |  |- Host/
|  |  |- Application.cpp
|  |  |- Application.h
|  |  `- main.cpp
|  |- bin/
|  |- include/
|  |  `- XCEditor/
|  |     |- Collections/
|  |     |- Fields/
|  |     |- Foundation/
|  |     |- Shell/
|  |     `- Widgets/
|  |- src/
|  |  |- Collections/
|  |  |- Fields/
|  |  |- Foundation/
|  |  |- Shell/
|  |  `- Widgets/
|  |- ui/
|  |  |- themes/
|  |  `- views/
|  `- CMakeLists.txt
|- project/
|  |- .xceditor/
|  |  |- imgui_layout.ini
|  |  `- thumbs/
|  |- Assets/
|  |  |- Materials/
|  |  |- Models/
|  |  |- Scenes/
|  |  `- Scripts/
|  |- Library/
|  |  |- ArtifactDB/
|  |  |- Artifacts/
|  |  |- ScriptAssemblies/
|  |  `- SourceAssetDB/
|  |- Assets.meta
|  `- Project.xcproject
|- scripts/
|  `- Run-RendererPhaseRegression.ps1
|- tests/
|  |- CMakeLists.txt
|  |- TEST_SPEC.md
|  |- Components/
|  |- Core/
|  |- Debug/
|  |- Editor/
|  |- Fixtures/
|  |- Input/
|  |- Memory/
|  |- NewEditor/                             # 当前为空的预留测试根目录
|  |- Rendering/
|  |  |- integration/
|  |  |  |- alpha_cutout_scene/
|  |  |  |- camera_post_process_scene/
|  |  |  |- directional_shadow_scene/
|  |  |  |- final_color_scene/
|  |  |  |- multi_light_scene/
|  |  |  |- skybox_scene/
|  |  |  |- volume_occlusion_scene/
|  |  |  |- volume_scene/
|  |  |  `- volume_transform_scene/
|  |  `- unit/
|  |- Resources/
|  |- RHI/
|  |- Scene/
|  |- Scripting/
|  |- Threading/
|  `- UI/
|     |- Core/
|     |- Editor/
|     |- Runtime/
|     `- TEST_SPEC.md
|- 参考/
|  |- Fermion/
|  |- TransformGizmo/
|  |- unity editor/
|  |- unity-editor-icons/
|  |- unity-icons/
|  `- UnityRuntimeSceneGizmo-master/
`- .vscode/
```

## 文档入口

- `docs/api/main.md`
- `editor/README.md`
- `AGENT.md`
- `docs/blueprint.md`
- `tests/TEST_SPEC.md`
- `tests/UI/TEST_SPEC.md`
- `docs/plan/Editor架构说明.md`
- `docs/plan/Library启动预热与运行时异步加载混合重构计划_2026-04-04.md`
- `docs/plan/XCUI_NewEditor主线重建计划_2026-04-07.md`
- `docs/plan/XCUI完整架构设计与执行计划.md`
- `docs/plan/NanoVDB体积云加载阻塞与Runtime上传修复计划_2026-04-10.md`
- `docs/plan/Unity风格模型导入与Model资产架构重构计划_2026-04-10.md`
- `docs/plan/3DGS专用PLY导入器与GaussianSplat资源缓存正式化计划_2026-04-10.md`