XCEngine/README.md

# 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)

## 许可证

当前仓库根目录未看到独立的顶层许可证文件。涉及第三方库时，请分别遵循其所在目录中的许可证或随附说明。