[Lighting Overhaul][Phase 1] Rewrite world-level voxel lighting and relight migration

[MichaelFisher1997]

Parent

Part of #898.

Depends on

#900.

Goal

Replace duplicated chunk-local lighting with one authoritative world-level system whose output is cross-chunk, deterministic, mutation-safe, and compatible with existing worlds.

Scope

• Introduce a WorldLightingEngine used by generation, loading, and runtime mutations.
• Centralize block opacity, light transmission/attenuation, and RGB emission rules.
• Seed direct skylight columns and RGB emitters, then propagate in all six directions across loaded chunk boundaries.
• Add proper addition/removal queues that follow the full light influence rather than a one-chunk edit box.
• Reconcile light frontiers when a chunk loads, generates, or gains a neighbor; results must not depend on load order.
• Use one water/translucent attenuation rule for generation and runtime updates.
• Remove entrance_bounce and entrance_dir; ordinary propagated skylight becomes the source of cave-entrance illumination.
• Add chunk content/light revisions or immutable meshing snapshots. Publish a worker mesh only when its captured revision still matches.
• Add a lighting algorithm version to world metadata. Existing worlds keep blocks but ignore stale derived light and relight asynchronously on load.
• Keep chunks non-renderable until the required local light frontier is stable; avoid a one-frame black or fullbright flash.
• Keep GPU meshing disabled until it can consume the same light data and vertex contract.

Acceptance criteria

• Skylight and RGB emitters propagate seamlessly across chunk boundaries.
• Placing/removing opaque and emissive blocks updates every affected loaded chunk.
• Results are identical for different chunk generation/load orders.
• Water/translucent attenuation is identical before and after runtime relighting.
• Existing version-two worlds load and relight without block or biome loss.
• No stale mesh can overwrite a newer block/light revision.
• Cave entrance, sealed cave, torch, and cross-chunk corridor tests pass.
• Entrance-light storage and vertex attributes are removed after migration.

Required tests

• Cross-chunk skylight in all four horizontal directions and corners.
• Cross-chunk RGB addition and removal from local coordinates 0 through 15.
• Upward/downward propagation and enclosed-cave behavior.
• Load-order permutation tests.
• Relight-on-load migration fixture.
• Mutation-versus-meshing revision rejection.

Verification

nix develop --command zig fmt modules/world-core/src modules/world-runtime/src modules/world-meshing/src modules/world-persistence/src modules/worldgen-common/src
nix develop --command zig build test
nix develop --command zig build -Dskip-present
nix develop --command zig build run -Dskip-present -Dauto-world=normal -Dstartup-diagnostic-seconds=5

[github-actions]

Analysis

