Phase 6: add LOD quality controls and diagnostics

[MichaelFisher1997]

Goal

Expose practical quality controls and diagnostics for tuning the improved LOD pipeline.

Work Items

• Add quality presets for render radius, horizontal detail, vertical span budget, fade mode, and cache budget.
• Add developer diagnostics for LOD queue state, cache hit rate, mesh counts, visible regions, and fallback reasons.
• Add runtime toggles for old/new mesh paths while the implementation stabilizes.
• Document recommended default settings and performance tradeoffs.
• Keep settings small and understandable; avoid exposing unstable internals.

Acceptance Criteria

• Users can tune distance LOD quality without code changes.
• Debug output makes common LOD quality/performance issues diagnosable.
• Defaults preserve current performance expectations unless explicitly changed.
• zig build test passes.

[github-actions]

Based on my analysis, here's my assessment:

Classification: Feature Request

Issue Summary: Phase 6 requests exposing quality controls and diagnostics for the LOD pipeline. The work items cover: quality presets (render radius, horizontal detail, vertical span budget, fade mode, cache budget), developer diagnostics (queue state, cache hit rate, mesh counts, visible regions, fallback reasons), runtime toggles for old/new mesh paths, and documentation.

Existing Foundation:

• RenderDistancePresetConfig (engine-rhi/src/render_settings.zig:26-36) already exposes LOD radii, fog start percent, QEM triangle targets, memory budget, upload limits, and skip_cutout/skip_lighting flags across 5 presets
• LODStats (modules/world-lod/src/lod_stats.zig) tracks loaded/generating/meshing counts per LOD level plus memory usage
• Environment-gated diagnostics exist via ZIGCRAFT_LOD_DIAG in scheduler and renderer

Gaps Identified:

1. Cache hit rate - no tracking mechanism exists in LODManager or LODRenderer
2. Queue state diagnostics - current LODStats lacks per-frame queue depth, wait counts, fallback reasons
3. Horizontal detail / vertical span budget - not exposed as independent tuning knobs; QEM targets exist but no grid resolution control
4. Runtime mesh path toggle - no flag for switching between buildFromSimplifiedData() and buildFromSimplifiedDataWithQEM()
5. Visible region / fallback tracking - renderer has isCoveredByFinerLOD and isCoveredByChunks but no aggregated diagnostics

Scope Assessment: The request is moderately scoped but crosses multiple areas:

• New controls in render_settings.zig and possibly lod_chunk.zig
• Extended diagnostics in lod_stats.zig and logging points
• Runtime toggle logic in lod_mesh.zig
• Documentation in code comments or a separate doc

Recommendation: This can proceed as a single feature PR, but consider splitting into two sub-issues: (1) implementation of controls + diagnostics, (2) documentation of performance tradeoffs.

Would you like me to elaborate on any specific gap or suggest concrete implementation approaches for the missing diagnostics?

opencode session  |  github run