Files

ssdfasd 31756847ab docs: sync api and planning docs

2026-04-08 16:07:03 +08:00

19 KiB

Raw Blame History

XCEngine

XCEngine 是一个 Windows 优先、编辑器优先的模块化 C++ 游戏引擎工作区。当前主线已经形成 RHI -> Rendering -> Editor Viewport -> AssetDatabase/Library -> Mono Scripting 的可运行闭环，不再只是若干独立 sample 的集合。

这份 README 面向引擎用户：重点回答项目是什么、当前能做什么、怎么构建、怎么启动，以及当前仓库各目录分别承担什么职责。面向参与引擎实现和文档维护的 coding agent，请看 AGENT.md。

项目定位

engine/ 构建静态库 XCEngine，包含 RHI、Rendering、Resources、Scene、Scripting 等核心模块。
editor/ 构建桌面编辑器 XCEditor，输出文件名仍为 XCEngine.exe，默认打开仓库内的 project/。
new_editor/ 维护基于 XCUI 的新宿主与 UI sandbox，当前与旧 editor/ 并行演进，应用输出名为 XCUIEditor.exe。
project/ 是随仓库维护的示例工程，已经采用 Assets/ + .meta + Library/ 的工程布局。
managed/ 负责 XCEngine.ScriptCore.dll、示例 GameScripts.dll 以及项目脚本程序集构建。
tests/ 覆盖 Engine、RHI、Rendering、Editor、Scripting、XCUI 等主线模块。

当前能力概览

RHI 当前维护 D3D12 / OpenGL / Vulkan 三后端。
Rendering 已形成 SceneRenderer -> CameraRenderer -> RenderPipeline 主链，支持 ObjectId、InfiniteGrid、Outline、overlayPasses 等能力。
Core/Asset 已经不是简单加载器，当前真实维护 Assets/.meta/Library 风格的 AssetDatabase、artifact 缓存和项目资源索引。
Library 当前已经采用“启动阶段恢复索引与缓存状态 + 运行时按需异步恢复 payload”的混合工作流，BootstrapProject() 已接入正式启动链路。
Material 与材质 artifact 已经进入稳定格式阶段，当前 .xcmat 使用 schema v2。
编辑器 Scene/Game viewport 已通过引擎 Rendering + RHI 链路渲染到离屏纹理，再接入 ImGui。
ScriptComponent 已打通脚本类发现、字段元数据读取、字段编辑和运行时字段同步。

环境要求

当前推荐在 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/ 中已经生成下面这 3 个程序集。当前工作树如果暂时缺少 XCEngine.ScriptCore.dll，通常说明项目脚本程序集还没有按最新状态完成重建：

XCEngine.ScriptCore.dll
GameScripts.dll
mscorlib.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，而不是 sample 私有渲染分支。
Resources 与 Core/Asset 已形成项目资源导入、artifact 缓存和运行时加载的统一链路。

Editor

当前 editor 是 D3D12 宿主应用，但 Scene/Game viewport 渲染本身走引擎 Rendering + RHI。
Viewport 子系统当前已经拆成更清晰的链路：SceneViewportChrome -> SceneViewportInteractionFrame -> SceneViewportNavigation -> SceneViewportTransformGizmoCoordinator -> ViewportHostService。
tests/Editor/ 已覆盖 SceneViewportChrome、SceneViewportInteractionFrame、SceneViewportNavigation、SceneViewportTransformGizmoCoordinator 等新 helper。

Project & Scripting

示例工程位于 project/，工程文件是 Project.xcproject，启动场景为 Assets/Scenes/Main.xc。
project/Library/ 虽然是生成目录，但在当前 workflow 里承担 SourceAssetDB、ArtifactDB、Artifacts、ScriptAssemblies 等关键角色。
managed/ 会生成引擎脚本 API 与示例脚本程序集，项目资产下的 .cs 文件也会单独编译为项目脚本程序集。

Tests

tests/ 已覆盖 Core、Memory、Threading、Scene、Resources、RHI、Rendering、Editor、Scripting 等主线模块。
tests/Rendering/ 当前维护一组集成场景测试。
tests/RHI/ 同时维护抽象层测试与后端专用测试。

完整目录结构

