# XCEngine Agent Guide

这个文件面向进入当前仓库的开发者 / Codex / Agent。目标不是介绍项目，而是快速建立对“当前工程状态、真实约束、推荐入口与协作方式”的统一认知。

项目介绍与目录总览看 [README.md](README.md)；设计原则与当前测试规则以本文为准。

## 1. 先看什么

进入仓库后，优先读这几份文档：

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/Renderer模块设计与实现.md](docs/plan/Renderer模块设计与实现.md)
5. [tests/TEST_SPEC.md](tests/TEST_SPEC.md)

其中：

- `RHI模块总览.md` 是 RHI 设计原则基线
- `Renderer模块设计与实现.md` 是当前渲染层演进方向
- `TEST_SPEC.md` 是测试组织、GT 图规则和 CMake/CTest 入口基线

## 2. 当前工程状态

### 2.1 引擎整体

当前仓库已经不再处于“先把底层跑起来”的阶段，而是处于：

- `RHI` 已具备可维护的三后端基线
- `Rendering` 已形成正式模块，不再只是零散 sample 代码
- `Editor` 已能通过引擎渲染链路驱动 viewport
- `Scripting` 已具备 Mono 托管程序集构建和基础运行时测试

当前主线工作不应继续封闭式堆 RHI，而应在不破坏测试基线的前提下，继续推进渲染、编辑器和脚本三者的对接。

### 2.2 RHI

当前正式支持的后端：

- `D3D12`
- `OpenGL`
- `Vulkan`

当前 RHI 的基本判断：

- 抽象层已经可用
- 后端差异路径已经被一轮轮集成测试逼出了很多真实问题并修过
- 但它仍然不是“完全封顶”的模块

看到上层新问题时，不要本能地用“测试特判 / 测试绕过 / include 私有头”来糊过去；优先判断是不是 RHI 根因。

### 2.3 Rendering

当前 `engine/include/XCEngine/Rendering/` 与 `engine/src/Rendering/` 已经落地：

- `RenderSceneExtractor`
- `RenderResourceCache`
- `RenderSurface`
- `CameraRenderer`
- `SceneRenderer`
- `BuiltinForwardPipeline`
- `RenderMaterialUtility`

这意味着：

- 当前已经存在正式的场景渲染运行时
- 不要再把真实渲染逻辑塞回 `mvs/` 样例里长期存活
- 新渲染功能优先落在 `Rendering` 模块与配套测试中

### 2.4 Editor

当前 editor 的关键事实：

- 它仍然是 `D3D12` 宿主应用
- Scene/Game viewport 已通过离屏纹理接入引擎 `SceneRenderer`
- `editor/src/Viewport/ViewportHostService.h` 当前直接依赖 `RHI::D3D12Device`
- Scene view 相机控制已经有独立控制器与单测

因此当前要注意：

- 引擎渲染逻辑应继续收敛在 `engine/Rendering`
- editor 只是宿主，不应复制一套独立 renderer
- editor 侧若要继续做 viewport 能力，应尽量围绕 `RenderSurface` 和引擎场景渲染入口扩展

### 2.5 Scripting

当前脚本链路：

- `managed/XCEngine.ScriptCore/`：托管 API
- `managed/GameScripts/`：托管测试 / 示例脚本
- `engine/include/XCEngine/Scripting/` 与 `engine/src/Scripting/`：原生运行时桥接

当前脚本构建依赖：

- .NET SDK
- `参考/Fermion/Fermion/external/mono` 下的 Mono 依赖

如果环境不完整，可以通过 `-DXCENGINE_ENABLE_MONO_SCRIPTING=OFF` 暂时关闭。

## 3. 当前测试基线

### 3.1 测试树

当前主要测试模块：

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

### 3.2 RHI 测试分层

`tests/RHI/` 当前分为五块：

- `tests/RHI/unit/`
- `tests/RHI/integration/`
- `tests/RHI/D3D12/`
- `tests/RHI/OpenGL/`
- `tests/RHI/Vulkan/`

边界规则：

- `tests/RHI/unit/` 和 `tests/RHI/integration/` 只能依赖公共 RHI 抽象
- 后端私有 API / 原生句柄 / 后端特有断言，只能进对应后端目录
- 如果抽象层测试必须 include 后端头才能过，优先修 RHI