Classification: Feature Request / architectural refactor (part of the umbrella #898 lighting overhaul, blocked on Phase 0 #900).

This is a well-scoped design doc, but it is far too large to land in a single PR. The scope enumerates ~11 cross-cutting changes that span at least five subsystems, and the acceptance criteria list eight independently verifiable properties. Implementing all of it as one branch would make review impossible, conflict with Phases 2–5 (#901, #903, #902, #904), and prevent bisectability on regressions.

What already exists (so we don't reinvent it)

A review of the current tree shows most of the machinery is already in place — the work is largely about unifying and removing duplication, not writing it from scratch:

• modules/world-runtime/src/lighting_engine.zig already implements chunk-local seed/spread for both skylight columns and RGB emitters, with cross-chunk neighbor lookup via ChunkStorage.get(cx + dx, cz + dz) (see lighting_engine.zig:30-50). Phase 1 mostly needs to (a) extend the spread box past the current 1-chunk edit radius, and (b) replace recomputeArea with a load-order-independent frontier reconcile.
• modules/world-core/src/chunk.zig:40-41 holds entrance_bounce: [CHUNK_VOLUME]u4 and entrance_dir: [CHUNK_VOLUME]u8 — these are exactly the fields to remove. They are read in world-meshing/src/meshing/*.zig (cross_mesher.zig:50-52, flat_quad_mesher.zig:50-52, tall_cross_mesher.zig:56-58, wall_attached_mesher.zig:59-61, custom_mesh_mesher.zig:60-62, greedy_mesher.zig:94-109) and world-lod/src/lod_geometry.zig:1387. There is also a vertex attribute at engine-rhi/src/rhi_types.zig:100 (entrance_dir: u32) and a shader binding at engine-graphics/src/vulkan/pipeline_specialized.zig:65 (location 6, R32_UINT).
• World-metadata versioning is already half-built: world-persistence/src/level_data.zig is a flat JSON file with seed/generator_name/timestamps/spawn, and world-persistence/src/chunk_serializer.zig:9 declares version: u8 = 2. Phase 1 should add a lighting_algorithm_version field to LevelData and bump the chunk wire-format to v3 with a has_light flag honoring the migration policy.
• Mutation entry point: modules/world-runtime/src/world_mutation.zig (248 LOC) currently calls LightingEngine.recomputeArea from a fixed edit box (lighting_engine.zig:23). Wiring WorldLightingEngine here is the natural seam.
• The acceptance criterion "no stale mesh overwrites newer revision" maps cleanly onto modules/world-meshing/src/chunk_storage.zig / chunk_mesh.zig:411 — the mesh task already carries a chunk handle; Phase 1 needs to also stamp chunk.content_revision (to be added) and reject publish on mismatch, parallel to the LOD seam at world-lod/src/lod_manager_*.zig.

Proposed split (suggest turning each into its own sub-issue under #899)

Each item below is independently mergeable, has its own acceptance gate, and matches one logical PR:

1. WorldLightingEngine skeleton + chunk revision counters — introduce the new type, add content_revision: u64 and light_revision: u64 to Chunk, plumb through ChunkStorage. No behavior change yet.
2. Unified opacity / transmission / RGB-emission rules — move def.isOpaque(), water attenuation, and emission tables into one place (likely world-core next to block_registry.zig) and have all lighting paths (lighting_engine.zig, worldgen-common/src/lighting_computer.zig, runtime updates) call it. Acceptance: existing tests pass with identical numerical output.
3. Cross-chunk, load-order-independent propagation — replace the 3×3 edit box with a true frontier walk that converges to the same final PackedLight regardless of ChunkStorage insertion order. Acceptance: load-order permutation test passes.
4. Mutation-queue refactor — afterBlockRemoval / future afterBlockAddition follow full light influence; opaque/emissive placement updates every loaded chunk in range. Acceptance: cross-chunk RGB removal test (local coords 0–15) passes.
5. entrance_bounce / entrance_dir removal — delete the chunk fields, vertex attribute, shader location, RHI helper (encodeEntranceDirection etc. in engine-rhi/src/rhi_types.zig:100-215), the debug menus (game-ui/src/screens/world_debug.zig, engine-ui/src/debug_menu.zig), and the DebugFeature.entrance_bounce_debug setting. Verify cave-entrance looks come from ordinary skylight propagation.
6. World metadata versioning + relight-on-load migration — add lighting_algorithm_version to LevelData, bump chunk wire-format to v3 (or keep v2 but with has_light=false forcing relight), make the save manager reset stored light on load and queue a relight. Acceptance: existing worlds load without block/biome loss.
7. Mesh revision-rejection + renderable gate — workers capture content_revision at mesh start, ChunkStorage rejects publish if the handle's revision advanced, and the renderer skips chunks whose local light frontier isn't stable. Acceptance: mutation-vs-meshing test passes, no black/fullbright flash in headless screenshots.
8. GPU-meshing hookup (or explicit "disabled") — either teach gpu_mesher.zig to consume the new vertex contract, or document the disabling point. (This may be a no-op if the contract doesn't change in Phase 1.)

Missing / ambiguous info

Could you clarify before we spin up the sub-issues?

• "Existing worlds keep blocks but ignore stale derived light" — confirm the migration policy: do we drop the LightData section from saved v2 chunks and recompute on load, or do we keep the section and just gate it behind the version compare? The acceptance criterion "load and relight without block or biome loss" implies the former, but a one-line note in chunk_serializer.zig:46-51 (HeaderFlags) would make it explicit.
• "One water/translucent attenuation rule" — is the existing attenuation in worldgen-common/src/lighting_computer.zig the canonical one to keep, or does Phase 1 want a different constant? A pointer to the current attenuation code would prevent two implementations drifting.
• "Required tests" enumerates 6 test fixtures — which existing test files (e.g., modules/world-core/src/light_fuzz_tests.zig, world-meshing/src/chunk_mesh_tests.zig) should they live in, or do you want a new modules/world-core/src/lighting_world_tests.zig aggregator?
• Linkage to Phase 0 [Lighting Overhaul][Phase 0] Establish visual baselines and repair pipeline contracts #900 — the issue says "depends on" Phase 0, but doesn't link it. Worth adding a Depends on: #900 / Blocked by: #900 reference so the dependency graph is visible.

Suggested next step

Split #899 into the eight sub-issues above and link them in a checklist under the umbrella #898. Each sub-issue gets a single PR. The first PR (skeleton + revision counters, item 1) is unblocked as soon as Phase 0 lands and is the right place to validate the chunk-revision approach before any behavior changes.

Happy to draft any of the sub-issue bodies if useful.

[github-actions]

Posted analysis on #899. Summary of the comment:

• Classification: Feature Request / architectural refactor (umbrella [Lighting Overhaul][Umbrella] Rebuild voxel lighting, shadows, and scene composition #898, blocked on Phase 0 [Lighting Overhaul][Phase 0] Establish visual baselines and repair pipeline contracts #900).
• Scope concern: Too large for one PR — ~11 cross-cutting changes across ≥5 subsystems with 8 independent acceptance criteria. Suggested splitting into 8 sub-issues (engine skeleton + revisions, unified opacity rules, cross-chunk propagation, mutation queue, entrance_* removal, metadata versioning + relight-on-load migration, mesh revision-rejection, GPU-meshing hookup).
• Code pointers to existing machinery: lighting_engine.zig:30-50 (current edit box), chunk.zig:40-41 (fields to delete), world-meshing/src/meshing/*.zig (readers), engine-rhi/src/rhi_types.zig:100-215 (RHI helpers), chunk_serializer.zig:9 (wire format v2), level_data.zig (metadata).
• Missing info requested: migration policy for v2 chunks, canonical water/translucent attenuation location, where new tests should live, and an explicit Blocked by #900 link.

opencode session  |  github run