[Lighting Overhaul][Phase 5] Remove legacy paths and enforce regression gates

[MichaelFisher1997]

Parent

Part of #898.

Depends on

#900, #899, #903, #901, and #902.

Goal

Remove superseded paths, lock visual/performance regressions behind automated gates, and roll the overhaul out as the sole supported lighting path.

Scope

• Delete duplicated worldgen/runtime lighting implementations after migration.
• Delete entrance-light storage/packing/shader code and stale save handling after compatibility coverage exists.
• Remove dead PCSS/blocker-search helpers, unused sun-shaft functions, stale shadow debug APIs, and duplicated UBO definitions.
• Remove simple/legacy terrain lighting branches and obsolete quality toggles.
• Keep GPU meshing disabled or repair its vertex stride, light inputs, AO, and output parity before enabling it.
• Add deterministic visual regression captures for all lighting scenarios and preset tiers.
• Add benchmark thresholds for shadow, opaque, SSAO, volumetric, draw-call, and total GPU timings.
• Tune LOW/MEDIUM/HIGH/ULTRA/EXTREME sample counts and resource sizes while preserving visual semantics.
• Document the new lighting architecture, debug channels, world relight behavior, and preset cost model.
• Remove temporary migration code only when the supported save compatibility window permits it.

Acceptance criteria

• Only one production terrain lighting model remains.
• No duplicate voxel propagation implementation remains.
• Shader/CPU data contracts have automated ABI checks.
• Deterministic visual regression scenes cover caves, emitters, chunk seams, foliage, water, LOD, day/night, and cascade transitions.
• High preset sustains the agreed 1080p/60 FPS target on designated midrange hardware.
• No phase causes more than an approved 10% total GPU regression versus its recorded baseline.
• Documentation describes architecture, diagnostics, migration, and tuning controls.

Final verification

nix develop --command zig fmt src modules
nix develop --command zig build test
nix develop --command zig build -Doptimize=ReleaseFast
nix develop --command zig build test-integration
nix develop --command zig build test-robustness
nix develop --command zig build run -Dskip-present -Dauto-world=normal -Dstartup-diagnostic-seconds=5
nix develop --command zig build benchmark -Doptimize=ReleaseFast -Dbenchmark-preset=high -Dbenchmark-duration=60 -Dbenchmark-output=lighting-overhaul-final-high.json

[github-actions]

Tracking this as the terminal phase of the #898 umbrella.

A few observations worth surfacing before this gets picked up:

Dependency state. Phases 0-4 (#900, #899, #903, #901, #902) are all still OPEN with no merged PRs against dev. Acceptance criteria here (single terrain lighting model, no duplicate propagation, ABI checks, regression scenes for every scenario) literally cannot be validated until upstream phases land. I'd treat this issue as a preparation checklist and re-validate the closure criteria once each dependency is merged.

Scope is too broad for one PR. This currently bundles seven orthogonal workstreams:

1. Dead-code removal (duplicated propagation, entrance-light storage/packing/shader, PCSS/blocker-search, sun-shaft, shadow debug APIs, duplicated UBOs, simple/legacy lighting branches).
2. Deterministic visual regression captures across caves/emitters/seams/foliage/water/LOD/day-night/cascade transitions.
3. Benchmark thresholds for shadow, opaque, SSAO, volumetric, draw-call, and total GPU timings.
4. LOW/MEDIUM/HIGH/ULTRA/EXTREME preset tuning while preserving visual semantics.
5. GPU meshing parity repair (vertex stride, light inputs, AO, output).
6. Architecture/diagnostics/migration/preset documentation.
7. Save-compatibility migration code removal.

Suggest splitting into child issues (one per workstream, all blocking on #904):

• Phase 5a - dead-code removal (sweep PRs scoped per subsystem: worldgen vs runtime vs save vs shaders).
• Phase 5b - visual regression test infrastructure + scene authoring (depends on phases 3/4 merging so the scenes exercise the new path).
• Phase 5c - benchmark gating + CI thresholds (depends on phase 4 perf numbers being captured).
• Phase 5d - preset tuning pass (depends on 5c gates existing so tuning is measured).
• Phase 5e - GPU meshing parity OR explicit long-term disablement decision (this is a substantive engineering task, not cleanup; please clarify intent - repair or retire?).
• Phase 5f - documentation overhaul.
• Phase 5g - migration code removal (gated on a specific release version that defines the compatibility window).

Missing data needed before workstream sizing:

• The "designated midrange hardware" target - which GPU(s) anchor the 1080p/60 FPS budget? The umbrella names the target but doesn't pin the SKU.
• The "recorded baseline" GPU timings every phase is measured against. Where is this captured (docs/perf/baselines.md? benchmark JSONs in zig-out/?). Without an authoritative artifact, the 10% regression acceptance test is unenforceable.
• The save-compatibility window length and the version at which temporary migration code can be retired.
• Existing visual regression scenes - do any live under assets/test/scenes/ already, or is this greenfield?
• Whether GPU meshing repair is in scope for this overhaul or should be removed from the umbrella with a separate tracking issue; assets/shaders/vulkan/mesh.comp:30-37,188-199 from [Lighting Overhaul][Umbrella] Rebuild voxel lighting, shadows, and scene composition #898 is the contract problem to solve.

Potential follow-ups flagged by the umbrella audit that interact with this phase: removing simple_lighting_mode (umbrella Critical #2), reconciling sky/CPU UBO layouts (High #10), and the format-independent display encoding (High #11). All three are preconditions for the "only one production terrain lighting model" criterion.

Happy to draft the 5a-5g split as separate child issues once the missing data above is supplied.

[github-actions]

Commented on #904: noted dependency state (Phases 0-4 still open), recommended splitting into 7 child workstreams (5a-5g), flagged GPU-meshing intent question, and requested the missing baseline data (designated GPU, recorded GPU baselines, save-compat window, existing regression scenes).

opencode session  |  github run