Worldgen Phase 3: add visual and debug snapshots for worldgen tuning

[MichaelFisher1997]

Parent: #646

Phase

Phase 3: Compatibility and tuning

Goal

Add reproducible debug outputs that make worldgen tuning reviewable.

Tasks

• Add or document a way to capture biome/height/climate snapshots for fixed seeds.
• Include temperature, humidity, continentalness, erosion/ruggedness, and biome ID views if practical.
• Prefer headless/offscreen workflows where screenshots are needed.
• Store outputs outside source control unless explicitly intended as fixtures.

Acceptance Criteria

• Reviewers can compare before/after worldgen behavior for fixed seeds.
• Debug outputs do not require a visible game window.
• Snapshot workflow is documented.

Dependencies

• Can start after baseline report direction is known.

Parallelization

Can run in parallel with Phase 3 tuning tasks.

[github-actions]

Based on my exploration, this is a Feature Request for debug/tuning infrastructure.

Analysis:

The codebase has good foundation for this, but lacks explicit climate snapshot tooling:

Existing capabilities:

• WorldMap (modules/world-worldgen/src/world_map.zig) renders top-down biome color visualization
• BiomeColorProvider provides biome RGB colors
• Headless screenshot system exists (modules/engine-graphics/src/vulkan/screenshot.zig)
• Build flags like -Dskip-present, -Dsmoke-test, -Dstartup-diagnostic-seconds support headless workflows
• Seed determinism is already tested and guaranteed
• ClassificationCache in gen_region.zig caches climate data per-cell

What's missing for this issue:

1. No dedicated snapshot format for intermediate climate values (temperature/humidity/continentalness/erosion/ruggedness grids)
2. No existing module to export these as data files (JSON, binary) or visual heatmaps
3. No documented workflow for reproducible tuning review
4. WorldMap renders biome colors only, not the underlying climate space views

Suggested implementation approach (not implementing):

1. Create a WorldGenSnapshot module in world-worldgen/ that:

   • Exposes functions to sample climate grids at given world coordinates for a fixed seed
   • Renders false-color heatmaps (like biome ID view, temperature view, etc.) as 2D textures
   • Outputs to configurable path (outside source control)

2. Leverage existing NoiseSampler and ClimateParams structs - they're already computed per-column

3. Document headless workflow: use -Dskip-present -Dstartup-diagnostic-seconds=N to run headless, capture via snapshot module before exit

Scope assessment: This is appropriately scoped - single subsystem focus on debug visualization tooling. One implementation PR should suffice.

Dependencies note: No blocking dependencies identified. Existing headless infrastructure and deterministic seeding provide the necessary foundation.

opencode session  |  github run