fix: stabilize LOD streaming transitions

[MichaelFisher1997]

Summary

• remove visual LOD seam distortion and prevent water-cell vegetation ingestion
• bound and prioritize horizon LOD scheduling while reserving worker capacity for nearby chunks
• use a fast LOD4 horizon fallback that LOD3 refines at full far-terrain detail

Validation

• Zig 0.16.0 + SDL3 Dev Environment
  Compiler: 0.16.0
  Shadow ABI reflection: 4 matrices, 352-byte block, offsets 0/256/272/288/304/320/336
  SPIR-V size: assets/shaders/vulkan/bloom_downsample.frag 9764 bytes (72ms compile)
  SPIR-V size: assets/shaders/vulkan/bloom_downsample.vert 1160 bytes (69ms compile)
  SPIR-V size: assets/shaders/vulkan/bloom_upsample.frag 3956 bytes (69ms compile)
  SPIR-V size: assets/shaders/vulkan/bloom_upsample.vert 1160 bytes (69ms compile)
  SPIR-V size: assets/shaders/vulkan/culling.comp 11352 bytes (72ms compile)
  SPIR-V size: assets/shaders/vulkan/debug_shadow.frag 836 bytes (69ms compile)
  SPIR-V size: assets/shaders/vulkan/debug_shadow.vert 1344 bytes (69ms compile)
  SPIR-V size: assets/shaders/vulkan/depth_pyramid.comp 2936 bytes (67ms compile)
  SPIR-V size: assets/shaders/vulkan/fxaa.frag 5916 bytes (67ms compile)
  SPIR-V size: assets/shaders/vulkan/fxaa.vert 1160 bytes (66ms compile)
  SPIR-V size: assets/shaders/vulkan/g_pass.frag 5596 bytes (71ms compile)
  SPIR-V size: assets/shaders/vulkan/lpv_inject.comp 4844 bytes (71ms compile)
  SPIR-V size: assets/shaders/vulkan/lpv_propagate.comp 8316 bytes (65ms compile)
  SPIR-V size: assets/shaders/vulkan/mesh.comp 45244 bytes (71ms compile)
  SPIR-V size: assets/shaders/vulkan/post_process.frag 10856 bytes (67ms compile)
  SPIR-V size: assets/shaders/vulkan/post_process.vert 1160 bytes (70ms compile)
  SPIR-V size: assets/shaders/vulkan/shadow.frag 1592 bytes (71ms compile)
  SPIR-V size: assets/shaders/vulkan/shadow.vert 4596 bytes (68ms compile)
  SPIR-V size: assets/shaders/vulkan/sky.frag 18980 bytes (68ms compile)
  SPIR-V size: assets/shaders/vulkan/sky.vert 2696 bytes (67ms compile)
  SPIR-V size: assets/shaders/vulkan/ssao_blur.frag 1760 bytes (69ms compile)
  SPIR-V size: assets/shaders/vulkan/ssao.frag 6588 bytes (75ms compile)
  SPIR-V size: assets/shaders/vulkan/ssao.vert 1160 bytes (65ms compile)
  SPIR-V size: assets/shaders/vulkan/taa.frag 9760 bytes (67ms compile)
  SPIR-V size: assets/shaders/vulkan/taa.vert 1160 bytes (66ms compile)
  SPIR-V size: assets/shaders/vulkan/terrain_debug.frag 1336 bytes (65ms compile)
  SPIR-V size: assets/shaders/vulkan/terrain.frag 61928 bytes (78ms compile)
  SPIR-V size: assets/shaders/vulkan/terrain.vert 10500 bytes (71ms compile)
  SPIR-V size: assets/shaders/vulkan/ui.frag 744 bytes (69ms compile)
  SPIR-V size: assets/shaders/vulkan/ui_tex.frag 1408 bytes (71ms compile)
  SPIR-V size: assets/shaders/vulkan/ui_tex.vert 1344 bytes (71ms compile)
  SPIR-V size: assets/shaders/vulkan/ui.vert 1336 bytes (67ms compile)
  SPIR-V size: assets/shaders/vulkan/water.frag 20368 bytes (71ms compile)
  SPIR-V size: assets/shaders/vulkan/water.vert 8796 bytes (73ms compile)
  assets/shaders/vulkan/bloom_downsample.vert
  assets/shaders/vulkan/bloom_upsample.vert
  assets/shaders/vulkan/debug_shadow.vert
  assets/shaders/vulkan/fxaa.vert
  assets/shaders/vulkan/post_process.vert
  assets/shaders/vulkan/shadow.vert
  assets/shaders/vulkan/sky.vert
  assets/shaders/vulkan/ssao.vert
  assets/shaders/vulkan/taa.vert
  assets/shaders/vulkan/terrain.vert
  assets/shaders/vulkan/ui_tex.vert
  assets/shaders/vulkan/ui.vert
  assets/shaders/vulkan/water.vert
  assets/shaders/vulkan/bloom_downsample.frag
  assets/shaders/vulkan/bloom_upsample.frag
  assets/shaders/vulkan/debug_shadow.frag
  assets/shaders/vulkan/fxaa.frag
  assets/shaders/vulkan/g_pass.frag
  assets/shaders/vulkan/post_process.frag
  assets/shaders/vulkan/shadow.frag
  assets/shaders/vulkan/sky.frag
  assets/shaders/vulkan/ssao_blur.frag
  assets/shaders/vulkan/ssao.frag
  assets/shaders/vulkan/taa.frag
  assets/shaders/vulkan/terrain_debug.frag
  assets/shaders/vulkan/terrain.frag
  assets/shaders/vulkan/ui.frag
  assets/shaders/vulkan/ui_tex.frag
  assets/shaders/vulkan/water.frag
  assets/shaders/vulkan/culling.comp
  assets/shaders/vulkan/depth_pyramid.comp
  assets/shaders/vulkan/lpv_inject.comp
  assets/shaders/vulkan/lpv_propagate.comp
  assets/shaders/vulkan/mesh.comp
