[HIGH] Refactor shadow architecture: decouple visual LOD from shadow casters

[MichaelFisher1997]

Problem

Visual terrain LOD behavior and shadow casting are still coupled enough to cause instability/artifacts under streaming and low sun angles.

Goal

Refactor shadow casting so it is independent from visual LOD seam/offset logic, with clear ownership boundaries and explicit policy configuration.

Scope

• Introduce a dedicated shadow-caster source path (chunk-only or shadow-LOD representation).
• Remove reliance on visual-only mesh adjustments for shadow pass behavior.
• Clarify shadow policy inputs in uniforms/config (avoid overloaded cloud/shader params).
• Add targeted debug channels for CSM/cascade index/caster coverage diagnostics.

Acceptance Criteria

• Shadow caster set is explicit and testable.
• No detached/morphing artifacts caused by visual LOD offsets in shadow pass.
• Stable behavior across streaming boundaries.
• Shadow controls map 1:1 from settings to shader/runtime behavior.

Dependencies / Order

• Depends on [HIGH] Stabilize sun shadows on LOW preset (camera-angle morphing) #278 and should be done after [HIGH] Stabilize sun shadows on LOW preset (camera-angle morphing) #278 (baseline stability first).

Related Issues

• [HIGH] Simplify RHI composite - Split into focused subsystem interfaces #272 Simplify RHI composite
• [HIGH] Decompose World struct - Separate streaming, rendering, and LOD concerns #273 Decompose World struct
• [MED] Add debug tooling - Chunk inspector, wireframe modes, performance overlays #275 Add debug tooling
• Refactor lod_manager.zig - Separate LOD Logic from GPU Operations #246 LOD manager GPU decoupling (completed precursor)
• Shadow System Refactoring: SOLID Violations & Monolithic VulkanContext #174 Shadow system refactor (historical context)

[opencode-agent]

Based on my analysis of the codebase, here's my assessment:

Classification

Type: Feature Request / Architecture Refactoring (HIGH priority)

Issue Scope Assessment

This is a well-defined but broad refactoring that should be broken down into sub-issues. The scope spans multiple subsystems:

• Graphics/Shadow System - CSM computation, shadow passes
• World/LOD System - LOD chunks, streaming boundaries
• Settings/Configuration - Shadow policy, uniforms
• Debug Tooling - Visualization channels

Key Code Pointers (Current Coupling)

1. Shared render path (src/world/world_renderer.zig:181-241):

   • Both render() and renderShadowPass() call lod_mgr.render() with identical frustum culling
   • Same render distance clamping: @min(render_distance, mgr.config.getRadii()[0])

2. Settings coupling (src/game/settings/data.zig:41-50):

   • shadow_distance: f32 = 250.0 affects cascade far plane
   • lod_enabled: bool gates LOD in shadow pass
   • No dedicated shadow-LOD distance configuration

3. CSM computation (src/engine/graphics/csm.zig:59):

   • Uses shadow_dist parameter directly for cascade splits
   • LOD chunks (up to 160 chunks for LOD3) can extend far beyond shadow coverage (~16 chunks at default 250m)

4. World-level integration (src/world/world.zig:290-292):

   • renderShadowPass() conditionally passes lod_manager based on lod_enabled
   • No explicit shadow-caster configuration separate from visual LOD

Recommendation: Break into Sub-Issues

This work should be split into 4 focused sub-issues:

1. #XXX-A: Shadow Caster Source Path - Create dedicated chunk-only or shadow-LOD representation, independent from visual LOD mesh generation

2. #XXX-B: Visual LOD Decoupling - Remove lod_mgr.render() calls from shadow pass; implement separate shadow-caster culling/distance logic

3. #XXX-C: Policy Configuration - Add explicit shadow_caster_distance, shadow_lod_bias settings; clean up uniform parameter overloading

4. #XXX-D: Debug Tooling - Add CSM cascade index visualization, caster coverage overlay, and seam/offset debug channels

Missing Information Needed

To better prioritize and validate fixes:

• Screenshots/descriptions of specific artifacts at low sun angles
• Reproduction steps for streaming boundary instability
• Performance targets - What's the desired shadow caster count vs visual LOD count?

Dependency on #278 noted and appropriate - this should wait for baseline stability before refactoring core rendering paths.

opencode session  |  github run