444 lines
13 KiB
Markdown
444 lines
13 KiB
Markdown
# XCEngine
|
||
|
||
`XCEngine` 是一个 Windows-first、editor-first 的 `C++20` 游戏引擎工作区。当前代码中已经形成 `RHI`、`Rendering`、`Scene`、`Resources`、`Editor`、`Mono C# Scripting` 和 `XCUI` 相关主线；本 README 只描述当前已经实现、已经接入或已经成为正式工作流一部分的能力。
|
||
|
||
## 核心特性
|
||
|
||
### 渲染
|
||
|
||
- 内置跨后端 `RHI` 抽象层，当前支持 `D3D12`、`OpenGL`、`Vulkan`
|
||
- 当前主渲染链为 `SceneRenderer -> CameraRenderer -> BuiltinForwardPipeline`
|
||
- 已接入前向渲染主路径、透明路径和 skybox 路径
|
||
- 已具备方向光阴影通路
|
||
- 已具备 `object-id` pass，可用于编辑器拾取
|
||
- 已具备选中描边、最终颜色合成和颜色缩放后处理 pass
|
||
- 已具备无限网格 pass，可用于 Scene View
|
||
- 已接入 `NanoVDB` 体积渲染 pass
|
||
- `RenderSurface` 允许同一条渲染链服务于窗口输出、编辑器视口和离屏目标
|
||
|
||
### 场景与运行时
|
||
|
||
- 采用 `Scene / GameObject / Component` 结构
|
||
- 已具备场景更新、运行时驱动和场景序列化能力
|
||
- 内置常用组件，包括：
|
||
- `TransformComponent`
|
||
- `CameraComponent`
|
||
- `LightComponent`
|
||
- `MeshFilterComponent`
|
||
- `MeshRendererComponent`
|
||
- `VolumeRendererComponent`
|
||
- `AudioSourceComponent`
|
||
- `AudioListenerComponent`
|
||
- `ScriptComponent`
|
||
|
||
### 资源系统
|
||
|
||
- 资源主线不是简单文件直读，而是 `AssetDatabase + Artifact + Library` 工作流
|
||
- 已具备项目资产索引、导入、重导入和缓存维护链路
|
||
- 已接入的资源类型包括：
|
||
- `Mesh`
|
||
- `Texture`
|
||
- `Shader`
|
||
- `Material`
|
||
- `AudioClip`
|
||
- `VolumeField`
|
||
- `UI Document`
|
||
- 内置 `builtin://` 资源入口，可直接使用基础 mesh、材质等内置资源
|
||
|
||
### 脚本系统
|
||
|
||
- 可选启用基于 `Mono` 的 `C#` 脚本运行时
|
||
- 托管程序集分为：
|
||
- `XCEngine.ScriptCore`
|
||
- `GameScripts`
|
||
- 脚本组件由 `ScriptComponent` 承载
|
||
- 引擎当前支持脚本类发现、字段元数据读取、默认值读取和字段存储
|
||
- 支持脚本字段 override 持久化与运行时同步
|
||
- 编辑器已接入项目脚本程序集重建与脚本运行时重载
|
||
|
||
### 编辑器
|
||
|
||
- 当前正式编辑器是基于 `Win32 + D3D12 + ImGui` 的桌面编辑器
|
||
- 当前已具备以下基础工作流：
|
||
- `Hierarchy`
|
||
- `Inspector`
|
||
- `Project`
|
||
- `Console`
|
||
- `Scene View`
|
||
- `Game View`
|
||
- `Scene View` 已接入：
|
||
- object-id picking
|
||
- selection outline
|
||
- overlay
|
||
- transform gizmo
|
||
- infinite grid
|
||
- `Inspector` 已能处理常规组件检查，也已接入 `ScriptComponent` 与材质资源检查路径
|
||
- 编辑器能够识别项目目录、加载项目资源、接通 `Library/ScriptAssemblies` 中的脚本程序集
|
||
|
||
### UI 与 XCUI
|
||
|
||
- 引擎内部包含 retained-mode UI 基础设施
|
||
- 已具备：
|
||
- 布局系统
|
||
- 样式系统
|
||
- 焦点控制
|
||
- 输入分发
|
||
- 快捷键分发
|
||
- 文本输入编辑
|
||
- 选择模型
|
||
- 拖拽交互模型
|
||
- 运行时 UI 主链包括：
|
||
- `UIScreenDocumentHost`
|
||
- `UIScreenPlayer`
|
||
- `UISystem`
|
||
- `tests/UI/` 是当前 XCUI `Core / Editor / Runtime` 三层的正式基础层验证入口
|
||
- `new_editor/` 是未来正式编辑器主线，不再只是临时沙盒；当前已经包含树视图、列表视图、菜单、标签条、属性网格、字段控件、workspace / dock / viewport shell 等基础组件
|
||
|
||
### 音频
|
||
|
||
- 已具备 `AudioSystem`
|
||
- 已接入 `AudioSourceComponent` 与 `AudioListenerComponent`
|
||
- 当前代码中已包含 `AudioMixer` 和多种效果器/分析器实现入口：
|
||
- `Equalizer`
|
||
- `FFTFilter`
|
||
- `Reverbation`
|
||
- `HRTF`
|
||
|
||
### 测试
|
||
|
||
- 引擎不是“只靠手工点点看”的状态，当前已具备大规模测试树
|
||
- 覆盖范围包括：
|
||
- Engine 基础模块
|
||
- Rendering
|
||
- RHI
|
||
- Editor
|
||
- Scripting
|
||
- UI
|
||
- `RHI` 集成测试使用统一基准图做 golden-image 对比
|
||
- `XCUI` 当前也有独立的 unit / integration 验证链路
|
||
|
||
## 当前实现范围
|
||
|
||
- 当前正式编辑器为基于 `Win32 + D3D12 + ImGui` 的桌面编辑器
|
||
- 当前 `RHI` 后端为 `D3D12`、`OpenGL`、`Vulkan`
|
||
- 当前项目资产工作流已经接入 `AssetDatabase + Artifact + Library`
|
||
- 当前 `Mono C#` 脚本程序集与运行时链路已经接入
|
||
- 当前 `XCUI` 新编辑器路线以 `new_editor/` 为正式主线继续推进
|
||
|
||
## 快速开始
|
||
|
||
推荐环境：
|
||
|
||
- Windows 10/11
|
||
- Visual Studio 2022 / MSVC v143
|
||
- CMake 3.15+
|
||
- Vulkan SDK
|
||
- .NET SDK
|
||
|
||
配置工程：
|
||
|
||
```powershell
|
||
cmake -S . -B build -A x64
|
||
```
|
||
|
||
如果当前不需要 Mono 脚本运行时：
|
||
|
||
```powershell
|
||
cmake -S . -B build -A x64 -DXCENGINE_ENABLE_MONO_SCRIPTING=OFF
|
||
```
|
||
|
||
构建当前正式编辑器：
|
||
|
||
```powershell
|
||
cmake --build build --config Debug --target XCEditor
|
||
```
|
||
|
||
运行：
|
||
|
||
```powershell
|
||
.\editor\bin\Debug\XCEngine.exe
|
||
```
|
||
|
||
如需构建项目脚本程序集：
|
||
|
||
```powershell
|
||
cmake --build build --config Debug --target xcengine_project_managed_assemblies
|
||
```
|
||
|
||
如需构建 XCUI 新编辑器宿主：
|
||
|
||
```powershell
|
||
cmake --build build --config Debug --target XCUIEditorApp
|
||
```
|
||
|
||
运行 XCUI 新编辑器宿主：
|
||
|
||
```powershell
|
||
.\new_editor\bin\Debug\XCUIEditor.exe
|
||
```
|
||
|
||
## 测试入口
|
||
|
||
```powershell
|
||
ctest --test-dir build -N -C Debug
|
||
ctest --test-dir build -C Debug --output-on-failure
|
||
```
|
||
|
||
常用目标：
|
||
|
||
```powershell
|
||
cmake --build build --config Debug --target editor_tests
|
||
cmake --build build --config Debug --target rendering_all_tests
|
||
cmake --build build --config Debug --target rhi_all_tests
|
||
cmake --build build --config Debug --target scripting_tests
|
||
cmake --build build --config Debug --target core_ui_all_tests
|
||
cmake --build build --config Debug --target editor_ui_all_tests
|
||
cmake --build build --config Debug --target runtime_ui_all_tests
|
||
```
|
||
|
||
## 完整目录结构
|
||
|
||
以下目录树按当前工作树整理，保留了真实使用的生成目录与关键子树；省略了 `.git/`、`build/_deps/`、部分重复资源文件，以及 `docs/used/` 中大量历史归档的长尾条目。
|
||
|
||
```text
|
||
XCEngine/
|
||
|- .gitattributes
|
||
|- .gitignore
|
||
|- AGENT.md
|
||
|- CMakeLists.txt
|
||
|- README.md
|
||
|- build/ # 本地 CMake 构建输出
|
||
|- docs/
|
||
| |- api/
|
||
| | |- XCEngine/
|
||
| | |- _guides/
|
||
| | |- _meta/
|
||
| | |- _tools/
|
||
| | `- main.md
|
||
| |- issues/
|
||
| | `- Editor模块_Console面板错误绑定fallback sink导致运行时日志不显示4.3.md
|
||
| |- plan/
|
||
| | |- end/
|
||
| | | |- RHI模块设计与实现/
|
||
| | | | |- RHIFence.md
|
||
| | | | `- RHI模块总览.md
|
||
| | | `- 编辑器与运行时分层架构设计.md
|
||
| | |- 开题报告和任务书/
|
||
| | |- 旧版题目/
|
||
| | |- 3DGS专用PLY导入器与GaussianSplat资源缓存正式化计划_2026-04-10.md
|
||
| | |- API文档目录结构第二轮并行任务板_2026-04-09.md
|
||
| | |- API文档目录结构第二轮重构计划_2026-04-09.md
|
||
| | |- API文档目录结构重大重构并行任务板_2026-04-09.md
|
||
| | |- API文档目录结构重构并行任务板_2026-04-09_第二轮.md
|
||
| | |- API文档目录重构计划_2026-04-09.md
|
||
| | |- C#脚本模块下一阶段计划.md
|
||
| | |- Editor架构说明.md
|
||
| | |- Library启动预热与运行时异步加载混合重构计划_2026-04-04.md
|
||
| | |- Library启动预热与运行时异步加载混合重构计划_进度更新_2026-04-04.md
|
||
| | |- NanoVDB体积云加载阻塞与Runtime上传修复计划_2026-04-10.md
|
||
| | |- Unity SRP API参考文档.md
|
||
| | |- Unity绝区零开发文档还原版.md
|
||
| | |- Unity风格模型导入与Model资产架构重构计划_2026-04-10.md
|
||
| | |- XCUI_NewEditor主线重建计划_2026-04-07.md
|
||
| | `- XCUI完整架构设计与执行计划.md
|
||
| |- used/ # 历史材料、阶段归档和旧计划背景
|
||
| | |- API文档实时同步任务池_2026-04-03.md
|
||
| | |- Library资产导入与缓存系统收口计划_完成归档_2026-04-03.md
|
||
| | |- NanoVDB稀疏体积渲染后续正式化计划_阶段归档_2026-04-10.md
|
||
| | |- NanoVDB稀疏体积渲染正式集成计划_第一阶段完成归档_2026-04-09.md
|
||
| | |- Renderer当前阶段正式收口计划_阶段归档_2026-04-10.md
|
||
| | |- Renderer剩余收口与体积渲染多后端正式化计划_完成归档_2026-04-10.md
|
||
| | |- Renderer下一阶段_Unity风格Shader体系正式化计划_完成归档_2026-04-07.md
|
||
| | |- SceneViewport_Overlay_Gizmo_Rework_Plan_完成归档_2026-04-04.md
|
||
| | |- Unity式SceneView_Gizmo系统完整审查与正式化重构方案_完成归档_2026-04-06.md
|
||
| | `- XCUI_Phase_Status_2026-04-05.md
|
||
| |- api-skill.md
|
||
| |- blueprint-skill.md
|
||
| `- blueprint.md
|
||
|- editor/
|
||
| |- CMakeLists.txt
|
||
| |- README.md
|
||
| |- bin/
|
||
| |- resources/
|
||
| | `- Icons/
|
||
| `- src/
|
||
| |- Actions/
|
||
| |- Commands/
|
||
| |- ComponentEditors/
|
||
| |- Core/
|
||
| |- Layers/
|
||
| |- Layout/
|
||
| |- Managers/
|
||
| |- panels/
|
||
| |- Platform/
|
||
| |- Scripting/
|
||
| |- UI/
|
||
| |- Utils/
|
||
| |- Viewport/
|
||
| | |- Passes/
|
||
| | |- SceneViewportChrome.*
|
||
| | |- SceneViewportInteractionFrame.h
|
||
| | |- SceneViewportNavigation.h
|
||
| | |- SceneViewportOverlayBuilder.*
|
||
| | |- SceneViewportOverlayFrameCache.*
|
||
| | |- SceneViewportOverlaySpriteResources.*
|
||
| | |- SceneViewportPassSpecs.h
|
||
| | |- SceneViewportPicker.*
|
||
| | |- SceneViewportResourcePaths.h
|
||
| | |- SceneViewportTransformGizmoCoordinator.*
|
||
| | `- ViewportHostService.h
|
||
| |- Application.cpp
|
||
| |- Application.h
|
||
| |- Theme.cpp
|
||
| `- main.cpp
|
||
|- engine/
|
||
| |- CMakeLists.txt
|
||
| |- include/
|
||
| | `- XCEngine/
|
||
| | |- Audio/
|
||
| | |- Components/
|
||
| | |- Core/
|
||
| | |- Debug/
|
||
| | |- Input/
|
||
| | |- Memory/
|
||
| | |- Platform/
|
||
| | |- Rendering/
|
||
| | | |- Caches/
|
||
| | | |- Execution/
|
||
| | | |- Extraction/
|
||
| | | |- FrameData/
|
||
| | | |- Materials/
|
||
| | | |- Passes/
|
||
| | | |- Picking/
|
||
| | | |- Pipelines/
|
||
| | | `- Planning/
|
||
| | |- Resources/
|
||
| | | |- AudioClip/
|
||
| | | |- Material/
|
||
| | | |- Mesh/
|
||
| | | |- Shader/
|
||
| | | |- Texture/
|
||
| | | `- Volume/
|
||
| | |- RHI/
|
||
| | | |- D3D12/
|
||
| | | |- OpenGL/
|
||
| | | `- Vulkan/
|
||
| | |- Scene/
|
||
| | |- Scripting/
|
||
| | |- Threading/
|
||
| | `- UI/
|
||
| |- src/
|
||
| |- third_party/
|
||
| `- tools/
|
||
|- managed/
|
||
| |- CMakeLists.txt
|
||
| |- GameScripts/
|
||
| `- XCEngine.ScriptCore/
|
||
|- mvs/
|
||
| |- 3DGS-Unity/
|
||
| |- D3D12/
|
||
| |- OpenGL/
|
||
| |- RenderDoc/
|
||
| |- ui/
|
||
| `- VolumeRenderer/
|
||
|- new_editor/
|
||
| |- app/
|
||
| | |- Host/
|
||
| | |- Application.cpp
|
||
| | |- Application.h
|
||
| | `- main.cpp
|
||
| |- bin/
|
||
| |- include/
|
||
| | `- XCEditor/
|
||
| | |- Collections/
|
||
| | |- Fields/
|
||
| | |- Foundation/
|
||
| | |- Shell/
|
||
| | `- Widgets/
|
||
| |- src/
|
||
| | |- Collections/
|
||
| | |- Fields/
|
||
| | |- Foundation/
|
||
| | |- Shell/
|
||
| | `- Widgets/
|
||
| |- ui/
|
||
| | |- themes/
|
||
| | `- views/
|
||
| `- CMakeLists.txt
|
||
|- project/
|
||
| |- .xceditor/
|
||
| | |- imgui_layout.ini
|
||
| | `- thumbs/
|
||
| |- Assets/
|
||
| | |- Materials/
|
||
| | |- Models/
|
||
| | |- Scenes/
|
||
| | `- Scripts/
|
||
| |- Library/
|
||
| | |- ArtifactDB/
|
||
| | |- Artifacts/
|
||
| | |- ScriptAssemblies/
|
||
| | `- SourceAssetDB/
|
||
| |- Assets.meta
|
||
| `- Project.xcproject
|
||
|- scripts/
|
||
| `- Run-RendererPhaseRegression.ps1
|
||
|- tests/
|
||
| |- CMakeLists.txt
|
||
| |- TEST_SPEC.md
|
||
| |- Components/
|
||
| |- Core/
|
||
| |- Debug/
|
||
| |- Editor/
|
||
| |- Fixtures/
|
||
| |- Input/
|
||
| |- Memory/
|
||
| |- NewEditor/ # 当前为空的预留测试根目录
|
||
| |- Rendering/
|
||
| | |- integration/
|
||
| | | |- alpha_cutout_scene/
|
||
| | | |- camera_post_process_scene/
|
||
| | | |- directional_shadow_scene/
|
||
| | | |- final_color_scene/
|
||
| | | |- multi_light_scene/
|
||
| | | |- skybox_scene/
|
||
| | | |- volume_occlusion_scene/
|
||
| | | |- volume_scene/
|
||
| | | `- volume_transform_scene/
|
||
| | `- unit/
|
||
| |- Resources/
|
||
| |- RHI/
|
||
| |- Scene/
|
||
| |- Scripting/
|
||
| |- Threading/
|
||
| `- UI/
|
||
| |- Core/
|
||
| |- Editor/
|
||
| |- Runtime/
|
||
| `- TEST_SPEC.md
|
||
|- 参考/
|
||
| |- Fermion/
|
||
| |- TransformGizmo/
|
||
| |- unity editor/
|
||
| |- unity-editor-icons/
|
||
| |- unity-icons/
|
||
| `- UnityRuntimeSceneGizmo-master/
|
||
`- .vscode/
|
||
```
|
||
|
||
## 文档入口
|
||
|
||
- `docs/api/main.md`
|
||
- `editor/README.md`
|
||
- `AGENT.md`
|
||
- `docs/blueprint.md`
|
||
- `tests/TEST_SPEC.md`
|
||
- `tests/UI/TEST_SPEC.md`
|
||
- `docs/plan/Editor架构说明.md`
|
||
- `docs/plan/Library启动预热与运行时异步加载混合重构计划_2026-04-04.md`
|
||
- `docs/plan/XCUI_NewEditor主线重建计划_2026-04-07.md`
|
||
- `docs/plan/XCUI完整架构设计与执行计划.md`
|
||
- `docs/plan/NanoVDB体积云加载阻塞与Runtime上传修复计划_2026-04-10.md`
|
||
- `docs/plan/Unity风格模型导入与Model资产架构重构计划_2026-04-10.md`
|
||
- `docs/plan/3DGS专用PLY导入器与GaussianSplat资源缓存正式化计划_2026-04-10.md`
|