• Zig 0.16.0 + SDL3 Dev Environment
  Compiler: 0.16.0
  === LOD heightmap generation benchmark (generator='overworld' seed=1337) ===
  lod1: grid=65x65 (~4225 cols) avg=290.8ms min=281.0ms max=305.0ms
  lod2: grid=65x65 (~4225 cols) avg=306.0ms min=288.0ms max=327.0ms
  lod3: grid=129x129 (~16641 cols) avg=1211.3ms min=1122.0ms max=1283.0ms
  lod4: grid=65x65 (~4225 cols) avg=318.8ms min=289.0ms max=341.0ms

Interpretation:

• If LOD4 avg < ~500ms: generation is cheap; LOD loading is bounded by
  worker throughput/contention, not per-region cost.
• If LOD4 avg > ~2000ms: generation itself is the bottleneck.

Benchmark

• LOD4 source generation: 1225ms to 315ms per region (~74% faster)

[github-actions]

kcov coverage

Line coverage ran for this PR and uploaded a non-blocking report artifact named kcov-report. Codecov upload is configured as non-blocking while the project captures a stable baseline.

[github-actions]

📋 Summary

PR #914 has no linked issues. It stabilizes LOD streaming by removing boundary-height blending that caused seam distortion, replacing dithered LOD transitions with a hard radial mask, blocking vegetation generation in water cells, bounding pending LOD region admission, reducing LOD4 source grid resolution, and avoiding redundant relighting of newly generated chunks.

Validation: full zig build test and zig fmt --check pass; LOD4 generation benchmark improved from 1225ms to 315ms per region.

📌 Review Metadata

• Reviewed Commit SHA: 66c14c8dee39da10068617ffecff91661b37d1b2
• Reviewed PR: fix: stabilize LOD streaming transitions #914

No linked issues were found in the PR description. The implementation matches the stated goals: seam-stitching logic is removed, water-cell vegetation is blocked, horizon scheduling is bounded, and the fast LOD4 / detailed LOD3 split is implemented.

🔴 Critical Issues (Must Fix - Blocks Merge)

None identified.

⚠️ High Priority Issues (Should Fix)

None identified.

💡 Medium Priority Issues (Nice to Fix)

None identified.

ℹ️ Low Priority Suggestions (Optional)

[LOW] modules/world-lod/src/lod_renderer.zig:647 - calculateBandFade is now unused
Confidence: High
Description: The fade calculation was intentionally replaced by chunk.transitionFadeProgress() at line 606, but calculateBandFade and its dedicated tests remain in the file.
Impact: Dead code adds maintenance surface and can confuse future readers about how LOD handoff is actually controlled.
Suggested Fix: Remove calculateBandFade and its tests, or add a doc comment explaining it is intentionally retained for a future distance-based fallback.

[LOW] assets/shaders/vulkan/water.frag:14 - Unused vLODFade input
Confidence: High
Description: The fragment shader still declares layout(location = 11) in float vLODFade; after the dithered LOD-fade discard was removed.
Impact: Slightly misleading shader interface; a wasted interpolator.
Suggested Fix: Remove the vLODFade in/out from water.frag and water.vert.

[LOW] modules/world-runtime/src/chunk_queue_coordinator.zig:540 - Redundant lighting_valid assignment
Confidence: High
Description: chunk_data.chunk.lighting_valid = true is set at line 540 inside the generated_new block, then set again at line 563 in the trailing else branch.
Impact: None functional, but the duplication is unnecessary.
Suggested Fix: Drop the assignment at line 563 since the generated_new branch already handles it.

📊 SOLID Principles Score

Principle	Score	Notes
Single Responsibility	7	Each module has a clear focus, but world_streamer.zig now mixes worker budgeting with streamer logic.
Open/Closed	8	Changes are mostly additive/config-driven; scheduler cap is a new field rather than a rewrite.
Liskov Substitution	8	No interface hierarchy changes; LOD data/mesh behavior remains consistent.
Interface Segregation	8	Shader inputs are still fine-grained; scheduler context fields are optional.
Dependency Inversion	7	RHI abstraction remains intact; LOD worker reserve is advisory and not enforced against the LODManager.
Average	7.6

🎯 Final Assessment

Overall Confidence Score: 88%

Confidence Breakdown:

• Code Quality: 85% (clean, well-commented, a few dead-code remnants)
• Completeness: 90% (covers all stated goals with tests and benchmarks)
• Risk Level: 75% (shader handoff is a deliberate hard transition; LOD cache invalidated by generator version bump)
• Test Coverage: 90% (new tests added for water-cell vegetation, pending-region cap, and authoritative boundary heights)

Merge Readiness:

• All critical issues resolved
• SOLID average score >= 6.0
• Overall confidence >= 60%
• No security concerns
• Tests present and passing (if applicable)

Verdict:

MERGE WITH FIXES

The PR is solid and well-validated; only minor dead-code cleanup is needed before merging.

{
  "reviewed_sha": "66c14c8dee39da10068617ffecff91661b37d1b2",
  "critical_issues": 0,
  "high_priority_issues": 0,
  "medium_priority_issues": 0,
  "overall_confidence_score": 88,
  "recommendation": "MERGE"
}

opencode session  |  github run