[MED] Add debug tooling - Chunk inspector, wireframe modes, performance overlays

[MichaelFisher1997]

Problem

The engine lacks runtime debugging tools beyond the basic timing overlay. When issues occur (rendering artifacts, performance problems, world generation bugs), developers have limited visibility into the internal state.

Current State

• Timing overlay exists (TimingOverlay)
• Environment variables for disabling features (ZIGCRAFT_DISABLE_SHADOWS, etc.)
• GPU timing queries

But missing:

• Visual chunk inspection
• Wireframe rendering modes
• Detailed performance breakdowns
• World state inspection

Proposed Solution

Add a comprehensive debug tooling system:

1. Debug Menu System

• Toggle key (e.g., F3) to open debug menu
• Hierarchical debug options

2. Chunk Inspector

• Visualize chunk boundaries
• Show chunk states (generating, meshing, renderable)
• Display chunk coordinates and distances
• Highlight dirty chunks

3. Wireframe Modes

• Toggle wireframe rendering for:
  • All geometry
  • Chunks only
  • LOD chunks only
• Visualize chunk mesh boundaries

4. Enhanced Performance Overlay

• Per-system timing (world update, rendering, UI)
• Memory usage stats (chunks, meshes, GPU memory)
• Active chunk count by state
• LOD statistics

5. Debug Visualizations

• Show frustum culling
• Display shadow cascades
• Light propagation visualization

Benefits

• Faster debugging of rendering/world issues
• Better performance profiling
• Easier to understand internal state
• Improved developer experience

Acceptance Criteria

• Debug menu accessible via hotkey
• Chunk inspector with visual boundaries
• Wireframe rendering toggle
• Enhanced performance overlay
• Document all debug features
• Tests pass with debug features enabled/disabled

Related Files

• src/engine/ui/debug_*.zig (existing debug overlays)
• src/engine/ui/ui_system.zig
• src/game/screens/world.zig
• src/world/world_renderer.zig

Estimated Effort

Medium (requires UI work and RHI integration)

[opencode-agent]

This is a Feature Request for comprehensive debug tooling.

Analysis

What's Already Implemented

Good news - some features already exist:

1. Wireframe Mode - Already implemented! Press F to toggle (bound to toggle_wireframe action)
2. Timing Overlay - TimingOverlay displays GPU pass timings (bound to F4)
3. Shadow Debug - DebugShadowOverlay shows cascade thumbnails
4. Render Stats - WorldRenderer.RenderStats already tracks chunks rendered/culled/vertices

Implementation Guidance

Chunk Inspector - Follow the TimingOverlay pattern in src/engine/ui/timing_overlay.zig:

• Add ChunkStatsOverlay struct with enabled: bool
• Draw using UISystem.drawRect() + drawText()
• Access RenderStats from WorldRenderer

Debug Menu System - Could extend existing Settings menu or create new overlay:

• Add toggle_debug_menu to GameAction enum
• Draw hierarchical menu using existing UI primitives
• Toggle individual debug features

Enhanced Performance Overlay - Extend current TimingOverlay:

• Add CPU frame timing (track in main loop)
• Add RenderDevice.getStats() for GPU memory
• Show RenderStats data (already collected)

Debug Visualizations:

• Frustum: Use wireframe_cube.zig with camera frustum corners
• Shadow cascades: Already have DebugShadowOverlay, extend for cascade visualization
• LPV: Already have DebugLPVOverlay

Scope Assessment

This issue contains 5 distinct features that could be implemented independently:

1. Debug Menu (UI framework)
2. Chunk Inspector overlay
3. Enhanced Performance overlay
4. Frustum/shadow visualizations
5. World state inspection

Consider breaking into sub-issues if work spans multiple PRs.

Questions

1. Priority order - Which debug tool is most needed first?
2. Chunk Inspector details - Should it show per-chunk data or just aggregate stats? Visual boundaries in 3D or 2D overlay?
3. Debug Menu scope - Should it be a full menu system or just cycling through overlays with hotkeys (current pattern)?

The existing infrastructure (wireframe toggle, overlay system, RenderStats) provides a solid foundation - most features can be added by following established patterns.

opencode session  |  github run