374 lines
13 KiB
Markdown
374 lines
13 KiB
Markdown
# 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)
|
||
|
||
## 许可证
|
||
|
||
当前仓库根目录未看到单独的顶层许可证文件；涉及第三方库时请分别遵循对应依赖目录中的许可证说明。
|