Worldgen Phase 3: retune biome adjacency and transition bands

[MichaelFisher1997]

Parent: #646

Phase

Phase 3: Compatibility and tuning

Goal

Revisit biome edge/transition rules after terrain modifiers and multi-parameter selection change biome distribution.

Tasks

• Review TRANSITION_RULES for missing or obsolete pairs.
• Tune transition band widths and detection thresholds if needed.
• Ensure harsh biome boundaries still get appropriate buffer biomes.
• Add tests for important transition pairs.

Acceptance Criteria

• Desert/forest, cold/temperate, mountain/lowland, wetland/forest, and ocean/coast transitions remain natural.
• Transition micro-biomes appear near boundaries, not as dominant regions.

Dependencies

• Should follow initial Phase 2 migration.

Parallelization

Can run in parallel with region-role validation and debug snapshot work.

[github-actions]

Based on the codebase exploration, here's my analysis as a comment on the issue:

---

Analysis: Biome Adjacency and Transition Bands (Phase 3)

Current Implementation State

The transition system is well-structured in modules/world-worldgen/src/biome_edge_detector.zig:

• TRANSITION_RULES (lines 42–108): Defines 30+ biome pairs requiring transitions
• EDGE_CHECK_RADII = [4, 8, 12]: Edge detection samples at 3 radii, mapping to inner/middle/outer bands
• EDGE_WIDTH = 8 blocks: Target transition band width
• Blend factors: inner=0.3, middle=0.2, outer=0.1

Potential Gaps Found

1. Missing transition pairs: The rules cover hot↔temperate and cold↔temperate, but some neighbor pairs may be absent:

   • savanna ↔ desert (two hot/dry biomes meeting — is a transition biome needed?)
   • old_growth_taiga ↔ dark_forest (no direct rule)
   • eroded_badlands ↔ forest (only plains→dry_plains exists, not forest)
   • wooded_badlands ↔ plains (missing, only forest→dry_plains)

2. No tests for biome_edge_detector.zig: The module has zero test coverage despite being critical for boundary naturalness. All other worldgen modules (biome_registry, biome_selector, terrain_shape_generator) have tests.

3. Edge detection is player-distance-gated (player_dist_sq < 256 * 256): Distant chunks never get transition biomes injected, which could cause harsh-looking boundaries for far LOD chunks.

Recommendations for Sub-Tasks

1. Audit TRANSITION_RULES completeness — Compare against all BiomeId pair combinations that can legally border each other in the Voronoi space
2. Add biome_edge_detector tests — Cover needsTransition, getTransitionBiome, and edge band classification at minimum
3. Evaluate EDGE_WIDTH tuning — 8-block width may be too narrow/wide for some biomes; consider making it per-transition-pair configurable
4. Check for obsolete rules — After Phase 2 terrain modifier changes, verify no rules produce illogical transitions

Related Code Pointers

• Transition rules: modules/world-worldgen/src/biome_edge_detector.zig:42–108
• Edge detection logic: modules/world-worldgen/src/biome_edge_detector.zig:111–132
• Edge injection in chunk prep: modules/world-worldgen/src/terrain_shape_generator.zig:276–317
• Transition micro-biomes (edge-only): modules/world-worldgen/src/biome_registry.zig:907–973

---

opencode session  |  github run