AGENTS.md

AGENTS.md

本文件约束在 WaveEngine 仓库中工作的编码代理。项目入口见 README.md，当前实现见 docs/architecture/current-engine-architecture.md。源码、CMakeLists.txt 和本次实际验证始终优先于文档。

工作规则

• 使用中文沟通。
• 每次开始先运行 git status --short，保护用户未提交修改，不覆盖、清理或回退无关内容。
• 禁止 git reset --hard、破坏性 checkout 和未经确认的批量删除。
• 除非用户明确要求，不修改 Engine/ThirdParty/ 中的 vendored 代码。
• 可在一个已验证的本地改动边界后创建 checkpoint commit；push 必须事先获得用户明确确认。
• 按风险执行当前构建和运行验证，不能用历史结果代替。

平台与构建

WaveEngine 是 Windows x64、C++20、DirectX 12 项目。主光栅路径要求 Shader Model 6.6、Mesh Shader 和 bindless；Path Tracing 另需 DXR Tier 1.1，不支持时回落光栅。

cmake -S . -B Build -G "Visual Studio 17 2022" -A x64
cmake --build Build --config Debug --target WaveEditor
& .\Build\Debug\WaveEditor.exe

• Visual Studio 产物位于 Build/<Config>/。
• GLOB_RECURSE ... CONFIGURE_DEPENDS 收集常规源码与 Shader。
• WaveRuntime、WaveEditorSupport 和 WaveEditor 警告视为错误。
• MSVC 使用 /bigobj、/Zc:preprocessor；/ZI 和增量链接只用于 Debug。
• 构建后会复制 Engine/ThirdParty/bin/ 的运行库。

生命周期与 GPU

• 入口是 Engine/Source/WaveEditor.cpp。
• 启动顺序保持为 Paths/Log → Window/Input → RHI → Shader/Scene → Renderer/UI。
• 帧循环保持 Input → 资产完成队列 → Scene Tick → Renderer → EndFrame。
• 关闭时先拒绝新资产任务并 drain worker，再等待 Direct/Compute/Copy 与 Present idle，随后销毁 GPU-backed UI、Renderer、缓存、Scene、Shader、RHI 和窗口。
• 无法证明 GPU idle 时必须走 quarantine，不能执行不安全的 GPU teardown。
• Deferred command payload、command list 与 KeepAlive() 资源必须保留到对应 fence 完成。
• Execute+Signal 是单一提交事务；Signal、fence 或 wait 失败后 queue 不得继续复用。

RenderGraph 与渲染

• Pass setup 用 Read*、Write*、ReadWrite* 声明，execute 通过匹配的 graph accessor 访问。
• 不假设插入顺序等于执行顺序；依赖由 RAW/WAR/WAW DAG 决定。
• 外部资源必须显式 Import；瞬态 handle 和 RHI resource 不得逃逸。
• 当前光栅链为 IBL → Shadow/Culling → G-Buffer → Shadow Project → Lighting → Exposure → Tonemap。
• Path Tracing 在相机、分辨率或用户重置时清空累积；修改 Skybox 必须使 IBL 烘焙失效。

坐标、Scene 与资产

• 世界坐标为左手系 +X 前、+Y 右、+Z 上，矩阵为 row_major。
• FRotator(Pitch,Yaw,Roll) 分别绕 +Y/+Z/+X；保持现有数值尺度。
• 使用 WaveMath::WorldForward/Right/Up，相机和 Path Tracing 保留完整 Forward/Right/Up basis。
• 异步导入后台只构建 CPU payload，GPU 资源只在主线程创建。
• WEMesh writer 为 v3；WEScene v4 使用 UE 坐标并以 FAssetId 为资产引用，同时保留 source hint 降级路径。
• FSharedAssetCache 共享 CPU/GPU mesh；Reimport 使用 staging、校验和原子发布，失败不得替换正式 artifact 或 live mesh。
• Scene、WEMesh 和 UI 配置保存使用同目录临时文件与原子替换。

Shader、UI 与代码风格

• Shader 使用 DECLARE_SHADER、FPermutationDomain 和 IMPLEMENT_SHADER；DXC 固定 SM 6.6，Ray Tracing 使用 lib_6_6。
• Debug Shader 使用 -Zi -Od -Qembed_debug，Release 禁止；条件编译使用 #if WAVE_DEBUG。
• Engine/Shaders/Shared/ 的 C++/HLSL 布局、对齐和类型必须同步。
• ui_config.cfg 按不可信输入处理，校验解析、finite、范围和 min/max。
• Unreal 风格命名；整数使用项目别名；Tab 宽度 4；保持邻近代码风格，不做无关格式化。
• 公共头显式包含直接依赖；使用 check / checkNoEntry；日志参数通过 operator<< 拼接。
• 新 Render Pass 同步修改 C++、HLSL、Shader 注册和 Renderer 接线。

验证

至少重新配置并构建受影响目标。渲染或生命周期修改还应正常启动和退出编辑器，并检查本次 %LOCALAPPDATA%\WaveEngine\Logs\WaveEngine.log 中新增的 Error、Fatal 和 D3D12 validation 错误。窗口能打开本身不代表 GPU 修改已完成验证。