xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6f876678f5fdce789d77750dbc3f7f6101978b77
XCEngine/README.md

13 KiB
Raw Blame History

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

配置工程：

cmake -S . -B build -A x64

如果当前不需要 Mono 脚本运行时：

cmake -S . -B build -A x64 -DXCENGINE_ENABLE_MONO_SCRIPTING=OFF

构建当前正式编辑器：

cmake --build build --config Debug --target XCEditor

运行：

.\editor\bin\Debug\XCEngine.exe

如需构建项目脚本程序集：

cmake --build build --config Debug --target xcengine_project_managed_assemblies

如需构建 XCUI 新编辑器宿主：

cmake --build build --config Debug --target XCUIEditorApp

运行 XCUI 新编辑器宿主：

.\new_editor\bin\Debug\XCUIEditor.exe

测试入口

ctest --test-dir build -N -C Debug
ctest --test-dir build -C Debug --output-on-failure

常用目标：

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/ 中大量历史归档的长尾条目。

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
Reference in New Issue View Git Blame Copy Permalink