fix: stabilize lighting and underwater rendering

[MichaelFisher1997]

Summary

• bound generation and meshing worker defaults, defer mutation lighting, and schedule affected remeshes immediately
• reconcile local lighting safely across chunk boundaries, including water transitions and high placed emitters
• improve tunnel and underwater lighting, fluid face visibility, kelp rendering, and aquatic vegetation density
• add regressions for water skylight, cross-chunk lighting, paused jobs, fluid faces, and texture fallback

Validation

• nix develop --command zig build test -j1
• nix develop --command zig build -j1 -Dskip-present
• pre-push formatting and full test hooks

[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

No linked issues are mentioned in the PR description.

PR #912 stabilizes runtime lighting and underwater rendering by deferring mutation lighting to the mesh worker pool, introducing bounded boundary reconciliation, and improving water/fluid/tunnel visual handling. It also adds regression tests for the changed behaviors. The implementation matches the PR summary, tests pass, and code is formatted.

🔴 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-runtime/src/world_mutation.zig:91 - MutationResult.chunk_data is unused in production
Confidence: High
Description: The chunk_data: *ChunkData field is only referenced in one test (places block within bounds). Production callers (World.setBlock, WorldStreamer.enqueueMutationLighting) only use the coordinate and lighting fields.
Impact: Slightly widens the API surface and exposes a pointer that can become stale if the chunk is unloaded before the async lighting job runs.
Suggested Fix: Remove chunk_data from MutationResult and update the one test to look up the chunk via storage.get.

[LOW] modules/world-runtime/src/lighting_engine.zig:158 - recomputeArea ignores its local coordinates
Confidence: High
Description: recomputeArea accepts local_x and local_z but immediately suppresses them with _ = local_x; _ = local_z; and always recomputes the full 3×3 window.
Impact: The API is misleading; callers may expect a smaller bounded update.
Suggested Fix: Rename to recomputeArea3x3 or document in the signature that the parameters are intentionally unused because boundary light can reach deep into the chunk.

[LOW] assets/shaders/vulkan/terrain.frag:429 and modules/world-core/src/block_registry.zig:142 - Magic constants for tunnel and water floor lighting
Confidence: Medium
Description: tunnelIrradiance = vec3(0.42) and attenuateVerticalSkylight clamping water to a minimum of 6 are hard-coded values with no named constants.
Impact: Future tuning requires hunting through source; values are not self-documenting.
Suggested Fix: Expose named constants (e.g., MIN_WATER_SKYLIGHT, TUNNEL_IRRADIANCE) near the relevant configuration.

📊 SOLID Principles Score

Principle	Score	Notes
Single Responsibility	8	Lighting, mutation, and job scheduling are cleanly separated into distinct modules.
Open/Closed	6	Adding new lighting update kinds requires editing the enum and switch in updateLighting.
Liskov Substitution	8	No new class hierarchy changes; existing RHI interfaces remain untouched.
Interface Segregation	7	MutationResult carries one unused production field (chunk_data).
Dependency Inversion	6	Streamer and lighting engine still depend on concrete mutation/storage types.
Average	7.0

🎯 Final Assessment

Overall Confidence Score: 85%

Confidence Breakdown:

• Code Quality: 85%
• Completeness: 90%
• Risk Level: 80%
• Test Coverage: 85%

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 — The PR is well-scoped, thoroughly tested, and addresses the stated lighting and rendering issues.

{
  "reviewed_sha": "026beea0052b56a84754ddb118cd20484abc69dd",
  "critical_issues": 0,
  "high_priority_issues": 0,
  "medium_priority_issues": 0,
  "overall_confidence_score": 85,
  "recommendation": "MERGE"
}

opencode session  |  github run