docs: refresh repository entry guides

2026-03-29 01:55:36 +08:00
parent 6683e3c299
commit b0427b7091
2 changed files with 551 additions and 689 deletions
--- a/AGENT.md
+++ b/AGENT.md
@@ -1,187 +1,291 @@
 # XCEngine Agent Guide

-这个文件面向进入当前工作区的开发者 / Codex / Agent，目标是快速建立对当前工程状态的正确认知，避免重新踩已经处理过的 RHI 问题。
+这个文件面向进入当前仓库的开发者 / Codex / Agent。目标不是介绍项目，而是快速建立对“当前工程状态、真实约束、推荐入口与协作方式”的统一认知。

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

-当前工程已经不再处于“先把 RHI 补到能跑起来”的阶段，而是处于：
+## 1. 先看什么

- RHI 抽象层已经可用
- 可以开始继续向上做基础渲染管线
- 上层实现过程中继续反向驱动 RHI 精化
+进入仓库后，优先读这几份文档：

-当前最重要的原则不是“继续堆抽象”，而是：
+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)

- 先保证功能正确
- 保证 D3D12 / OpenGL 双后端不被破坏
- 每修一个真实问题，都补对应测试
+其中：

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

-RHI 当前重点支持：
+## 2. 当前工程状态
+
+### 2.1 引擎整体
+
+当前仓库已经不再处于“先把底层跑起来”的阶段，而是处于：
+
+- `RHI` 已具备可维护的三后端基线
+- `Rendering` 已形成正式模块，不再只是零散 sample 代码
+- `Editor` 已能通过引擎渲染链路驱动 viewport
+- `Scripting` 已具备 Mono 托管程序集构建和基础运行时测试
+
+当前主线工作不应继续封闭式堆 RHI，而应在不破坏测试基线的前提下，继续推进渲染、编辑器和脚本三者的对接。
+
+### 2.2 RHI
+
+当前正式支持的后端：

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

-近期已经完成的关键收敛：
+当前 RHI 的基本判断：

- `pipeline layout` 负责拥有并管理 descriptor set 元数据
- D3D12 / OpenGL 两个后端的 descriptor 绑定都已经 `set-aware`
- `firstSet` 路径已经被系统性修过并补测
- OpenGL shader 从内存源码创建时，不再依赖偶然的 NUL 终止
- OpenGL 单 shader 编译路径现在会正确记录 `ShaderType`
- OpenGL 的 compute/UAV 绑定已经有真实 dispatch + 回读验证
- RHI 抽象层集成测试统一采用“一场景一张 `GT.ppm`，双后端都与同一 GT 比对”
+- 抽象层已经可用
+- 后端差异路径已经被一轮轮集成测试逼出了很多真实问题并修过
+- 但它仍然不是“完全封顶”的模块

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

- 现在可以直接开始做基础渲染管线
- 但不要假设 RHI 已经“绝对最终完成”
- 后续上层实现很可能继续暴露新的真实缺口，这是正常状态
+### 2.3 Rendering

-## 3. 设计原则
+当前 `engine/include/XCEngine/Rendering/` 与 `engine/src/Rendering/` 已经落地：

-RHI 模块始终遵循：
+- `RenderSceneExtractor`
+- `RenderResourceCache`
+- `RenderSurface`
+- `CameraRenderer`
+- `SceneRenderer`
+- `BuiltinForwardPipeline`
+- `RenderMaterialUtility`

- 求同存异
- 分层抽象
- 特性降级
- 谨慎逃逸
+这意味着：

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

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

-工程实践约束：
+当前 editor 的关键事实：

- 抽象层测试只能依赖公共 RHI 接口
- 如果为了让抽象层测试通过而不得不 include 后端私有头文件，优先修 RHI 本身
- 功能不破坏永远高于“为了抽象而抽象”
+- 它仍然是 `D3D12` 宿主应用
+- Scene/Game viewport 已通过离屏纹理接入引擎 `SceneRenderer`
+- `editor/src/Viewport/ViewportHostService.h` 当前直接依赖 `RHI::D3D12Device`
+- Scene view 相机控制已经有独立控制器与单测

-## 4. 当前测试体系
+因此当前要注意：

-RHI 测试分四层：
+- 引擎渲染逻辑应继续收敛在 `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/`
-  - D3D12 后端专项测试
 - `tests/RHI/OpenGL/`
-  - OpenGL 后端专项测试
+- `tests/RHI/Vulkan/`

-当前关键测试目标：
+边界规则：

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

-测试规范总文档：
+### 3.3 RHI 抽象层集成测试

