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](AGENT.md)
2. [README.md](README.md)
3. [docs/plan/end/RHI模块设计与实现/RHI模块总览.md](docs/plan/end/RHI模块设计与实现/RHI模块总览.md)
4. [docs/plan/Shader与Material系统下一阶段计划.md](docs/plan/Shader与Material系统下一阶段计划.md)
5. [docs/plan/SceneViewport_Overlay_Gizmo_Rework_Plan.md](docs/plan/SceneViewport_Overlay_Gizmo_Rework_Plan.md)
6. [tests/TEST_SPEC.md](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](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 配置

```bash
cmake -S . -B build -A x64
```

如果当前任务不需要 Mono：

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

### 5.2 常用构建 target

```bash
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 全量测试入口

```bash
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 一个“当前真实工程长什么样”的基线。它本身也必须随着工程演进一起维护，不能再落回旧状态说明。