以下目录树按当前工作树整理，保留了当前 workflow 已经真实使用的生成目录与关键子树；省略 .git/、build/_deps/ 与部分重复资源文件。像 project/.xceditor/thumbs/、project/Library/Artifacts/ 这类会随本地导入状态变化的内容，用结构模式表示。

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
|  |  |- 开题报告和任务书/
|  |  |- 旧版题目/
|  |  |- API文档实时同步任务池_2026-04-03.md
|  |  |- C#脚本模块下一阶段计划.md
|  |  |- Editor架构说明.md
|  |  |- Library启动预热与运行时异步加载混合重构计划_2026-04-04.md
|  |  |- Library启动预热与运行时异步加载混合重构计划_进度更新_2026-04-04.md
|  |  |- Renderer下一阶段_Unity风格Shader体系正式化计划_2026-04-06.md
|  |  |- Unity SRP API参考文档.md
|  |  |- XCUI_Phase_Status_2026-04-05.md
|  |  |- XCUI完整架构设计与执行计划.md
|  |  `- Unity绝区零开发文档还原版.md
|  |- used/                                   # 历史材料、归档计划与截图
|  |  |- API文档实时同步任务池_2026-04-03_第一轮归档.md
|  |  |- API文档实时同步任务池_2026-04-03_第二轮归档.md
|  |  |- C#脚本模块的设计与实现_阶段一归档_2026-04-03.md
|  |  |- Library资产导入与缓存系统收口计划_完成归档_2026-04-03.md
|  |  |- Renderer结构收口与代码正式化计划_完成归档_2026-04-05.md
|  |  |- SceneViewport_Overlay_Gizmo_Rework_Plan_完成归档_2026-04-04.md
|  |  |- Shader与Material系统下一阶段计划_完成归档_2026-04-04.md
|  |  |- Unity式SceneView_Gizmo系统完整审查与正式化重构方案_完成归档_2026-04-06.md
|  |  |- Unity式Tick系统与PlayMode运行时方案-阶段进展.md
|  |  `- Unity式Tick系统与PlayMode运行时方案.md
|  |- api-skill.md
|  |- blueprint-skill.md
|  `- blueprint.md
|- editor/
|  |- CMakeLists.txt
|  |- README.md
|  |- bin/                                   # 编辑器输出目录，产物名为 XCEngine.exe
|  |- resources/
|  |  `- Icons/
|  `- src/
|     |- Actions/
|     |- Commands/
|     |- ComponentEditors/
|     |- Core/
|     |- Layers/
|     |- Layout/
|     |- Managers/
|     |- panels/
|     |  |- ConsolePanel.cpp
|     |  |- ConsolePanel.h
|     |  |- GameViewPanel.cpp
|     |  |- GameViewPanel.h
|     |  |- HierarchyPanel.cpp
|     |  |- HierarchyPanel.h
|     |  |- InspectorPanel.cpp
|     |  |- InspectorPanel.h
|     |  |- MenuBar.cpp
|     |  |- MenuBar.h
|     |  |- Panel.cpp
|     |  |- Panel.h
|     |  |- PanelCollection.h
|     |  |- ProjectPanel.cpp
|     |  |- ProjectPanel.h
|     |  |- SceneViewPanel.cpp
|     |  |- SceneViewPanel.h
|     |  `- ViewportPanelContent.h
|     |- Platform/
|     |- Scripting/
|     |- UI/
|     |- Utils/
|     |- Viewport/
|     |  |- Passes/
|     |  |  |- SceneViewportEditorOverlayPass.cpp
|     |  |  |- SceneViewportEditorOverlayPass.h
|     |  |  |- SceneViewportGridPass.cpp
|     |  |  |- SceneViewportGridPass.h
|     |  |  |- SceneViewportSelectionOutlinePass.cpp
|     |  |  `- SceneViewportSelectionOutlinePass.h
|     |  |- IViewportHostService.h
|     |  |- SceneViewportCameraController.h
|     |  |- SceneViewportChrome.cpp
|     |  |- SceneViewportChrome.h
|     |  |- SceneViewportEditorModes.h
|     |  |- SceneViewportEditorOverlayData.h
|     |  |- SceneViewportHudOverlay.cpp
|     |  |- SceneViewportHudOverlay.h
|     |  |- SceneViewportInteractionActions.cpp
|     |  |- SceneViewportInteractionActions.h
|     |  |- SceneViewportInteractionFrame.h
|     |  |- SceneViewportInteractionResolver.cpp
|     |  |- SceneViewportInteractionResolver.h
|     |  |- SceneViewportMath.h
|     |  |- SceneViewportMoveGizmo.cpp
|     |  |- SceneViewportMoveGizmo.h
|     |  |- SceneViewportNavigation.h
|     |  |- SceneViewportOrientationGizmo.cpp
|     |  |- SceneViewportOrientationGizmo.h
|     |  |- SceneViewportOverlayBuilder.cpp
|     |  |- SceneViewportOverlayBuilder.h
|     |  |- SceneViewportOverlayFrameCache.cpp
|     |  |- SceneViewportOverlayFrameCache.h
|     |  |- SceneViewportOverlayHandleBuilder.h
|     |  |- SceneViewportOverlayHitTester.h
|     |  |- SceneViewportOverlayProviders.cpp
|     |  |- SceneViewportOverlayProviders.h
|     |  |- SceneViewportOverlaySpriteResources.cpp
|     |  |- SceneViewportOverlaySpriteResources.h
|     |  |- SceneViewportPassSpecs.h
|     |  |- SceneViewportPicker.cpp
|     |  |- SceneViewportPicker.h
|     |  |- SceneViewportRenderPlan.h
|     |  |- SceneViewportResourcePaths.h
|     |  |- SceneViewportRotateGizmo.cpp
|     |  |- SceneViewportRotateGizmo.h
|     |  |- SceneViewportScaleGizmo.cpp
|     |  |- SceneViewportScaleGizmo.h
|     |  |- SceneViewportShaderPaths.h
|     |  |- SceneViewportTransformGizmoCoordinator.cpp
|     |  |- SceneViewportTransformGizmoCoordinator.h
|     |  |- SceneViewportTransformGizmoFrameBuilder.h
|     |  |- ViewportHostRenderFlowUtils.h
|     |  |- ViewportHostRenderTargets.h
|     |  |- ViewportHostService.h
|     |  |- ViewportHostSurfaceUtils.h
|     |  `- ViewportObjectIdPicker.h
|     |- Application.cpp
|     |- Application.h
|     |- EditorApp.rc
|     |- EditorResources.h
|     |- Theme.cpp
|     |- Theme.h
|     `- main.cpp
|- engine/
|  |- CMakeLists.txt
|  |- include/
|  |  `- XCEngine/
|  |     |- Audio/
|  |     |- Components/
|  |     |- Core/
|  |     |  |- Asset/
|  |     |  |- Containers/
|  |     |  |- IO/
|  |     |  `- Math/
|  |     |- Debug/
|  |     |- Input/
|  |     |- Memory/
|  |     |- Platform/
|  |     |  `- Windows/
|  |     |- Rendering/
|  |     |  |- Passes/
|  |     |  |- Pipelines/
|  |     |  |- CameraRenderer.h
|  |     |  |- CameraRenderRequest.h
|  |     |  |- ObjectIdPass.h
|  |     |  |- RenderPipeline.h
|  |     |  |- RenderSurface.h
|  |     |  `- SceneRenderer.h
|  |     |- Resources/
|  |     |  |- AudioClip/
|  |     |  |- Material/
|  |     |  |- Mesh/
|  |     |  |- Shader/
|  |     |  `- Texture/
|  |     |- RHI/
|  |     |  |- D3D12/
|  |     |  |- OpenGL/
|  |     |  `- Vulkan/
|  |     |- Scene/
|  |     |- Scripting/
|  |     |  `- Mono/
|  |     `- Threading/
|  |- src/                                   # 与 include/XCEngine 中的主模块一一对应
|  |- 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 原型
|  `- VolumeRenderer/
|- new_editor/
|  |- app/
|  |  |- Host/
|  |  |- Application.cpp
|  |  |- Application.h
|  |  `- main.cpp
|  |- bin/                                   # XCUIEditor.exe 输出目录
|  |- include/
|  |  `- XCEditor/
|  |     |- Core/
|  |     `- Widgets/
|  |- src/
|  |  |- Core/
|  |  |- Platform/
|  |  `- Widgets/
|  |- ui/
|  `- CMakeLists.txt
|- project/
|  |- .xceditor/
|  |  |- imgui_layout.ini
|  |  `- thumbs/
|  |- Assets/
|  |  |- Materials/
|  |  |- Materials.meta
|  |  |- Models/
|  |  |- Models.meta
|  |  |- New Folder.meta
|  |  |- New Folder 1.meta
|  |  |- New Material.mat
|  |  |- New Material.mat.meta
|  |  |- Scenes/
|  |  |  |- Backpack.xc
|  |  |  |- Backpack.xc.meta
|  |  |  |- Main.xc
|  |  |  |- Main.xc.meta
|  |  |  |- NewFolder.meta
|  |  |  `- NewFolder/
|  |  |- Scenes.meta
|  |  |- Scripts/
|  |  |  |- ProjectScriptProbe.cs
|  |  |  |- ProjectScriptProbe.cs.meta
|  |  |  |- Textures/
|  |  |  |- Textures.meta
|  |  |  |- TickLogProbe.cs
|  |  |  `- TickLogProbe.cs.meta
|  |  `- Scripts.meta
|  |- Library/
|  |  |- ArtifactDB/
|  |  |  `- artifacts.db
|  |  |- Artifacts/
|  |  |  `- <bucket>/<artifact-id>/
|  |  |- ScriptAssemblies/
|  |  |  |- GameScripts.dll
|  |  |  `- mscorlib.dll
|  |  `- SourceAssetDB/
|  |     `- assets.db
|  |- Assets.meta
|  `- Project.xcproject
|- scripts/
|  `- Run-RendererPhaseRegression.ps1
|- tests/
|  |- CMakeLists.txt
|  |- TEST_SPEC.md
|  |- Components/
|  |- Core/
|  |  |- Asset/
|  |  |- Containers/
|  |  |- IO/
|  |  `- Math/
|  |- Debug/
|  |- Editor/
|  |  |- CMakeLists.txt
|  |  |- test_action_routing.cpp
|  |  |- test_application_asset_cache_stub.cpp
|  |  |- test_builtin_icon_layout_utils.cpp
|  |  |- test_editor_console_sink.cpp
|  |  |- test_editor_script_assembly_builder.cpp
|  |  |- test_editor_script_assembly_builder_utils.cpp
|  |  |- test_play_session_controller.cpp
|  |  |- test_play_session_controller_scripting.cpp
|  |  |- test_scene_viewport_camera_controller.cpp
|  |  |- test_scene_viewport_chrome.cpp
|  |  |- test_scene_viewport_interaction_actions.cpp
|  |  |- test_scene_viewport_interaction_frame.cpp
|  |  |- test_scene_viewport_interaction_resolver.cpp
|  |  |- test_scene_viewport_move_gizmo.cpp
|  |  |- test_scene_viewport_navigation.cpp
|  |  |- test_scene_viewport_overlay_providers.cpp
|  |  |- test_scene_viewport_overlay_renderer.cpp
|  |  |- test_scene_viewport_picker.cpp
|  |  |- test_scene_viewport_rotate_gizmo.cpp
|  |  |- test_scene_viewport_scale_gizmo.cpp
|  |  |- test_scene_viewport_shader_paths.cpp
|  |  |- test_scene_viewport_transform_gizmo_coordinator.cpp
|  |  |- test_script_component_editor_utils.cpp
|  |  |- test_viewport_host_surface_utils.cpp
|  |  |- test_viewport_object_id_picker.cpp
|  |  |- test_viewport_render_flow_utils.cpp
|  |  `- test_viewport_render_targets.cpp
|  |- Fixtures/
|  |  `- Resources/
|  |- Input/
|  |- Memory/
|  |- NewEditor/                             # 当前为空的预留测试根目录
|  |- 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/
|  `- UI/
|     |- Core/
|     |- Editor/
|     |- Runtime/
|     `- TEST_SPEC.md
|- 参考/
|  |- Fermion/
|  |- TransformGizmo/
|  |- unity editor/
|  |- unity-editor-icons/
|  |- unity-icons/
|  `- UnityRuntimeSceneGizmo-master/
`- .vscode/

关键文档入口

编辑器模块说明：editor/README.md
面向引擎实现者和 coding agent 的协作基线：AGENT.md
API 文档入口：docs/api/main.md
架构蓝图：docs/blueprint.md
RHI 基线设计：docs/plan/end/RHI模块设计与实现/RHI模块总览.md
Library 启动与运行时加载主线：docs/plan/Library启动预热与运行时异步加载混合重构计划_2026-04-04.md
Editor 当前架构：docs/plan/Editor架构说明.md
当前 Shader / Material 主线：docs/plan/Renderer下一阶段_Unity风格Shader体系正式化计划_2026-04-06.md
XCUI 总体蓝图：docs/plan/XCUI完整架构设计与执行计划.md
XCUI 阶段状态：docs/plan/XCUI_Phase_Status_2026-04-05.md
测试规范：tests/TEST_SPEC.md

许可说明

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

19 KiB Raw Blame History Unescape Escape