292 lines
8.2 KiB
Markdown
292 lines
8.2 KiB
Markdown
# 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)
|