xuanchi/XCEngine

Fork 0

Files

ssdfasd 31756847ab docs: sync api and planning docs

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

16 KiB

Raw Blame History

XCEngine Agent Guide

这个文件面向在当前仓库里工作的 coding agent / 开发者。它不负责介绍项目卖点，而是给出当前 checkout 的真实工程状态、优先入口、硬约束和推荐验证方式。

如果 README、旧文档和当前文件树 / CMakeLists.txt / 测试 target 冲突，以当前 checkout 为准，并在本次工作里顺手修正文档。

1. 开工顺序

进入仓库后，优先按下面顺序建立上下文：

AGENT.md
README.md
相关模块的 CMakeLists.txt
对应模块最近的测试目录与聚合 target
对应设计文档

当前最常用的设计入口：

已归档但当前仍常用的背景文档：

如果任务落在 API 文档：

先检查 docs/plan/ 下有没有日期更晚的 API 相关计划或归档；当前活跃任务池是 docs/plan/API文档实时同步任务池_2026-04-03.md。这份任务池目前已经推进到第三轮 T01-T20 全部完成，结构审计保持全绿，但开始新一轮前仍要先确认是否又追加了新任务块。
再看 docs/api-skill.md。
再看 docs/api/_meta/rebuild-status.md。
一次只认领一个任务块，先改状态为 DOING，只写自己任务块允许的范围。

2. 当前工程事实

顶层 CMakeLists.txt 当前纳入 engine/、editor/、new_editor/、managed/、mvs/RenderDoc/ 和 tests/。
engine/ 构建静态库 XCEngine；editor/ 构建 XCEditor，但输出文件名仍是 editor/bin/<Config>/XCEngine.exe。
new_editor/ 当前构建 XCUIEditorLib、XCUIEditorHost；启用 XCENGINE_BUILD_XCUI_EDITOR_APP 时会输出 new_editor/bin/<Config>/XCUIEditor.exe。
editor 默认把仓库内的 project/ 识别为工程根目录，也支持 --project <path> 覆盖。
当前工程真实使用 Assets/ + .meta + Library/ 的项目布局；project/Library/ 是当前 workflow 的一部分，不是可随手忽略的垃圾目录。
Mono 运行时与 editor 的脚本类发现都从 <project>/Library/ScriptAssemblies/ 加载程序集。
当前根目录里没有 native 占位项；更新目录树或迁移旧文档时，不要继续传播这条过期事实。
当前工作机是 Windows 文件系统；文档里统一写 tests/Editor/、tests/Core/、tests/Scripting/ 等真实目录名，不要制造大小写噪音。
engine/CMakeLists.txt 当前对 Vulkan 是硬依赖；editor/ 和 tests/ 首次配置会拉取 ImGui 与 googletest。

3. 子系统现状

3.1 Core / Asset / Resources

Core/Asset/AssetDatabase、AssetImportService、ProjectAssetIndex、ResourceManager 已形成正式导入与运行时加载链路。
当前真实职责包括：
- 扫描 Assets/
- 为资源生成 .meta
- 维护 Library/SourceAssetDB/assets.db
- 维护 Library/ArtifactDB/artifacts.db
- 写入 Library/Artifacts/
最新活跃设计文档已经把下一阶段目标收口到“启动阶段前置恢复索引 / 缓存状态，运行时按需异步加载 payload”。
BootstrapProject() / BootstrapProjectAssets() 已正式接入启动链路；接下来重点是指标固化、UI 状态拆分和剩余同步兜底点审计。
当前还不要把 AssetImportService、ProjectAssetIndex、ResourceManager 的职责重新揉回一团；先看 docs/plan/Library启动预热与运行时异步加载混合重构计划_2026-04-04.md。
材质 artifact 当前是 schema v2：
- kMaterialArtifactSchemaVersion = 2
- magic XCMAT02
- texture binding 序列化三元组是 binding name + encoded AssetRef + optional path
Material 当前同时维护 loaded handle、稳定 AssetRef 与 path 元数据；GetTexture() 首次访问时可触发懒加载，GetTextureBindingLoadedTexture() 不触发加载。

3.2 Rendering

当前正式主链是 SceneRenderer -> CameraRenderer -> RenderPipeline。
现有正式能力包括：
- forward 主几何渲染
- ObjectId 渲染与 editor picking
- BuiltinInfiniteGridPass
- BuiltinObjectIdOutlinePass
- CameraRenderRequest::postScenePasses
- CameraRenderRequest::overlayPasses
当前主线不是 render graph，而是 shader / material contract、builtin pass contract 和 renderer-owned feature contract。

3.3 Editor

