[Lighting Overhaul][Phase 4] Bring AO, materials, water, LOD, and volumetrics to parity

[MichaelFisher1997]

Parent

Part of #898.

Depends on

#901.

Goal

Bring AO, materials, water, distant terrain, and optional cinematic effects into parity with the corrected baseline without compromising the 60 FPS target.

Scope

• Convert SSAO inputs to one coordinate space and replace box blur with depth/normal-aware bilateral filtering.
• Run SSAO at a cost-appropriate resolution and apply it only to indirect diffuse.
• Add tile-safe diffuse/normal/roughness mipmaps through gutters, padding, or texture-array migration; make anisotropy meaningful.
• Preserve material-frequency detail beyond the current 32-128 unit flattening range.
• Give LOD terrain propagated lighting semantics and atmosphere/shadow continuity rather than full hard-coded skylight.
• Rework water around Schlick Fresnel, atmosphere/sky reflection, scene reflection, depth-based Beer-Lambert absorption, modest scattering, and RGB block light.
• Remove fixed cyan and nighttime luminance floors from water.
• Reintroduce bounded volumetric sun scattering only after baseline benchmark budgets pass.
• Keep LPV explicitly experimental/quarantined with no allocation or update cost when disabled.
• Evaluate LPV separately after this phase; do not make it a completion dependency.

Acceptance criteria

• SSAO has no silhouette halos or coordinate-dependent rotation artifacts.
• AO strengthens contact depth without darkening direct sun/specular.
• Distant textures retain stable detail without atlas bleeding.
• LOD handoff does not change lighting semantics or expose a shadow wall.
• Water reflects the sky, responds to depth, and carries colored nearby light without opaque cyan plastic behavior.
• Optional volumetrics remain temporally stable and target below 2 ms at high preset/1080p.
• Disabled LPV allocates no textures/buffers and runs no update pass.

Verification

nix develop --command zig build test
nix develop --command zig build -Dskip-present
nix develop --command zig build test-robustness
nix develop --command zig build run -Dskip-present -Dauto-world=normal -Dscreenshot-path=screenshots/lighting-phase4-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-phase4-high.json

[github-actions]

Analysis

Classification: This is best treated as a Feature Request / multi-subsystem refactor umbrella, not a bug. Despite carrying the bug label, the body describes a forward-looking plan to bring several unrelated rendering systems to "parity with the corrected baseline." The automated-audit provenance lines up with how Phase 0–5 of #898 were scoped.

Validation:

• Parent umbrella: [Lighting Overhaul][Umbrella] Rebuild voxel lighting, shadows, and scene composition #898 ("[Lighting Overhaul][Umbrella] Rebuild voxel lighting, shadows, and scene composition").
• Hard dependency on [Lighting Overhaul][Phase 3] Unify terrain lighting, atmosphere, and output #901 (Phase 3: unified scene lighting + atmosphere contract) — Phase 4 cannot land coherently until Phase 3 stabilizes its scene/atmosphere contract.
• No open PR is currently implementing any Phase 4 item (verified gh pr list --search 'phase 4 OR SSAO OR volumetric' → empty).
• The targeted subsystems all exist where described: SSAO/material/post-fx in modules/engine-graphics/src/ (material_system.zig, texture_atlas.zig, render_graph.zig), LOD in modules/world-lod/src/ (lod_materials.zig, lod_mesh.zig), water/atmosphere under modules/engine-graphics/src/atmosphere/ and world-meshing/. LPV is already split via lpv_types.zig / lpv_utils.zig, so the "quarantine when disabled" requirement is tractable without new structure.

Scope is too broad for a single PR. The body bundles 8 distinct subsystems and at least 3 different review disciplines (graphics correctness, shader authoring, asset/texture pipeline). Each item in the Scope list has its own acceptance criterion and could regress the others. I strongly recommend splitting this into the following sub-issues before any implementation begins:

1. SSAO input-space + bilateral filter rewrite — coordinate-space unification, depth/normal-aware filter, indirect-diffuse-only application, resolution scaling. Acceptance: no silhouette halos, no rotation artifacts.
2. Tile-safe material mipmaps — gutters/padding or texture-array migration for diffuse/normal/roughness, plus meaningful anisotropy. Acceptance: no atlas bleeding at distance.
3. Material-frequency detail preservation — lift the 32–128 unit flattening cap. Likely shader + sampler-state work; pair with feat: implement layered noise worldgen with multi-noise biomes #2 for review.
4. LOD lighting continuity — propagated lighting semantics + atmosphere/shadow handoff at the LOD boundary. Acceptance: no "shadow wall" at the handoff radius.
5. Water shading rewrite — Schlick Fresnel, sky/scene reflection, Beer-Lambert absorption, modest scattering, RGB block light. Pair with removing the cyan and nighttime luminance floors. Acceptance: depth-correct color, sky reflection, no opaque cyan plastic.
6. Volumetric sun scattering — explicitly gated behind baseline benchmark budgets passing first, per the body. Suggest leaving this as a follow-up issue that links to the Phase 4 benchmark JSON, not part of the Phase 4 closure PR.
7. LPV quarantine / zero-cost when disabled — no allocations, no update pass when the feature flag is off. Acceptance criteria are already well-defined.
8. LPV evaluation — explicitly out of Phase 4 per the body ("do not make it a completion dependency"). Track as its own future issue, gated on Cascaded Shadow Maps (CSM) #7 landing first.

Suggested sequencing once Phase 3 (#901) is in:

• Land Cascaded Shadow Maps (CSM) #7 (LPV quarantine) first — it is the smallest, lowest-risk change and unblocks disabling LPV during the rest of Phase 4 work.
• Then Roadmapv3 #1 (SSAO) and feat: worm cave system with connected underground networks #4 (LOD continuity) — these directly touch the corrected baseline that Phase 3 establishes.
• Then feat: implement layered noise worldgen with multi-noise biomes #2 + feat: voxel engine with worldgen, async streaming, and render stability #3 together as one PR (textures + material shaders).
• Then code quality #5 (water) — depends on the atmosphere contract being stable.
• Atmosphere, Lighting & Shadows #6 (volumetrics) and feat: implement Minecraft-like cloud system #8 (LPV eval) belong in a later phase or as separate issues.

Action requested: Please split this issue into the sub-issues above (or describe a preferred split) so each can be sized, reviewed, and merged independently. Until that split lands, recommend keeping this issue open as the Phase 4 tracker and linking the sub-issues back to it via "depends on / blocks."

[github-actions]

Posted analysis comment on issue #902 recommending the umbrella be split into 8 sub-issues (SSAO, mipmaps, material frequency, LOD continuity, water rewrite, volumetrics, LPV quarantine, LPV eval) with suggested sequencing after Phase 3 (#901) lands.

opencode session  |  github run