# 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 shadow 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, unless
  local-shadow fallback is required.
- Effective Solari forces an HDR camera target regardless of authored HDR settings, because Bevy
  Solari requires `STORAGE_BINDING` on the camera main texture and wgpu rejects storage usage on
  sRGB target formats.
- 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 when local point/spot shadow
  correctness or unavailable RT features require it.
- 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.
- 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.