XCEngine/AGENT.md

XCEngine Agent Guide

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

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

1. 先建立的事实

• 顶层 CMakeLists.txt 当前纳入 engine/、editor/、managed/、mvs/RenderDoc/ 和 tests/。
• engine/ 构建静态库 XCEngine；editor/ 构建 XCEditor，但输出文件名仍是 editor/bin/<Config>/XCEngine.exe。
• editor 默认把仓库内的 project/ 识别为工程根目录，也支持 --project <path> 覆盖。
• 当前工程不再只是 Assets/ 目录：已经真实使用 Assets/ + .meta + Library/ 的工程布局。
• Mono 运行时与 editor 脚本类发现都从 <project>/Library/ScriptAssemblies/ 加载程序集。
• engine/CMakeLists.txt 当前对 Vulkan 是硬依赖；editor/ 和 tests/ 首次配置会拉取 ImGui 和 googletest。

2. 优先阅读顺序

进入仓库后，优先看这些文档和入口文件：

1. AGENT.md
2. README.md
3. docs/plan/end/RHI模块设计与实现/RHI模块总览.md
4. docs/plan/Shader与Material系统下一阶段计划.md
5. docs/plan/SceneViewport_Overlay_Gizmo_Rework_Plan.md
6. tests/TEST_SPEC.md

额外规则：

• 如果任务落在某个模块里，先读该模块的 CMakeLists.txt 和最近的测试目录。
• tests/TEST_SPEC.md 仍然适合作为 GT 图规则和 RHI 边界说明，但 target 名称与目录变化时，始终以当前 tests/CMakeLists.txt 和子模块 CMakeLists.txt 为准。

3. 当前工程状态

3.1 Engine 与工程布局

当前仓库已经不在“先把底层 sample 跑起来”的阶段，而是已经形成：

• RHI
• Rendering
• Editor viewport
• AssetDatabase / Library
• Mono scripting

这几条主线之间的真实对接。

Core/Asset/AssetDatabase 现在是当前工程的重要基线，不是预研代码。它已经负责：

• 扫描 Assets/
• 为资源生成 .meta
• 维护 Library/SourceAssetDB/assets.db
• 维护 Library/ArtifactDB/artifacts.db
• 维护哈希化 Library/Artifacts/

因此：

• project/Library/ 虽然可重建，但在当前 workflow 里不是可以随手忽略的“垃圾目录”。
• 涉及资源导入、meta、artifact、脚本程序集发现时，不要擅自删除 project/Library/ 或 .meta 文件来“清环境”。

3.2 Rendering

当前 engine/include/XCEngine/Rendering/ 与 engine/src/Rendering/ 已经形成正式主链：

• SceneRenderer
• CameraRenderer
• RenderPipeline
• RenderSceneExtractor
• RenderResourceCache
• SceneRenderRequestPlanner
• RenderSurface

当前已经落地并应被视为正式能力的内容包括：

• 内建 forward 主几何渲染
• ObjectId 渲染与 editor picking
• BuiltinInfiniteGridPass
• BuiltinObjectIdOutlinePass
• CameraRenderRequest::overlayPasses

当前 Renderer 的下一阶段主线不是 render graph，而是：

• shader asset contract
• material GPU binding
• builtin pass contract
• renderer-owned feature contract

对应设计文档是 docs/plan/Shader与Material系统下一阶段计划.md。

3.3 Editor

当前 editor 的事实：

• 它仍然是 D3D12 宿主应用。
• Scene/Game viewport 已经通过引擎 Rendering + RHI 输出离屏纹理。
• ViewportHostService 是 editor 与 renderer 的关键接线层。
• object-id picking、selection outline、scene icon / gizmo overlay 已经进入正规化收口阶段。

当前 editor/src/Viewport/ 已经存在：

• SceneViewportOverlayBuilder
• SceneViewportEditorOverlayPass
• SceneViewportPicker
• SceneViewportMoveGizmo
• SceneViewportRotateGizmo
• SceneViewportScaleGizmo

这意味着：

• editor 是宿主，不是第二套 renderer。
• 新的世界空间 overlay，不应继续堆回 SceneViewPanel.cpp 的 ImGui world overlay 路径。
• 优先沿 overlayPasses -> overlay builder -> canonical frame data -> overlay pass 方向扩展。

3.4 Scripting

当前脚本链路由三部分组成：

• managed/XCEngine.ScriptCore/
• managed/GameScripts/
• project/Assets/**/*.cs

构建结果分两类：

• xcengine_managed_assemblies 生成引擎示例程序集
• xcengine_project_managed_assemblies 生成项目脚本程序集，并复制到 project/Library/ScriptAssemblies/

ScriptEngine 当前已经具备：

• 脚本类发现
• 字段元数据读取
• 默认值读取
• stored override 管理
• 运行时 managed field 同步

Inspector 侧已经存在 ScriptComponentEditor，因此脚本相关改动通常同时影响：

• engine/src/Scripting/
• managed/
• project/Assets/Scripts/
• editor/src/ComponentEditors/
• tests/Scripting/
• tests/Editor/test_script_component_editor_utils.cpp

3.5 Tests

当前测试主目录包括：

• tests/Components/
• tests/Core/
• tests/Debug/
• tests/Editor/
• tests/Input/
• tests/Memory/
• tests/Rendering/
• tests/Resources/
• tests/RHI/
• tests/Scene/
• tests/Scripting/
• tests/Threading/

需要特别记住的聚合 target：

• rhi_all_tests
• rendering_all_tests
• rendering_phase_regression
• editor_tests
• scripting_tests

4. 不可忽视的硬约束

4.1 文档服从真实 checkout

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

• 先信当前 checkout
• 再更新文档

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

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

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

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

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

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

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

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

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

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

4.4 不要再扩写 ImGui world overlay

当前 viewport overlay / gizmo 已有明确收口方向。新功能若仍然继续堆在：

• SceneViewPanel.cpp
• SceneViewportOverlayRenderer.cpp 的 ImGui world draw 路径

通常就是逆着当前架构方向在走。

优先入口是：

• CameraRenderRequest::overlayPasses
• SceneViewportOverlayBuilder
• SceneViewportEditorOverlayPass

4.5 backpack 导入行为必须统一

这是仓库里已经踩过的真实坑。

backpack 相关资源在以下路径中的导入行为必须保持一致：

• editor
• runtime
• rendering tests
• rhi abstraction tests

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

4.6 mvs/ 不是长期主线模块

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

• engine/
• editor/
• managed/
• tests/

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

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 或 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/
• Editor viewport / gizmo / picking：editor/src/Viewport/、editor/src/panels/SceneViewPanel.cpp、tests/Editor/
• 资源导入与工程布局：engine/include/XCEngine/Core/Asset/、engine/src/Core/Asset/、editor/src/Managers/ProjectManager.cpp、project/Assets/、project/Library/
• 脚本运行时与程序集：engine/include/XCEngine/Scripting/、engine/src/Scripting/、managed/、project/Assets/Scripts/、tests/Scripting/
• 默认工程与项目描述：project/Project.xcproject、editor/src/Core/ProjectRootResolver.h、editor/src/Utils/ProjectFileUtils.h

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

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

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