editor 仍然是 D3D12 宿主应用。
Scene/Game viewport 已通过引擎 Rendering + RHI 输出离屏纹理，再由 editor 宿主接入 ImGui。
当前 Scene View 主链已经显式拆成：
- SceneViewportChrome
- SceneViewportInteractionFrame
- SceneViewportNavigation
- SceneViewportTransformGizmoCoordinator
- ViewportHostService
editor/src/Viewport/ 当前稳定存在的关键入口包括：
- SceneViewportCameraController
- SceneViewportChrome
- SceneViewportEditorModes
- SceneViewportHudOverlay
- SceneViewportInteractionActions
- SceneViewportInteractionFrame
- SceneViewportInteractionResolver
- SceneViewportMoveGizmo
- SceneViewportNavigation
- SceneViewportOverlayBuilder
- SceneViewportOverlayFrameCache
- SceneViewportOverlayProviders
- SceneViewportOverlaySpriteResources
- SceneViewportPassSpecs
- SceneViewportPicker
- SceneViewportResourcePaths
- SceneViewportRotateGizmo
- SceneViewportScaleGizmo
- SceneViewportShaderPaths
- SceneViewportTransformGizmoCoordinator
- SceneViewportTransformGizmoFrameBuilder
- ViewportHostRenderFlowUtils
- ViewportHostRenderTargets
- ViewportHostSurfaceUtils
- ViewportObjectIdPicker
SceneViewportShaderPaths.h 当前主要是兼容 include；路径真实 owner 已转到 SceneViewportResourcePaths.h。
tests/Editor/ 已有 test_scene_viewport_chrome.cpp、test_scene_viewport_interaction_frame.cpp、test_scene_viewport_navigation.cpp 与 test_scene_viewport_transform_gizmo_coordinator.cpp，不要再按“这些 helper 还没落地”理解当前 editor。

3.4 XCUI / New Editor

new_editor/ 是当前 XCUI editor sandbox 主线；旧 editor/ 的整体替换仍处于延后状态，不要把 XCUI 计划误读成“已经整体替换现有 editor”。
当前宿主分层是：
- XCUIEditorLib
- XCUIEditorHost
- XCUIEditorApp（可选应用壳）
共享 UI core、runtime screen host 与 widget 基础能力主要沉淀在 engine/include/XCEngine/UI/ 与 engine/src/UI/；new_editor/ 负责 XCUI editor 壳、宿主与 widget sandbox。
XCUI / new_editor 的测试规范以 tests/UI/TEST_SPEC.md 为准；根目录虽然有 tests/NewEditor/，但当前具体测试实现主要放在 tests/UI/ 下。

3.5 Scripting

当前脚本链路由三部分组成：
- managed/XCEngine.ScriptCore/
- managed/GameScripts/
- project/Assets/**/*.cs
构建结果分两类：
- xcengine_managed_assemblies 生成引擎示例程序集
- xcengine_project_managed_assemblies 生成项目脚本程序集，并复制到 project/Library/ScriptAssemblies/
project/Library/ScriptAssemblies/ 里的当前快照可能落后于目标态；判断“成功构建后应有哪些程序集”时，以 managed/CMakeLists.txt、editor/src/Scripting/EditorScriptAssemblyBuilder.cpp 与对应测试为准，而不是只看工作树里此刻存着什么。
ScriptEngine 当前已具备脚本类发现、字段元数据读取、默认值读取、stored override 管理和运行时 managed field 同步。
Inspector 侧已经存在 ScriptComponentEditor；脚本相关改动通常同时影响 engine/src/Scripting/、managed/、project/Assets/Scripts/、editor/src/ComponentEditors/ 与 tests/Scripting/ / tests/Editor/。

3.6 Tests

当前测试主目录包括：

tests/Components/
tests/Core/
tests/Debug/
tests/Editor/
tests/Fixtures/
tests/Input/
tests/Memory/
tests/NewEditor/
tests/Rendering/
tests/Resources/
tests/RHI/
tests/Scene/
tests/Scripting/
tests/Threading/
tests/UI/

需要特别记住的聚合 target：

rhi_all_tests
rendering_all_tests
rendering_phase_regression
editor_tests
core_ui_tests
editor_ui_tests
runtime_ui_tests
scripting_tests

4. 不可忽视的硬约束

4.1 文档服从真实 checkout

如果文档与当前目录结构、target 名称、代码事实冲突：

先信当前 checkout
再更新文档

不要沿用“计划中但未落地”的旧说法。

4.2 不要随手清空 `project/Library/` 或删 `.meta`

project/Library/ 虽然可重建，但它在当前 workflow 里承载：

SourceAssetDB
ArtifactDB
Artifacts
ScriptAssemblies

涉及资源导入、artifact、脚本程序集发现时，不要把删库重建当作默认修复手段。

4.3 RHI 抽象层与后端层必须分层

tests/RHI/unit/ 与 tests/RHI/integration/ 只能依赖公共 RHI 抽象。

