XCEngine/README.md

# XCEngine

XCEngine 是一个正在持续开发中的模块化 C++ 游戏引擎。当前仓库已经形成了较完整的底座：

- `RHI` 抽象层已稳定覆盖 `D3D12 / OpenGL / Vulkan`
- `Rendering` 模块已经落地最小可用的场景渲染链路
- `editor/` 已接入基于引擎渲染链路的 Scene/Game viewport
- `managed/` 已具备基于 Mono 的 C# 运行时与托管程序集构建链路
- `tests/` 已形成按模块分层的单元测试与集成测试体系

如果你是第一次进入当前仓库，先看 [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/`，已包含基础场景、背包模型与脚本资产目录。

## 环境要求

建议在 Windows 上构建当前仓库。

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

如果启用默认脚本构建，还需要：

- `参考/Fermion/Fermion/external/mono` 下可用的 Mono 头文件、静态库与 `mscorlib.dll`

如果本地暂时没有 Mono 依赖，可以在配置时关闭脚本构建：

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

如果你需要 `mvs/3DGS-Unity/room.ply` 这类大文件样例，请确保已经执行过 Git LFS 拉取。

## 构建

### 1. 配置

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

### 2. 全量编译

```bash
cmake --build build --config Debug
```

### 3. 常用增量 target

```bash
cmake --build build --config Debug --target XCEngine
cmake --build build --config Debug --target XCVolumeRendererUI2
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 target 名称仍然是历史遗留的 `XCVolumeRendererUI2`，但输出文件名是 `XCEngine.exe`
- 顶层 CMake 当前会纳入 `engine/`、`editor/`、`managed/`、`mvs/RenderDoc/` 与 `tests/`

## 测试

推荐始终通过 CMake / CTest 驱动测试。

### 列出测试

```bash
ctest --test-dir build -N -C Debug
```

### 运行全部测试

```bash
ctest --test-dir build -C Debug --output-on-failure
```

### 常用测试 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 editor_tests
cmake --build build --config Debug --target scripting_tests
```

更完整的测试规则见 [tests/TEST_SPEC.md](tests/TEST_SPEC.md)。

## 目录结构

下面的目录树用于表达当前仓库的实际入口结构与模块边界。

```text
XCEngine/
├── .gitattributes
├── .gitignore
├── AGENT.md
├── CMakeLists.txt
├── README.md
├── build/                            # 本地构建输出
├── docs/
│   ├── api/                          # API 文档
│   ├── issues/                       # 跟踪中的设计 / 实现问题
│   ├── plan/                         # 设计文档、阶段规划、归档方案
│   │   ├── Renderer模块设计与实现.md
│   │   └── end/
│   │       └── RHI模块设计与实现/
│   │           └── RHI模块总览.md
│   ├── used/
│   ├── api-skill.md
│   ├── blueprint-skill.md
│   └── blueprint.md
├── editor/
│   ├── CMakeLists.txt
│   ├── README.md
│   ├── resources/
│   │   └── Icons/
│   ├── src/
│   │   ├── Actions/
│   │   ├── Commands/
│   │   ├── ComponentEditors/
│   │   ├── Core/
│   │   ├── Layers/
│   │   ├── Layout/
│   │   ├── Managers/
│   │   ├── panels/
│   │   ├── Platform/
│   │   ├── UI/
│   │   ├── Utils/
│   │   ├── Viewport/
│   │   ├── Application.cpp
│   │   ├── Application.h
│   │   ├── EditorApp.rc
│   │   ├── Theme.cpp
│   │   ├── Theme.h
│   │   └── main.cpp
│   └── bin/                          # 编辑器输出目录，输出名为 XCEngine.exe
├── engine/
│   ├── CMakeLists.txt
│   ├── include/
│   │   └── XCEngine/
│   │       ├── Audio/
│   │       ├── Components/
│   │       ├── Core/
│   │       │   ├── Asset/
│   │       │   ├── Containers/
│   │       │   ├── IO/
│   │       │   └── Math/
│   │       ├── Debug/
│   │       ├── Input/
│   │       ├── Memory/
│   │       ├── Platform/
│   │       │   └── Windows/
│   │       ├── Rendering/
│   │       │   ├── Pipelines/
│   │       │   ├── CameraRenderRequest.h
│   │       │   ├── CameraRenderer.h
│   │       │   ├── RenderCameraData.h
│   │       │   ├── RenderContext.h
│   │       │   ├── RenderMaterialUtility.h
│   │       │   ├── RenderPipeline.h
│   │       │   ├── RenderPipelineAsset.h
│   │       │   ├── RenderResourceCache.h
│   │       │   ├── RenderSceneExtractor.h
│   │       │   ├── RenderSurface.h
│   │       │   ├── SceneRenderer.h
│   │       │   └── VisibleRenderObject.h
│   │       ├── Resources/
│   │       │   ├── AudioClip/
│   │       │   ├── Material/
│   │       │   ├── Mesh/
│   │       │   ├── Shader/
│   │       │   └── Texture/
│   │       ├── 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
│   │       ├── Scene/
│   │       ├── Scripting/
│   │       │   └── Mono/
│   │       └── Threading/
│   ├── src/
│   │   ├── Audio/
│   │   ├── Components/
│   │   ├── Core/
│   │   │   ├── Asset/
│   │   │   ├── Containers/
│   │   │   ├── IO/
│   │   │   └── Math/
│   │   ├── Debug/
│   │   ├── Input/
│   │   ├── Memory/
│   │   ├── Platform/
│   │   │   └── Windows/
│   │   ├── Rendering/
│   │   │   └── Pipelines/
│   │   ├── Resources/
│   │   │   ├── AudioClip/
│   │   │   ├── Material/
│   │   │   ├── Mesh/
│   │   │   ├── Shader/
│   │   │   └── Texture/
│   │   ├── RHI/
│   │   │   ├── D3D12/
│   │   │   ├── OpenGL/
│   │   │   └── Vulkan/
│   │   ├── Scene/
│   │   ├── Scripting/
│   │   │   └── Mono/
│   │   └── Threading/
│   ├── third_party/
│   │   ├── assimp/
│   │   ├── GLAD/
│   │   ├── kissfft/
│   │   ├── renderdoc/
│   │   └── stb/
│   └── tools/
│       └── renderdoc_parser/
├── managed/
│   ├── CMakeLists.txt
│   ├── GameScripts/                # 示例 / 验证脚本程序集源码
│   └── XCEngine.ScriptCore/        # 引擎托管 API
├── mvs/
│   ├── 3DGS-Unity/                 # Unity 侧 3DGS 参考与资源
│   ├── D3D12/
│   ├── Music fluctuations/
│   ├── OpenGL/
│   ├── RenderDoc/
│   ├── Res/
│   ├── ui/
│   └── VolumeRenderer/
├── project/
│   ├── .xceditor/
│   │   └── imgui_layout.ini
│   ├── Assets/
│   │   ├── Materials/
│   │   ├── Models/
│   │   │   └── backpack/
│   │   ├── Scenes/
│   │   │   └── Main.xc
│   │   └── Scripts/
│   └── Project.xcproject
├── tests/
│   ├── CMakeLists.txt
│   ├── TEST_SPEC.md
│   ├── Components/
│   ├── Core/
│   │   ├── Asset/
│   │   ├── Containers/
│   │   ├── IO/
│   │   └── Math/
│   ├── Debug/
│   ├── Editor/
│   ├── Fixtures/
│   ├── Input/
│   ├── Memory/
│   ├── Rendering/
│   │   ├── integration/
│   │   │   ├── backpack_scene/
│   │   │   ├── cull_material_scene/
│   │   │   ├── depth_sort_scene/
│   │   │   ├── material_state_scene/
│   │   │   ├── offscreen_scene/
│   │   │   ├── textured_quad_scene/
│   │   │   └── transparent_material_scene/
│   │   └── unit/
│   ├── Resources/
│   │   ├── AudioClip/
│   │   ├── Material/
│   │   ├── Mesh/
│   │   ├── 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/
│   ├── Scene/
│   ├── Scripting/
│   └── Threading/
├── 参考/
│   └── TransformGizmo/
└── .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)
- 测试规范：[tests/TEST_SPEC.md](tests/TEST_SPEC.md)

## 许可证

当前仓库根目录未看到单独的顶层许可证文件；涉及第三方库时请分别遵循对应依赖目录中的许可证说明。