# ADR 0016: Unified rendering contract

## Status

Accepted

## Context

Rendering state crossed settings, hydration, game runtime, Solari readiness, editor viewport
ownership, and diagnostics. The project already had `ActiveCameraRenderProfile` for project and
volume intent, but GI fallback decisions were repeated across camera sync, Solari systems, and UI.

Bevy 0.18 Solari is still experimental. It needs raytracing-capable hardware, eligible
`Mesh3d + MeshMaterial3d<StandardMaterial>` scene geometry, Solari-compatible mesh assets
(TriangleList, POSITION/NORMAL/UV_0/TANGENT, U32 indices), a render-scene bind group, and a
compatible directional or emissive light source. It also does not replace Forward PBR local
point/spot lighting.

## Decision

- `settings` owns the neutral render-stack contract:
  `ActiveCameraRenderProfile` is requested intent, and `EffectiveRenderStack` records requested GI,
  effective GI, Solari readiness, local shadow-light state, and fallback reason.
- `game_hot` owns runtime application of the stack. Camera systems call the shared resolver and
  mirror the result into `RenderingCapabilities` for renderer method selection and diagnostics.
- Requested Solari and effective Solari are distinct. Requested Solari keeps eligible project
  geometry tagged for raytracing and attaches Bevy Solari as soon as RT support is available.
- Point/spot `LightDesc` components are runtime-disabled while Solari is active. They stay authored
  and editable enough to switch kind, but hydration strips/skips their Bevy `PointLight`/`SpotLight`
  components and the inspector explains the limitation on the component.
- Effective Solari and atmosphere force an HDR camera target regardless of authored HDR settings.
  Bevy Solari requires `STORAGE_BINDING` on the camera main texture, and Bevy sky/atmosphere
  pipelines must not be carried onto an SDR swapchain render pass.
- Runtime changes that alter the active render target or effective Solari/Forward path rebuild the
  active camera stack instead of incrementally patching it. This
  prevents stale pipelines from surviving texture-format transitions.
- Hybrid Auto remains the default policy: use Solari for directional/emissive scenes, surface
  readiness diagnostics while it warms up, and fall back to Forward PBR only when RT features are
  unavailable.
- Material authoring includes emissive color, intensity, and texture fields so scenes can create
  Solari-compatible emissive contributors without Rust changes.

## Consequences

- Diagnostics must report requested GI, effective GI, and fallback reason from
  `EffectiveRenderStack` rather than deriving labels independently.
- Project settings can disable user-authored HDR, but the active camera still receives `Hdr` when
  atmosphere or effective Solari requires an HDR target.
- Solari mesh eligibility is based on hydrated project geometry under `LevelObject` ancestry with
  `RaytracingExcluded` helpers filtered out. Built-in primitive hydration generates tangents for
  Solari compatibility; imported/custom meshes remain visible in diagnostics when they lack
  required Solari mesh attributes or U32 indices.
- Existing scenes and material assets remain compatible through serde defaults for new emissive
  fields.
- Bevy 0.19+ rendering upgrades remain a separate migration track under ADR 0002, not part of this
  contract change.