Rendering workflow (GI + post-process volumes)

Step-by-step guide for game teams managing look development without Rust changes.

Mental model

Project defaults — assets/project.ron → rendering section (GI mode, lighting, post FX).
Post-process volumes — scene actors with local overrides (rooms, biomes, boss arenas).
Requested profile — the active viewport camera always uses ActiveCameraRenderProfile (project + blended volumes), whether it is the editor fly camera or the possessed player camera.
Effective stack — EffectiveRenderStack records requested GI, effective GI, and fallback reason for renderer sync and diagnostics.

See ADR 0013 for tier policy and crate boundaries, and ADR 0016 for the requested/effective stack contract.

Project defaults

Edit → Project Settings
Expand Global Illumination, Lighting, and Post Process sections.
Click Apply (updates runtime; Save to disk writes assets/project.ron).

Section	Key controls
GI	`GiMode`: Auto / Forward / Solari; status line shows RT fallback
Lighting	Ambient, sun lux, shadow cascades
Post Process	HDR, exposure mode (Manual EV100 / Auto), auto exposure speeds, bloom, TAA, SSAO, atmosphere, fog

Post-process volumes

Create

Scene → Create → Post Process Volume
Asset Browser → Built-ins → Post Process Volume (drag into the viewport)
Command palette: rendering.create_volume

Inspector (inherit / override)

Each FX field uses Override checkbox:

Unchecked — inherits project value (shown greyed as Inherited: …).
Checked — local value; Reset to project per field.

Volume fields: label (HUD), priority, blend distance, half extents (local-space AABB).

Rendering panel

Window → Rendering tabs:

Tab	Purpose
Active Camera	Resolved GI path, exposure, fog, FX flags, contributing volumes
Project	Read-only `project.ron` summary + link to Project Settings
Volumes	All volumes in level (priority sort, select/focus)

Viewport overlays: GI badge (Forward / Solari), volume HUD when inside a volume.

GI modes

Mode	Behavior
Auto	Startup default: Solari when RT GPU support is available; Forward otherwise
Forward	Bevy Forward PBR with HDR/TAA/SSAO/atmosphere/shadows
Solari	Request Solari; the camera attaches Bevy Solari when RT support is available

Solari in Bevy 0.18 samples directional lights and emissive meshes. Point and spot lights require the normal PBR light pass, so LightDesc point/spot components are runtime-disabled while Solari is active. The component remains in the scene, the inspector shows an unsupported message, and hydration strips/skips the Bevy PointLight / SpotLight until authors switch the light to Directional or switch GI to Forward. The viewport resolves Hybrid Auto through EffectiveRenderStack: requested Solari keeps project meshes eligible for raytracing and attaches Bevy Solari when RT support is available. Effective GI falls back to Forward only when RT is unavailable. Effective Solari forces an HDR camera target even if project HDR is off, because Bevy Solari writes to the main texture through a storage binding and sRGB textures are invalid for that use. Primitive hydration generates tangents so built-in boxes/spheres can enter Solari BLAS/TLAS; imported/custom meshes still need TriangleList geometry, POSITION/NORMAL/UV_0/TANGENT attributes, and U32 indices. The Rendering panel reports the exact fallback reason, Solari-compatible asset counts, bind-group state, and compatible light counters. Set BEVY_FPS_FORCE_SOLARI=1 to force RT feature probing in dev (see README troubleshooting).

Emissive lighting

Material authoring includes emissive color, emissive intensity (nits), and an optional emissive texture. Emissive materials contribute to bloom in Forward PBR and count as Solari-compatible light sources when the material is on eligible project geometry. Use emissive surfaces for area-style indirect light in Solari scenes; use point/spot lights when local direct lighting and shadows are more important.

Asset folders

Path	Purpose
`assets/rendering_profiles/*.ron`	Named override bundles (`RenderingProfileAsset`); Apply / Revert in volume inspector
`assets/post_fx/*.ron` + `.wgsl`	Fullscreen effects (`PostProcessEffectAsset`); picker in volume inspector
`assets/materials/*.ron`	Material presets, including emissive fields for Solari-compatible surfaces

Shipped examples: post_fx/vignette.ron, post_fx/chromatic_aberration.ron, rendering_profiles/cave_dark.ron, rendering_profiles/outdoor_haze.ron, materials/emissive_panel.ron.

Game team checklist

Keep global look in assets/project.ron.
Use volumes for rooms/biomes; set label for HUD clarity.
Reuse looks via rendering_profiles/ presets.
Add custom shaders under assets/post_fx/ — do not fork camera_fx.rs for one-off levels.
Prefer GiMode::Auto for the default project path. Use GiMode::Forward when authoring point/spot lighting or debugging classic shadow maps.
Use emissive material presets for Solari indirect-light contributors; keep helper meshes tagged RaytracingExcluded.

Example level

Open assets/levels/rendering_showcase.scn.ron for fog, exposure, and vignette volume examples.

Troubleshooting

Symptom	Check
Point/spot weak at max lumens	Outdoor exposure (~12–15 EV100 in Project Settings) needs much higher lumens than indoor (~7 EV100). Bevy’s reference scale is ~1M lumens (`VERY_LARGE_CINEMA_LIGHT`); inspector allows up to 2M. Narrow spot cones for brighter hotspots. For local lights, GI path must be Forward (Solari uses directional + emissive only).
Point/spot controls disabled under GiMode Auto	Auto selected Solari on this GPU. Point/spot `LightDesc` is disabled while Solari is active; switch the light to Directional, use emissive materials, or set GI to Forward.
Scene sun shadow range wrong vs Project Settings	Scene directionals use `cascade_config_from_rendering`; Apply shadow cascade settings and confirm `sync_scene_directional_shadow_cascades`
Auto exposure not active	Rendering → Active Camera: needs Exposure: Auto, HDR on, and GPU compute. Volume Exposure EV100 override forces manual for that view.
Viewport black in Lit	Rendering panel → Runtime lights, Stack, and Solari raytracing scene; Collider mode hides meshes
Solari warming up	Solari raytracing scene readiness: tagged meshes, Solari-compatible mesh assets, render instances, bind group, compatible lights
Lighting changes do nothing in Solari	Solari samples directional lights and emissive meshes; point/spot `LightDesc` is disabled while Solari is active
GI badge shows Forward unexpectedly	Solari RT wgpu features unavailable; Rendering → Active Camera tab
Volume has no effect	Camera inside AABB? Priority vs other volumes? Overrides enabled?
Custom FX missing	RON path in volume matches `assets/post_fx/`; shader path in RON

Command palette: rendering.select_volumes_at_camera, rendering.focus_active_volumes.

7.3 KiB Raw Blame History Unescape Escape