diff --git a/engine/include/XCEngine/Rendering/AGENTS.md b/engine/include/XCEngine/Rendering/AGENTS.md index 89b806e0..1e8ebf45 100644 --- a/engine/include/XCEngine/Rendering/AGENTS.md +++ b/engine/include/XCEngine/Rendering/AGENTS.md @@ -31,6 +31,67 @@ when those concepts fit the engine. in `engine/include/XCEngine/RHI/**`, `engine/src/RHI/**`, or editor host rendering, not in SRP/URP policy. +## Key Facts + +These facts are the current architecture baseline. Do not weaken them without a +deliberate architecture cut and tests. + +- The SRP/URP architecture is phase-closed enough to extend. The public object + model, managed asset selection, URP renderer data/features/passes, native + frame planning, stage recording, and RenderGraph execution now form a single + path. +- This is not full Unity URP compatibility yet. The public shape is intentionally + Unity-like, but the execution feature set is still smaller than Unity URP. +- `UniversalRenderPipelineAsset` can be selected as the active managed SRP + asset, so users can route rendering through the URP package. Treat that as + supported but still transitional. +- The current URP package is not yet a complete replacement for the built-in + renderer in the strong sense. URP owns selection, planning, renderer feature + organization, pass ordering, and stage recording; native code still supplies + scene extraction, renderer-list realization, RenderGraph execution, RHI + resources, and the default scene draw backend. +- Native execution is not the problem by itself. Unity also executes through a + native engine. The risk is native code retaining built-in forward pipeline + policy instead of acting as a backend executor for URP-declared work. +- The desired ownership model is: URP decides what to render, when to render it, + which renderer lists/passes/features are active, and which stages exist; + native executes those declarations without smuggling in built-in pipeline + policy. +- Hidden fallback is dangerous. If a managed URP stage declares support but + cannot record, the failure should be visible. Do not silently draw the same + stage through the default built-in path and call it URP. +- The test suite has useful coverage, but it is not complete enough to call the + SRP/URP stack fully locked. Add high-value contract tests as architecture + boundaries close; do not pause the architecture work for a broad test-system + rewrite yet. + +## Near-Term Goals + +Current priority is to finish the SRP/URP architecture cut, with targeted tests +on each boundary. The immediate product goal is to make URP the render decision +layer and make native rendering the execution layer. + +- Demote `BuiltinForwardPipeline` from policy center toward default native scene + draw backend. It can remain a backend/fallback implementation, but it should + not decide URP pass order, feature participation, or stage policy. +- Make `ScriptableRenderer` and its active pass queue the authority for URP + main-scene scheduling. Opaque, skybox, transparent, depth, shadow, post, and + final-output flow should come from URP blocks and passes. +- Keep `DrawObjectsPass` and `DrawSkyboxPass` as managed URP pass declarations + that execute through renderer-list/native scene-recorder backends. +- Tighten stage support rules. If a fullscreen or main-scene stage requires + managed graph recording, require the selected renderer/pipeline to support and + record that stage. +- Grow managed RenderGraph only behind Unity-shaped APIs: resource declarations, + frame data, renderer-list drawing, pass data, and command recording. Avoid + exposing native private graph or scene-recorder details. +- Add contract tests while cutting architecture: URP selection, renderer data + selection, renderer override, pass event ordering, renderer feature + invalidation, stage planning, RenderGraph recording, and no hidden built-in + fallback. +- Defer broad test-suite reorganization until these SRP/URP ownership boundaries + are stable. Reorganizing too early risks preserving transitional behavior. + ## Pipeline Selection - `GraphicsSettings.renderPipelineAsset == null` means the renderer uses the