Verbatim/WORLDGEN_PLAN.md

World Generator Plan

Goal

Procedural world generation with depth-based biomes, rooms, corridors, and randomized features.

Current State

• Implemented in src/world/worldgen.rs
• Depth-based dispatch: surface (1-3), caves (4-6), BSP dungeon (7+)
• Randomized features, pools, trees, walls, rooms, corridors, traps
• World size: 2048x2048 for main game; 250x250 for tests/AI
• Seed-based generation with Game::seed
• Per-chunk world cache in cache/worlds/<seed>/depth_<N>/
• Tests in tests/worldgen.rs and tests/large_world.rs (ignored, slow)

Algorithms Researched

BSP (Binary Space Partitioning)

• Recursively divide space into rectangles
• Place room in each leaf node
• Connect siblings with corridors
• Guarantees no overlaps
• Use for: dungeon rooms (depth 7+)

Cellular Automata (4-5 rule)

• Fill grid with ~45% random walls
• 5 iterations: wall if >=4 neighbors are walls, else empty
• Produces organic cave shapes
• Flood fill to verify connectivity
• Use for: caves (depth 4-6, and underground at depth 1-3)

Drunkard's Walk

• Random walk digs tunnels through solid rock
• Creates winding cave-like paths
• Use for: tunnels connecting rooms

Brogue Room Accretion

• Start with one room, attach new rooms to existing structure
• Inherently connected (tree structure)
• Room templates: rectangle, CA blob, circle
• Use for: room placement strategy

Rooms and Mazes (Bob Nystrom)

• Place rooms → fill gaps with maze → connect → remove dead ends
• Inspirational, not directly used

Noita — Herringbone Wang Tiles

• Pre-made chunks laid in herringbone pattern
• Randomized contents within chunks
• Too complex for now, possible future enhancement

Architecture

New module: src/world/worldgen.rs

WorldGenerator
├── rng: &mut CellularAutomaton
├── generate(grid, depth)              — main entry point
├── generate_surface(grid, depth)      — depth 1-3: terrain + caves + features
├── generate_caves(grid, depth)        — depth 4-6: full underground caves
├── generate_dungeon(grid, depth)      — depth 7+: BSP rooms + corridors
│
├── Surface sub-methods:
│   ├── terrain_noise(x, depth)        — multi-octave surface height
│   ├── fill_terrain(grid, depth)      — fill dirt/stone/grass by depth
│   ├── carve_underground_caves(grid)  — CA caves below surface
│   ├── place_trees(grid, count)       — random tree placement
│   ├── place_pools(grid, count, types)— random liquid pools
│   ├── place_sand_dunes(grid, count)  — sand piles
│   └── place_walls(grid, count)       — stone wall obstacles
│
├── Cave sub-methods:
│   ├── ca_caves(grid, fill_prob, iterations) — cellular automata
│   ├── flood_fill_largest(grid)       — find largest connected region
│   ├── seal_small_regions(grid)       — fill disconnected caves
│   └── place_underground_pools(grid)  — lava/acid in caves
│
├── Dungeon sub-methods:
│   ├── bsp_split(rect, depth)         — recursive space partitioning
│   ├── place_room(grid, rect)         — carve room interior
│   ├── connect_rooms(grid, rooms)     — L-shaped corridors
│   ├── place_doors(grid, rooms)       — door at room entrances
│   └── place_traps(grid, rooms)       — acid/fire traps in rooms
│
└── Shared:
    ├── place_stairs(grid, depth)      — stairs in appropriate location
    └── place_items(game, rooms)       — items in rooms/on surface

Depth-based Generation

Depth	Type	Surface	Features	Algorithm
1-3	Surface	Grass/dirt	Trees, water pools, sand dunes, stone walls, underground CA caves	Multi-octave noise + CA
4-6	Caves	Stone/dirt	Large CA caves, lava pools, acid pools, stalactites	Cellular automata (4-5 rule)
7+	Dungeon	Stone	BSP rooms (5x3 to 12x8), corridors, traps, stairs	BSP + corridor connection

Implementation Details

Surface terrain (depth 1-3)

• Multi-octave sine noise: base + detail + micro
• Amplitude: 4-8 cells variation
• Surface material: grass at depth 1, dirt at 2-3
• Below surface: dirt for 8 cells, then stone
• Border: stone walls

CA cave generation (depth 4-6)

1. Fill entire grid with stone
2. Random fill ~45% as empty (cave candidate)
3. Run 5 iterations of 4-5 rule:
   • Cell becomes wall if >=4 of 8 neighbors are walls
   • Cell becomes empty if <4 neighbors are walls
4. Flood fill from center, find largest connected region
5. Seal all cells not in largest region (fill with stone)
6. Place lava/acid pools in random empty areas
7. Place stalactites (stone pillars) in random positions

BSP dungeon (depth 7+)

1. Start with full grid as stone
2. Recursively split into 2 halves (alternate H/V)
3. Stop when area < min_room_size (15x10)
4. In each leaf: place room (smaller than partition, centered)
5. Connect sibling rooms with L-shaped corridor (2 wide)
6. Place stairs in the deepest/farthest room
7. Place items in 2-3 random rooms
8. Place traps (acid pockets) in 1-2 rooms

Feature placement (all depths)

• All positions via RNG, not hardcoded
• Pool count: 2 + depth/2
• Pool radius: 4-10 cells
• Pool types by depth:
  • 1-3: water, sand
  • 4-6: lava, acid, water
  • 7+: acid (traps in rooms)
• Tree count: 3-7 (surface only)
• Wall count: 1-3 (surface only)

Files

File	Change
src/world/worldgen.rs	New module — all generation logic
src/world/mod.rs	Add pub mod worldgen
src/game.rs	init_world() calls WorldGenerator::generate()
tests/worldgen.rs	New tests

Tests

• Stairs exist after generation at any depth
• At least 3 distinct materials present
• Player spawn position is not inside solid
• Different depths produce different structures
• Depth 7+ has rooms (empty regions > 5x3)
• CA caves are connected (flood fill test)

Implementation Order

1. Create worldgen.rs with WorldGenerator struct and generate() dispatch
2. Implement surface generation (depth 1-3) — move existing code, add RNG
3. Implement CA cave generation (depth 4-6)
4. Implement BSP dungeon generation (depth 7+)
5. Integrate into game.rs::init_world()
6. Write tests
7. Run all tests + scenarios
8. Push