Falling-Metal-Interactive/Blacksite
2
0
Fork 0
Code Issues 28 Pull Requests Actions Packages Projects Releases Wiki Activity
19c4d017dc
Blacksite/docs/adr/0016-unified-rendering-contract.md
Rbanh f29712d158
Some checks are pending
CI / Format, lint, test, build (push) Waiting to run
Details
Initial project import
2026-06-05 21:44:45 -04:00

2.7 KiB
Raw Blame History

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.