- [TEST_SPEC.md](tests/TEST_SPEC.md)
+当前抽象层场景：

-## 5. RHI 抽象层集成测试约束
-
-当前抽象层集成测试目录：
-
- `tests/RHI/integration/minimal/`
- `tests/RHI/integration/triangle/`
- `tests/RHI/integration/quad/`
- `tests/RHI/integration/sphere/`
+- `minimal`
+- `triangle`
+- `quad`
+- `sphere`
+- `backpack`

 必须遵守：

- 每个场景目录只维护一张 `GT.ppm`
- D3D12 与 OpenGL 都与同一张 `GT.ppm` 比对
- 截图文件可以按后端区分，例如：
-  - `quad_d3d12.ppm`
-  - `quad_opengl.ppm`
- 抽象层集成测试必须只用公共 RHI 接口
- 新场景如果暴露的是 RHI 根因，要先修 RHI，再修测试
+1. 每个场景目录只维护一张 `GT.ppm`
+2. `D3D12 / OpenGL / Vulkan` 都与同一张 `GT.ppm` 做比对
+3. 运行输出可以按后端区分命名，但 GT 不能拆成多份
+4. 场景测试代码只能使用公共 RHI 接口

-特别注意：
+### 3.4 Rendering 测试

- `sphere` 这类场景承担了 `firstSet != 0` 的验证职责
- 不能为了让测试过而绕开 set/binding 语义
+当前 `tests/Rendering/` 已经存在：

-## 6. 推荐构建命令
+- `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 --build build --config Debug --target rhi_unit_tests
-cmake --build build --config Debug --target rhi_integration_minimal
-cmake --build build --config Debug --target rhi_integration_triangle
-cmake --build build --config Debug --target rhi_integration_quad
-cmake --build build --config Debug --target rhi_integration_sphere
+cmake -S . -B build -A x64 -DXCENGINE_ENABLE_MONO_SCRIPTING=OFF
 ```

-查看测试：
+### 5.2 常用构建 target

 ```bash
-ctest --test-dir build -N -C Debug
+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
 ```

-## 7. 常用验证命令
-
-RHI 单测：
+### 6.2 RHI

 ```bash
-build\tests\RHI\unit\Debug\rhi_unit_tests.exe
+cmake --build build --config Debug --target rhi_abstraction_tests
+cmake --build build --config Debug --target rhi_backend_tests
 ```

-抽象层集成测试示例：
+### 6.3 Rendering

 ```bash
-build\tests\RHI\integration\quad\Debug\rhi_integration_quad.exe --gtest_filter=D3D12/QuadTest.RenderQuad/0
-build\tests\RHI\integration\quad\Debug\rhi_integration_quad.exe --gtest_filter=OpenGL/QuadTest.RenderQuad/0
+cmake --build build --config Debug --target rendering_unit_tests
+cmake --build build --config Debug --target rendering_integration_backpack_scene
 ```

+### 6.4 Editor / Scripting
+
 ```bash
-build\tests\RHI\integration\sphere\Debug\rhi_integration_sphere.exe --gtest_filter=D3D12/SphereTest.RenderSphere/0
-build\tests\RHI\integration\sphere\Debug\rhi_integration_sphere.exe --gtest_filter=OpenGL/SphereTest.RenderSphere/0
+cmake --build build --config Debug --target editor_tests
+cmake --build build --config Debug --target scripting_tests
 ```

-## 8. 后续推荐方向
+## 7. 当前最合理的工作方式

-当前最合理的后续工作是直接做基础渲染管线，而不是继续封闭式打磨 RHI。
+适用于当前仓库的协作方式：

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

-1. 最小相机常量 / 每物体常量
-2. 基础 opaque pass
-3. render target / depth target 管理
-4. 最小材质系统
-5. 新的场景级集成测试
+特别是涉及：

-工作方式：
+- `RHI`
+- `Rendering`
+- `Editor viewport`
+- `Scripting runtime`

- 上层只能依赖 RHI 抽象
- 一旦暴露 RHI 根因，及时回到底层修复
- 每个阶段完成后立刻验证并提交
+这些模块时，必须避免“表面修好了，但测试基线退化”的情况。

-## 9. 文档入口
+## 8. 文档入口

- 项目介绍与目录总览：
-  - [README.md](README.md)
- RHI 核心设计文档：
-  - [RHI模块总览](docs/plan/end/RHI模块设计与实现/RHI模块总览.md)
- 测试规范：
-  - [TEST_SPEC.md](tests/TEST_SPEC.md)
+- 项目概览与目录树：[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)