Phase 1: polish LOD seams, fades, and representative sampling

[MichaelFisher1997]

Goal

Improve the current LOD rendering path with visible polish before deeper data-model changes.

Work Items

• Replace or augment boundary-only skirts with adjacency-aware edge stitching.
• Add dithered/faded LOD handoff in the shader path so near/far transitions are softer.
• Improve representative material and color sampling for surface cells.
• Tune water-edge handling, fog start, and mask-radius behavior.
• Add focused visual/debug logging for seam and transition failures.

Acceptance Criteria

• LOD region borders show fewer cracks and less popping during movement.
• Full-detail chunks and LOD regions blend without abrupt cutoffs in normal camera movement.
• Existing heightfield LOD behavior remains available and stable.
• zig build test passes.

[github-actions]

This is a Feature Request focused on LOD (Level of Detail) rendering polish. The work items are well-scoped within the world-lod module and shader path.

Analysis:

The codebase already has a solid LOD foundation:

• Skirts are implemented per-cell at boundaries (lod_mesh.zig:buildFromSimplifiedData)
• Dithered transitions exist in terrain.frag with LOD_TRANSITION_WIDTH = 24.0
• Seam stitching via stitchEdge() in lod_seam.zig with 2-cell blend
• QEM simplification is currently disabled due to visible cracks

Work Item Mapping:

Work Item	Primary Files
Adjacency-aware edge stitching	lod_mesh.zig, lod_seam.zig
Dithered/faded LOD handoff	terrain.frag:computeLOD(), g_pass.frag
Representative material sampling	lod_mesh.zig (mesh generation)
Water-edge/fog/mask-radius tuning	lod_chunk.zig, lod_renderer.zig
Debug logging for seams	lod_renderer.zig, lod_stats.zig

Notes:

• The QEM path (lod_manager.zig:740-742) is commented out - fixing the terraced-hole issue would enable better simplifications
• Existing debug flags: ZIGCRAFT_LOD_DIAG, ZIGCRAFT_LOD_DISABLE_FRUSTUM, -Dchunk-debug-mode
• Current lod_y_offset: -1.0 in lod_renderer.zig:154 already handles z-fighting; tuning this may help with the handoff

Recommendation: This is appropriately scoped as a Phase 1 polish pass. Consider splitting item 3 (material/color sampling) into a separate sub-issue if it requires changes to the block/texture atlas system, as that's a larger surface area.

The acceptance criteria are testable via visual inspection and zig build test passing.

opencode session  |  github run