xuanchi/XCEngine
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cd03465cd0202dc74925b6d8b473932b6c8ff721
XCEngine/AGENT.md

8.2 KiB
Raw Blame History

XCEngine Agent Guide

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

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

1. 先看什么

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

  1. AGENT.md
  2. README.md
  3. docs/plan/end/RHI模块设计与实现/RHI模块总览.md
  4. docs/plan/Renderer模块设计与实现.md
  5. 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 抽象、后端收敛、接口新增时，始终以：

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

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 配置

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 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 全量

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

6.2 RHI

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

6.3 Rendering

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

6.4 Editor / Scripting

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. 文档入口

Reference in New Issue View Git Blame Copy Permalink