[Lighting Overhaul][Phase 3] Unify terrain lighting, atmosphere, and output

[MichaelFisher1997]

Parent

Part of #898.

Depends on

#900, #899, and #903.

Goal

Replace simple/legacy/partial-PBR branching with one atmosphere-driven, scene-linear PBR-lite model matching the selected cinematic saturated art direction.

Scope

• Remove the hard-coded simple_lighting_mode override.
• Collapse terrain simple, legacy, and partial-PBR branches into one shared lighting equation.
• Use Lambert diffuse plus restrained dielectric GGX specular; metalness remains zero unless explicitly authored.
• Compose directional sun/moon, hemispherical sky irradiance, subtle neutral ground bounce, propagated skylight, and colored RGB block light.
• Apply mesh AO and SSAO only to indirect diffuse, not direct sun or specular.
• Add a controlled readable-dark indirect floor without converting low-light albedo to gray-blue.
• Correct camera-relative view vectors and TBN handedness.
• Produce sun radiance, sky/ground irradiance, fog/scattering colors, and exposure from one atmosphere state.
• Keep terrain, sky, fog, water inputs, and future volumetrics on the same atmosphere contract.
• Keep albedo sampling in sRGB hardware decode and all lighting/composition in linear HDR.
• Use one AgX-style tone map and exactly one display encoding step.
• Move cinematic saturation/contrast into an authored LUT; remove mandatory applyLushGrade stacking and hard-coded cyan cave/sky terms.
• Retune presets so they share the same visual model and differ only in feature quality/cost.

Acceptance criteria

• HIGH/ULTRA settings are no longer silently overridden by simple lighting.
• Caves are dark but readable and preserve material chroma.
• Day, sunset, night, and emissive lighting remain coherent without a global cyan cast.
• Direct, indirect, AO, shadow, and block-light debug channels sum to the final result predictably.
• Absolute world position does not alter Fresnel/specular response.
• Windowed and headless output remain color-equivalent.
• All presets retain the same lighting semantics.

Verification

nix develop --command zig build test
nix develop --command zig build -Dskip-present
nix develop --command zig build run -Dskip-present -Dauto-world=normal -Dscreenshot-path=screenshots/lighting-phase3-world.png -Dscreenshot-frame=180 -Dscreenshot-delay-seconds=3
nix develop --command zig build benchmark -Doptimize=ReleaseFast -Dbenchmark-preset=high -Dbenchmark-duration=60 -Dbenchmark-output=lighting-phase3-high.json

[github-actions]

Thanks for the detailed phase breakdown — this matches the umbrella in #898 and the audit evidence lines up with what I'm seeing in the tree today. I'll classify this as a Feature / Bug hybrid (it removes a forced override that masks correct behavior across the lighting pipeline), and I've cross-checked the related context below before suggesting how to slice it.

Cross-references / duplicates

• Parent umbrella: [Lighting Overhaul][Umbrella] Rebuild voxel lighting, shadows, and scene composition #898 — the audit summary there already pins the exact code paths this issue is asking us to clean up.
• Sister phases still open: [Lighting Overhaul][Phase 0] Establish visual baselines and repair pipeline contracts #900 (Phase 0 – baselines & contracts), [Lighting Overhaul][Phase 1] Rewrite world-level voxel lighting and relight migration #899 (Phase 1 – voxel lighting), [Lighting Overhaul][Phase 2] Rewrite cascaded shadows and caster submission #903 (Phase 2 – shadows), [Lighting Overhaul][Phase 4] Bring AO, materials, water, LOD, and volumetrics to parity #902 (Phase 4 – AO/materials/water/LOD/volumetrics), [Lighting Overhaul][Phase 5] Remove legacy paths and enforce regression gates #904 (Phase 5 – cleanup & gates).
• No open or merged PR currently targets Phase 3 — confirmed via gh pr list --search "phase3" and a gh pr list --search "unify terrain" sweep. Safe to branch from dev without conflicting work.

Scope check

The acceptance criteria are crisp, but the work spans at least five subsystems (terrain shader, post-process, frame-params plumbing, atmosphere contracts, preset retune). I'd strongly recommend landing this as four sequential PRs targeting dev instead of one mega-PR — reviewers can keep the math and the LUT/tonemap step mentally separate, and a shader ABI regression can be bisected cleanly. Suggested split:

1. PR 3a — remove the simple_lighting_mode override
   • modules/game-ui/src/screens/world.zig:355-356 drop the const simple_lighting_mode = true; TODO comment (the comment itself already promises this)
   • modules/game-ui/src/screens/world_frame_params.zig:27,46,73,74,87,94 derive every suppression from safe_mode / startup_light_render / render_system flags only
   • update Settings so low/medium/high/ultra presets keep the same lighting semantics and only differ in cost (resolution, samples, cascade count) — verify the umbrella acceptance line "No second lighting path for individual presets"
2. PR 3b — collapse the three terrain branches into one PBR-lite path
   • assets/shaders/vulkan/terrain.frag:767-777 collapse computePBR / computeNonPBR / computeLegacyDirect / computeLOD / fallback into one call site
   • Lambert + dielectric GGX with metalness=0 unless an authored override exists; this also retires the cyan/cave hard-coded tints at terrain.frag:489-503
   • AO/SSAO applied only to indirect diffuse in the unified function — partial fix for the medium-severity SSAO finding in [Lighting Overhaul][Umbrella] Rebuild voxel lighting, shadows, and scene composition #898
3. PR 3c — atmosphere contract, sun radiance, and view-vector correctness
   • Camera-relative view vectors & TBN handedness fix at terrain.frag:767-773
   • Centralize sun_color, sky_color, horizon_color, fog_color, fog_density, sun_intensity, moon_intensity, exposure on a single Atmosphere snapshot in modules/engine-atmosphere/src/root.zig so terrain, sky, water, fog, and post all share one source of truth
4. PR 3d — display transform (one AgX + one EOTF + LUT-driven grade)
   • assets/shaders/vulkan/post_process.frag:107-115 delete applyLushGrade and the two call sites at lines 234 and 242
   • Make sure agxToneMap (post_process.frag:98-105) is the single tonemap and agxEotf (post_process.frag:72-84) is the single display encoding, routed through the existing 3D LUT (uColorLUT) for cinematic chroma rather than stacked shader tweaks — this is what unblocks the headless↔windowed color-equivalence acceptance line

Validation needs (please confirm)

• Which preset values should map to the shared model? The current Settings has pbr_quality, lpv_*, volumetric_*, shadow_* knobs — do you want a focused doc/table in the PR describing cost-only deltas per preset, or is "retune to match current visuals at low/medium and add budget relief at high/ultra" enough?
• For the LUT-driven grade, do you have an authored .cube LUT to commit, or should the LUT sampler default to identity until artists supply one? Identity is the safer default to avoid regressing screenshots.
• The umbrella acceptance line "Shadow GPU < 2.5 ms, SSAO < 1 ms, volumetrics < 2 ms" lives under Phase 5 — but Phase 3's "all presets retain the same lighting semantics" will change SSAO/LPV eligibility defaults. Worth confirming before 3a lands that you don't want the budget gates re-validated there too.

Out of scope (confirm)

• AO/SSAO math rewrite (stays in [Lighting Overhaul][Phase 4] Bring AO, materials, water, LOD, and volumetrics to parity #902 per "ssao combines view-space positions with world-space normals").
• LPV data path (still quarantined in [Lighting Overhaul][Umbrella] Rebuild voxel lighting, shadows, and scene composition #898).
• Any shadow math (Phase 2).

Once 3a-3d are stacked, Phase 4 (#902) and Phase 5 (#904) can layer cleanly. Happy to drive any one of the sub-PRs when you give the green light.

[github-actions]

Comment posted to issue #901: #901 (comment)

Summary: classified as Feature/Bug hybrid (removes a forced override masking correct behavior); cross-referenced umbrella #898 and sister phases; confirmed no duplicate PRs exist; recommended splitting into 4 sequential PRs (3a override removal, 3b terrain branch collapse, 3c atmosphere contract + view vectors, 3d display transform + LUT); flagged three validation needs (preset table, LUT asset vs identity default, SSAO/LPV budget re-validation).

opencode session  |  github run