### 3.3 RHI 抽象层集成测试

当前抽象层场景：

- `minimal`
- `triangle`
- `quad`
- `sphere`
- `backpack`

必须遵守：

1. 每个场景目录只维护一张 `GT.ppm`
2. `D3D12 / OpenGL / Vulkan` 都与同一张 `GT.ppm` 做比对
3. 运行输出可以按后端区分命名，但 GT 不能拆成多份
4. 场景测试代码只能使用公共 RHI 接口

### 3.4 Rendering 测试

当前 `tests/Rendering/` 已经存在：

- `unit/`
- `integration/backpack_scene`
- `integration/textured_quad_scene`
- `integration/transparent_material_scene`
- `integration/cull_material_scene`
- `integration/depth_sort_scene`
- `integration/material_state_scene`
- `integration/offscreen_scene`

结论：

- 新渲染功能不需要再从零搭测试体系
- 直接往现有 `tests/Rendering` 扩展即可

## 4. 已知关键约束

### 4.1 始终遵循 RHI 设计文档

涉及 RHI 抽象、后端收敛、接口新增时，始终以：

- [docs/plan/end/RHI模块设计与实现/RHI模块总览.md](docs/plan/end/RHI模块设计与实现/RHI模块总览.md)

作为原则基线，而不是局部方便优先。

### 4.2 功能正确优先于抽象表面整洁

允许为了功能正确做必要重构，但不允许：

- 测试特判掩盖真实后端缺陷
- 为了不改底层而污染抽象层测试
- 为了“少动代码”保留明显错误的对象边界

### 4.3 backpack 资源导入行为必须统一

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

规则：

- editor / runtime / rendering tests / rhi abstraction tests 的 backpack 导入行为必须保持一致
- 不要只在某个测试路径里额外加 `MeshImportFlags::FlipUVs`
- 否则很容易出现 editor 显示正确、测试里 UV 错乱的假分叉

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

如果 editor viewport 有问题，优先判断：

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

不要把问题简单归因为“editor 特殊”，然后在 editor 里复制一份独立渲染逻辑。

## 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 XCVolumeRendererUI2
cmake --build build --config Debug --target xcengine_managed_assemblies
cmake --build build --config Debug --target rhi_all_tests
cmake --build build --config Debug --target rendering_unit_tests
cmake --build build --config Debug --target editor_tests
cmake --build build --config Debug --target scripting_tests
```

补充：

- 编辑器 target 名称是 `XCVolumeRendererUI2`
- 输出文件名是 `editor/bin/<Config>/XCEngine.exe`

## 6. 推荐验证入口

### 6.1 全量

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

### 6.2 RHI

```bash
cmake --build build --config Debug --target rhi_abstraction_tests
cmake --build build --config Debug --target rhi_backend_tests
```

### 6.3 Rendering

```bash
cmake --build build --config Debug --target rendering_unit_tests
cmake --build build --config Debug --target rendering_integration_backpack_scene
```

### 6.4 Editor / Scripting

```bash
cmake --build build --config Debug --target editor_tests
cmake --build build --config Debug --target scripting_tests
```

## 7. 当前最合理的工作方式

适用于当前仓库的协作方式：

1. 先在现有模块边界里定位问题，不要绕开体系补 sample 代码
2. 改动后立即补或更新测试
3. 先跑和改动最相关的测试，再决定是否扩大全量验证
4. 每个阶段完成后尽快提交，保持工作区清晰

特别是涉及：

- `RHI`
- `Rendering`
- `Editor viewport`
- `Scripting runtime`

这些模块时，必须避免“表面修好了，但测试基线退化”的情况。

## 8. 文档入口

- 项目概览与目录树：[README.md](README.md)
- RHI 设计基线：[docs/plan/end/RHI模块设计与实现/RHI模块总览.md](docs/plan/end/RHI模块设计与实现/RHI模块总览.md)
- Renderer 设计文档：[docs/plan/Renderer模块设计与实现.md](docs/plan/Renderer模块设计与实现.md)
- 测试规范：[tests/TEST_SPEC.md](tests/TEST_SPEC.md)