XCEngine/README.md

XCEngine

XCEngine 是一个 Windows-first、editor-first 的 C++20 游戏引擎工作区。当前主线围绕 RHI -> Rendering -> Editor -> Asset Pipeline -> Mono Scripting 演进，目标不是堆 sample，而是把可运行的引擎与编辑器主链持续收口成型。

项目定位

• engine/ 提供核心静态库 XCEngine，包含 RHI、Rendering、Resources、Scene、Input、Audio、Scripting 等模块。
• editor/ 是当前正式桌面编辑器，宿主基于 Win32 + D3D12，编辑器 target 名为 XCEditor，输出文件名为 XCEngine.exe。
• new_editor/ 是基于 XCUI 的新编辑器主线，当前仍在并行演进。
• project/ 是随仓库维护的示例工程，已经采用 Assets + .meta + Library 布局。
• tests/ 覆盖 Engine、Rendering、RHI、Editor、Scripting、UI 等主线模块。

当前能力

• RHI 当前维护 D3D12 / OpenGL / Vulkan 三个后端。
• Rendering 已形成 SceneRenderer -> CameraRenderer -> RenderPipeline 主链。
• Scene View 已接通 object-id picking、selection outline、grid、overlay 与 gizmo 渲染。
• 资源系统已采用 AssetDatabase + Artifact + Library 工作流，而不是简单文件直读。
• Material / Shader / Texture / Mesh 已接入正式资源导入与运行时加载链路。
• 编辑器已支持项目加载、Scene/Game viewport、Inspector、Hierarchy、Project 面板等基础闭环。
• Mono C# 脚本运行时与项目脚本程序集构建链路已接入当前工作区。
• new_editor/ 正在推进 XCUI 宿主、控件与 shell 体系。

仓库结构

• engine/：引擎核心实现与公共头文件。
• editor/：当前正式编辑器与 viewport 接线。
• new_editor/：XCUI 新编辑器主线。
• managed/：XCEngine.ScriptCore 与示例托管程序集。
• project/：示例工程与随仓库维护的资产。
• tests/：单元测试、集成测试与阶段性回归入口。
• docs/：架构说明、API 文档、计划与历史归档。
• mvs/：原型、实验工程与外部参考材料。

环境要求

当前推荐在 Windows 上构建和运行。

• Windows 10/11
• Visual Studio 2022 / MSVC v143
• CMake 3.15+
• Vulkan SDK
• .NET SDK
• Git LFS

脚本运行时启用时，还需要：

• 可用的 Mono 依赖，默认路径来自 参考/Fermion/Fermion/external/mono

补充说明：

• 当前根 CMake 配置里，Vulkan SDK 仍是硬依赖。
• NanoVDB 头文件是可选能力，仅影响 .nvdb 体积资源支持。
• 如果仓库里的大资源依赖 Git LFS，请先执行 git lfs pull。

快速开始

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 XCEditor

编辑器产物路径：

• editor/bin/Debug/XCEngine.exe

3. 运行编辑器

.\editor\bin\Debug\XCEngine.exe

显式指定工程目录：

.\editor\bin\Debug\XCEngine.exe --project D:\Path\To\Project

4. 构建项目脚本程序集

如果你要验证 ScriptComponent、脚本类发现或 Inspector 字段编辑，先构建：

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

5. 可选构建 XCUI 新编辑器

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

产物路径通常为：

• 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

更细的测试组织与约定见 tests/TEST_SPEC.md。

文档入口

• 编辑器说明：editor/README.md
• API 文档入口：docs/api/main.md
• 架构蓝图：docs/blueprint.md
• Editor 架构说明：docs/plan/Editor架构说明.md
• 测试规范：tests/TEST_SPEC.md
• 协作约定：AGENT.md

当前状态

XCEngine 仍处于高频迭代阶段，但当前仓库已经不是“零散原型集合”，而是一个以编辑器工作流为中心持续收口的引擎工作区。接口、目录和构建细节仍可能调整，但主线方向已经比较明确：

• 稳定 RHI / Rendering / Asset Pipeline / Editor 主链。
• 继续推进 Mono Scripting 与项目脚本工作流。
• 推进 XCUI 新编辑器主线从组件库走向完整宿主。