413 lines
16 KiB
Markdown
413 lines
16 KiB
Markdown
# XCEngine
|
||
|
||
XCEngine 是一个 Windows 优先、编辑器优先的模块化 C++ 游戏引擎工作区。当前主线已经形成 `RHI -> Rendering -> Editor Viewport -> AssetDatabase/Library -> Mono Scripting` 的可运行闭环，不再只是示例代码集合。
|
||
|
||
这份 README 面向引擎用户：关注怎么进入项目、怎么构建、当前仓库各目录分别负责什么。面向构建本引擎的 coding agent，请看 [AGENT.md](AGENT.md)。
|
||
|
||
## 项目定位
|
||
|
||
- `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 10/11
|
||
- Visual Studio 2022 / MSVC v143
|
||
- CMake 3.15+
|
||
- Vulkan SDK
|
||
- .NET SDK
|
||
- Git LFS
|
||
|
||
启用 Mono 脚本运行时时，还需要：
|
||
|
||
- `参考/Fermion/Fermion/external/mono` 下可用的 Mono 头文件、静态库与 `mscorlib.dll`
|
||
|
||
补充说明：
|
||
|
||
- `engine/CMakeLists.txt` 当前对 `Vulkan` 是硬依赖，未配置 Vulkan SDK 时无法完成配置。
|
||
- `editor/` 和 `tests/` 首次配置会通过 `FetchContent` 从 Gitee 镜像拉取 `ImGui` 与 `googletest`；离线环境请确保已有可复用的 `_deps` 缓存。
|
||
- 如果需要 `mvs/3DGS-Unity/room.ply` 这类大文件示例，请先执行 Git LFS 拉取。
|
||
|
||
## 快速开始
|
||
|
||
### 1. 配置
|
||
|
||
```bash
|
||
cmake -S . -B build -A x64
|
||
```
|
||
|
||
如果本地暂时没有 Mono 依赖，可以先关闭脚本运行时：
|
||
|
||
```bash
|
||
cmake -S . -B build -A x64 -DXCENGINE_ENABLE_MONO_SCRIPTING=OFF
|
||
```
|
||
|
||
### 2. 构建常用目标
|
||
|
||
```bash
|
||
cmake --build build --config Debug --target XCEngine
|
||
cmake --build build --config Debug --target XCEditor
|
||
cmake --build build --config Debug --target xcengine_managed_assemblies
|
||
cmake --build build --config Debug --target xcengine_project_managed_assemblies
|
||
```
|
||
|
||
说明：
|
||
|
||
- `XCEngine` 是引擎静态库。
|
||
- `XCEditor` 是编辑器 target，输出文件名仍为 `editor/bin/<Config>/XCEngine.exe`。
|
||
- `xcengine_managed_assemblies` 生成 `managed/` 示例托管程序集。
|
||
- `xcengine_project_managed_assemblies` 会扫描 `project/Assets/**/*.cs`，并把结果输出到 `project/Library/ScriptAssemblies/`。
|
||
|
||
### 3. 启动编辑器
|
||
|
||
```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
|
||
ctest --test-dir build -C Debug --output-on-failure
|
||
```
|
||
|
||
按模块常用的构建 / 验证 target：
|
||
|
||
```bash
|
||
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
|
||
```
|
||
|
||
## 当前仓库状态
|
||
|
||
### 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/
|
||
├── .gitattributes
|
||
├── .gitignore
|
||
├── AGENT.md
|
||
├── CMakeLists.txt
|
||
├── README.md
|
||
├── build/ # 本地 CMake 构建输出
|
||
├── docs/
|
||
│ ├── 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
|
||
│ └── blueprint.md
|
||
├── editor/
|
||
│ ├── CMakeLists.txt
|
||
│ ├── README.md
|
||
│ ├── resources/
|
||
│ │ └── Icons/
|
||
│ ├── src/
|
||
│ │ ├── Actions/
|
||
│ │ ├── Commands/
|
||
│ │ ├── ComponentEditors/
|
||
│ │ ├── Core/
|
||
│ │ ├── Layers/
|
||
│ │ ├── Layout/
|
||
│ │ ├── Managers/
|
||
│ │ ├── panels/
|
||
│ │ ├── Platform/
|
||
│ │ ├── 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
|
||
├── engine/
|
||
│ ├── CMakeLists.txt
|
||
│ ├── include/
|
||
│ │ └── XCEngine/
|
||
│ │ ├── Audio/
|
||
│ │ ├── Components/
|
||
│ │ ├── Core/
|
||
│ │ │ ├── Asset/
|
||
│ │ │ ├── Containers/
|
||
│ │ │ ├── IO/
|
||
│ │ │ └── Math/
|
||
│ │ ├── Debug/
|
||
│ │ ├── Input/
|
||
│ │ ├── Memory/
|
||
│ │ ├── Platform/
|
||
│ │ │ └── Windows/
|
||
│ │ ├── Rendering/
|
||
│ │ │ ├── Passes/
|
||
│ │ │ ├── Pipelines/
|
||
│ │ │ ├── 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/
|
||
│ │ │ ├── AudioClip/
|
||
│ │ │ ├── Material/
|
||
│ │ │ ├── Mesh/
|
||
│ │ │ ├── Shader/
|
||
│ │ │ └── Texture/
|
||
│ │ ├── RHI/
|
||
│ │ │ ├── D3D12/
|
||
│ │ │ ├── OpenGL/
|
||
│ │ │ └── Vulkan/
|
||
│ │ ├── Scene/
|
||
│ │ ├── Scripting/
|
||
│ │ │ └── Mono/
|
||
│ │ └── Threading/
|
||
│ ├── src/
|
||
│ │ ├── Audio/
|
||
│ │ ├── Components/
|
||
│ │ ├── Core/
|
||
│ │ │ ├── Asset/
|
||
│ │ │ ├── Containers/
|
||
│ │ │ ├── IO/
|
||
│ │ │ └── Math/
|
||
│ │ ├── Debug/
|
||
│ │ ├── Input/
|
||
│ │ ├── Memory/
|
||
│ │ ├── Platform/
|
||
│ │ │ └── Windows/
|
||
│ │ ├── Rendering/
|
||
│ │ │ ├── Passes/
|
||
│ │ │ └── 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/
|
||
├── mvs/
|
||
│ ├── 3DGS-Unity/
|
||
│ ├── D3D12/
|
||
│ ├── Music fluctuations/
|
||
│ ├── OpenGL/
|
||
│ ├── RenderDoc/
|
||
│ ├── Res/
|
||
│ ├── ui/ # 早期 ImGui + D3D12 UI 原型，非当前正式 editor
|
||
│ └── VolumeRenderer/
|
||
├── project/
|
||
│ ├── .xceditor/
|
||
│ │ ├── 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
|
||
│ ├── Components/
|
||
│ ├── Core/
|
||
│ │ ├── Asset/
|
||
│ │ ├── Containers/
|
||
│ │ ├── IO/
|
||
│ │ └── Math/
|
||
│ ├── Debug/
|
||
│ ├── Editor/
|
||
│ ├── Fixtures/
|
||
│ ├── Input/
|
||
│ ├── Memory/
|
||
│ ├── Rendering/
|
||
│ │ ├── integration/
|
||
│ │ │ ├── backpack_lit_scene/
|
||
│ │ │ ├── backpack_scene/
|
||
│ │ │ ├── camera_stack_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/
|
||
│ │ ├── D3D12/
|
||
│ │ │ ├── integration/
|
||
│ │ │ └── unit/
|
||
│ │ ├── integration/
|
||
│ │ │ ├── backpack/
|
||
│ │ │ ├── fixtures/
|
||
│ │ │ ├── minimal/
|
||
│ │ │ ├── quad/
|
||
│ │ │ ├── sphere/
|
||
│ │ │ └── triangle/
|
||
│ │ ├── OpenGL/
|
||
│ │ │ ├── integration/
|
||
│ │ │ └── unit/
|
||
│ │ ├── unit/
|
||
│ │ └── Vulkan/
|
||
│ │ ├── integration/
|
||
│ │ └── unit/
|
||
│ ├── Scene/
|
||
│ ├── Scripting/
|
||
│ └── Threading/
|
||
├── 参考/
|
||
│ ├── Fermion/
|
||
│ ├── TransformGizmo/
|
||
│ ├── unity editor/
|
||
│ ├── unity-editor-icons/
|
||
│ ├── unity-icons/
|
||
│ └── UnityRuntimeSceneGizmo-master/
|
||
└── .vscode/
|
||
```
|
||
|
||
## 关键文档入口
|
||
|
||
- 协作基线与 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)
|
||
|
||
## 许可证
|
||
|
||
当前仓库根目录未看到独立的顶层许可证文件。涉及第三方库时，请分别遵循其所在目录中的许可证或随附说明。
|