不要为了让抽象层测试通过而：

include 后端私有头
直接使用原生句柄
给单一后端写抽象层特判

如果必须这么做，优先修 RHI，而不是污染测试边界。

4.4 Editor 是宿主，不是第二套渲染器

如果 viewport、outline、picking 或 gizmo 有问题，优先判断：

是 Rendering 模块问题
是 RenderSurface / RHI 输出问题
还是 editor 宿主接线问题

不要因为 editor 当前是 D3D12 host，就把问题草率塞回 editor 私有渲染逻辑。

4.5 不要再把新逻辑堆回旧的 ImGui world overlay

新的世界空间 overlay / gizmo 逻辑如果仍然直接堆在：

SceneViewPanel.cpp
panel 层临时拼的 immediate draw / ad-hoc overlay 路径

通常就是逆着当前架构方向在走。优先入口是：

CameraRenderRequest::overlayPasses
SceneViewportOverlayBuilder
SceneViewportEditorOverlayPass
SceneViewportTransformGizmoCoordinator

4.6 `backpack` 导入行为必须统一

这是仓库里已经踩过的真实坑。backpack 相关资源在以下路径中的导入行为必须保持一致：

editor
runtime
rendering tests
rhi abstraction tests

不要只在局部路径里额外加 MeshImportFlags::FlipUVs 之类的补丁。

4.7 `mvs/` 不是长期主线模块

mvs/ 里有样例、研究和工具，但当前正式引擎逻辑的长期落点应优先是：

engine/
editor/
managed/
tests/

不要把正式渲染逻辑重新堆回 sample 子树长期存活。

4.8 API 文档任务必须看最新计划并复跑审计

只要任务涉及 docs/api/：

先检查 docs/plan/ 下有没有更新日期更晚的 API 计划或归档。
以最新任务池和 docs/api-skill.md 为执行规范。
改完必须重新执行：

python -B docs/api/_tools/audit_api_docs.py

如果审计没回绿，不算完成。

5. 推荐构建与验证入口

5.1 配置

cmake -S . -B build -A x64

如果当前任务不需要 Mono：

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

5.2 常用构建 target

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

5.3 按改动类型选择验证

改 engine/RHI：先跑 rhi_abstraction_tests 或 rhi_backend_tests，再决定是否扩展到 rhi_all_tests
改 engine/Rendering：先跑 rendering_unit_tests 和最相关的 rendering_integration_*，必要时再跑 rendering_phase_regression
改 editor/Viewport、editor/UI 或 Inspector：先跑 editor_tests
改 engine/Scripting、managed/、project/Assets/Scripts/：先构建 xcengine_project_managed_assemblies，再跑 scripting_tests
改资源导入、.meta、artifact 相关逻辑：优先跑 tests/Resources/ 里的对应 target

5.4 全量测试入口

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

6. 按任务找入口

RHI 抽象与后端：engine/include/XCEngine/RHI/、engine/src/RHI/、tests/RHI/
Rendering 主链与 pass：engine/include/XCEngine/Rendering/、engine/src/Rendering/、tests/Rendering/
资源导入与工程布局：engine/include/XCEngine/Core/Asset/、engine/src/Core/Asset/、editor/src/Managers/ProjectManager.cpp、project/Assets/、project/Library/
Material / shader / artifact：engine/include/XCEngine/Resources/Material/、engine/src/Resources/Material/、engine/include/XCEngine/Core/Asset/ArtifactFormats.h、tests/Resources/Material/
Editor viewport / gizmo / picking：editor/src/Viewport/、editor/src/panels/SceneViewPanel.cpp、tests/Editor/
Editor actions / project routing：editor/src/Actions/、editor/src/Commands/、editor/src/Core/、editor/src/Managers/、tests/Editor/test_action_routing.cpp
脚本运行时与程序集：engine/include/XCEngine/Scripting/、engine/src/Scripting/、managed/、project/Assets/Scripts/、tests/Scripting/
API 文档：docs/api/XCEngine/、docs/api/_guides/、docs/api/_tools/audit_api_docs.py、docs/plan/API文档实时同步任务池_2026-04-03.md

7. 适合当前仓库的工作方式

先读当前模块的 CMakeLists.txt、最近测试和设计文档，再动代码。
优先在既有模块边界里解决问题，不要绕开系统回到 sample 式实现。
先跑与改动最相关的最小验证，再决定是否扩大全量验证。
目录、target、入口、文档名改了，就同步更新 README / AGENT / 相关说明。
如果任务会有意重建 project/Library/、脚本程序集或 .meta，在结果里明确说明哪些文件是有意生成的。

这份文档的作用，是给 agent 一条“当前真实工程长什么样”的基线。它本身也必须随着工程演进一起维护，不能再落回旧状态说明。

16 KiB Raw Blame History Unescape Escape