XCEngine
XCEngine 是一个 Windows 优先、编辑器优先的模块化 C++ 游戏引擎工作区。当前主线已经形成 RHI -> Rendering -> Editor Viewport -> AssetDatabase/Library -> Mono Scripting 的可运行闭环，不再只是示例代码集合。
这份 README 面向引擎用户：关注怎么进入项目、怎么构建、当前仓库各目录分别负责什么。面向构建本引擎的 coding agent，请看 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. 配置
cmake -S . -B build -A x64
如果本地暂时没有 Mono 依赖，可以先关闭脚本运行时：
cmake -S . -B build -A x64 -DXCENGINE_ENABLE_MONO_SCRIPTING=OFF
2. 构建常用目标
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. 启动编辑器
.\editor\bin\Debug\XCEngine.exe
默认情况下，编辑器会自动把仓库内的 project/ 识别为工程根目录。也可以显式指定其他工程：
.\editor\bin\Debug\XCEngine.exe --project D:\Path\To\MyProject
如果 Inspector 里看不到 C# 脚本类，先确认 project/Library/ScriptAssemblies/ 中已经生成：
XCEngine.ScriptCore.dllGameScripts.dllmscorlib.dll
4. 当前推荐验证入口
ctest --test-dir build -N -C Debug
ctest --test-dir build -C Debug --output-on-failure
按模块常用的构建 / 验证 target：
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、ObjectIdpicking 都已落地。- 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/ 与临时文件。
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
- RHI 基线设计：docs/plan/end/RHI模块设计与实现/RHI模块总览.md
- 当前 Shader / Material 主线：docs/plan/Shader与Material系统下一阶段计划.md
- Scene viewport overlay 重构：docs/plan/SceneViewport_Overlay_Gizmo_Rework_Plan.md
- 测试规范：tests/TEST_SPEC.md
许可证
当前仓库根目录未看到独立的顶层许可证文件。涉及第三方库时，请分别遵循其所在目录中的许可证或随附说明。