godot-procedural-generation

name	godot-procedural-generation
description	Expert blueprint for procedural content generation (dungeons, terrain, loot, levels) using FastNoiseLite, random walks, BSP trees, Wave Function Collapse, and seeded randomization. Use when creating roguelikes, sandbox games, or dynamic content. Keywords procedural, generation, FastNoiseLite, Perlin noise, BSP, drunkard walk, Wave Function Collapse, seeding.

Procedural Generation

Seeded algorithms, noise functions, and constraint propagation define replayable content generation. Do not paste inline algorithm tutorials — load the MANDATORY scripts below.

NEVER Do in Procedural Generation

• NEVER generate chunks on the Main Thread — Proc-gen is CPU intensive and causes frame-rate spikes. Use WorkerThreadPool or a background Thread to keep the UI responsive.
• NEVER query FastNoiseLite every frame — Sampling noise per frame (especially in _process) is a massive waste. Generate your map into an Image or Array once and sample from memory [NoiseSampling].
• NEVER use randi() for reproducible seeds — Always store and reuse a specific seed within your random number generator (RandomNumberGenerator.new()) to ensure consistent world generation.
• NEVER use pure randomness for object placement — Pure random (white noise) causes clumping and overlapping. Use Poisson Disk Sampling or Jittered Grids for natural-looking distributions.
• NEVER forget to bound your loops — Procedural loops (like WFC or Cellular Automata) can easily enter infinite states if constraints are impossible. Always include a max_iterations safety break.
• NEVER instantiate nodes directly from proc-gen threads — You cannot touch the SceneTree from a worker thread. Generate the data in the thread, then notify the Main Thread to handle add_child().
• NEVER use complex WFC for simple layouts — Wave Function Collapse is powerful but overkill for simple paths. Use Drunkard's Walk or BSP for lightweight structured layouts.
• NEVER rely on TileMap.set_cell() for large-scale updates — Updating 10,000 cells individually is slow. Prepare a TileMapPattern and use set_pattern() or set_cells_terrain_connect() for batch updates.
• NEVER forget to bake Navigation at the end — Procedurally generated worlds need their navmeshes rebaked at runtime or the AI will walk into walls.
• NEVER ignore data serialization — If you generate a world, you must be able to save the seed and any player modifications. Don't try to save the entire raw chunk state if avoidable.

---

Golden Path (MANDATORY)

Every generator starts here — seed isolation, async data, main-thread commit:

1. Seed & RNG — MANDATORY proc_gen_seed_history.gd: one RandomNumberGenerator per level/chunk; persist seed + state for shareable runs.
2. Async chunks — MANDATORY multi_threaded_chunk_gen.gd: WorkerThreadPool.add_task → compute data off-thread → call_deferred("_finalize_chunk") for SceneTree/node work.
3. Validate → bake nav — after tiles/meshes land on the main thread, rebake NavigationRegion (see godot-navigation-pathfinding).

var rng := RandomNumberGenerator.new()

func begin_generation(run_seed: int) -> void:
    rng.seed = run_seed
    WorkerThreadPool.add_task(_build_data.bind(run_seed))

func _build_data(seed: int) -> Dictionary:
    var local_rng := RandomNumberGenerator.new()
    local_rng.seed = seed
    var noise := FastNoiseLite.new()
    noise.seed = seed
    return {"heights": noise.get_image(64, 64)}

func _ready() -> void:
    # Worker returns here — safe for nodes
    pass

func _finalize_from_worker(data: Dictionary) -> void:
    # add_child / set_pattern / create_trimesh_collision — main thread only
    pass

Do NOT Load the full scripts/ folder. Open only the script that matches your algorithm row below.

Algorithm Decision Tree

Layout / content need	Algorithm	Script (MANDATORY when chosen)
Winding tunnels, rivers, simple paths	Drunkard's Walk	MANDATORY drunknard_walk_path.gd
Structured rooms + hallways	BSP	MANDATORY bsp_tree_rooms.gd
Organic caves / smooth terrain	Cellular Automata (4/5)	MANDATORY cellular_automata_dungeon.gd
Heightmaps, biomes, infinite terrain	FastNoiseLite → Image	MANDATORY fast_noise_noise2d_master.gd
Trees, rocks, spawns (no clumping)	Poisson Disk	MANDATORY poisson_disk_sampling_2d.gd
Tile adjacency / city blocks	Wave Function Collapse	MANDATORY wave_function_collapse_lite.gd (lite) or wfc_level_generator.gd (full rules)
Room graph before geometry	AStar graph layout	MANDATORY proc_gen_graph_layout.gd
3D voxel / smooth terrain mesh	Marching Cubes base	MANDATORY proc_gen_marching_cubes_base.gd
Infinite chunked 3D terrain	ArrayMesh + LOD chunks	MANDATORY mesh_gen_infinite_terrain.gd
Plants / branching structures	L-System	MANDATORY l_system_tree_gen.gd
Contour / metaball maps (2D)	Marching Squares	MANDATORY marching_squares_metaballs.gd

Routing hints: Simple path → drunkard; rectangular rooms → BSP; constraint tiles → WFC lite; open-world chunks → noise + multi_threaded_chunk_gen.gd. For roguelike run orchestration, hand off to godot-genre-roguelike.

Available Scripts

Core (always start here)

• proc_gen_seed_history.gd — MANDATORY seeded RandomNumberGenerator with push/pop state history
• multi_threaded_chunk_gen.gd — MANDATORY WorkerThreadPool → call_deferred chunk finalize pattern

2D layout & placement

• drunknard_walk_path.gd — MANDATORY for tunnels/paths (pass local RNG, never global randi())
• bsp_tree_rooms.gd — MANDATORY for structured floor plans
• cellular_automata_dungeon.gd — MANDATORY for organic caves
• poisson_disk_sampling_2d.gd — MANDATORY for blue-noise prop/enemy placement
• wave_function_collapse_lite.gd — MANDATORY lite WFC with entropy + max_iterations
• wfc_level_generator.gd — full WFC with tile-library adjacency rules
• proc_gen_graph_layout.gd — graph-before-geometry via AStar2D/3D

Noise & 3D

• fast_noise_noise2d_master.gd — MANDATORY FastNoiseLite → Image heightmaps
• mesh_gen_infinite_terrain.gd — runtime ArrayMesh terrain with LOD potential
• proc_gen_marching_cubes_base.gd — 3D mesh from voxel data
• marching_squares_metaballs.gd — 2D contour extraction
• l_system_tree_gen.gd — procedural plant/tree grammar

Expert Procedural Patterns

1. 3D Terrain via ArrayMesh (Marching Cubes)

For voxel-like or smooth organic terrain, use ArrayMesh to generate geometry from code.

• Logic: Calculate vertices, normals, and indices in a worker thread.
• Commit: Use add_surface_from_arrays(Mesh.PRIMITIVE_TRIANGLES, arrays) to create the mesh.
• Performance: Use create_trimesh_collision() only for the current chunk to keep physics updates fast.

2. Graph-Based Dungeon Logic

Don't generate your dungeon geometry first. Build a logical graph using AStar2D.

• Vertices: Represent "Rooms".
• Edges: Represent "Hallways" or "Doors".
• Benefit: You can easily run validation (is every room reachable?) before spawning a single mesh.

Deep dive (load on demand)

Drunkard walk, noise biomes, BSP, loot tables, WFC loops — references/algorithm-recipes.md.

Reference

Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• FastNoiseLite — seed, frequency, noise type, and get_image()/get_noise_2d() for heightmaps and biome masks.
• Random number generation — why per-generator RandomNumberGenerator seeds beat global randi() for shareable runs.
• RandomNumberGenerator — seed/state APIs for deterministic sequences and undoable RNG history.
• Using multiple threads — offload chunk/WFC work without freezing the main loop.
• Thread-safe APIs — which Godot APIs workers may call; SceneTree/node creation stays on the main thread.
• WorkerThreadPool — add_task + call_deferred finalize pattern for async chunk generation.
• Using ArrayMesh — commit vertex/normal/index arrays for marching-cubes and infinite terrain meshes.
• Using SurfaceTool — incremental vertex building and normal generation for runtime planes.
• Using TileMaps — TileMapLayer/pattern batch writes after BSP, CA, WFC, or drunkard-walk grids.
• Using GridMaps — modular 3D cell placement backend for dungeon/terrain generators.
• Navigation introduction (3D) — rebake NavigationRegion meshes after procedural geometry lands.
• AStar2D — room/hallway graph validation before spawning tiles or meshes.

Related Skills

Prerequisites

• godot-project-foundations — scenes, resources, and import basics before generators emit TileMaps, GridMaps, or ArrayMeshes.
• godot-gdscript-mastery — typed arrays, call_deferred, and WorkerThreadPool task patterns used across every generator script.
• godot-resource-data-patterns — Resource-backed tile libraries, adjacency rules, and seed configs instead of hard-coded magic tables.

Complements

• godot-tilemap-mastery — set_pattern / terrain connect batching so large CA/WFC grids do not call set_cell per tile.
• godot-3d-world-building — GridMap/MeshLibrary/CSG placement backends that consume room graphs and heightmaps.
• godot-navigation-pathfinding — runtime navmesh bake after rooms, caves, or terrain chunks finish.
• godot-performance-optimization — budgets for mesh commits, collision trimeshes, and MultiMesh prop scattering after generation.
• godot-save-load-systems — persist seed + player deltas instead of serializing every generated chunk.
• godot-scene-management — threaded load/unload of chunk scenes that wrap generated data.
• godot-monte-carlo-balancer — sample spawn density, loot tables, and room difficulty against seed distributions before shipping.

Downstream / consumers

• godot-genre-roguelike — run-based dungeon crawlers that consume BSP/WFC/drunkard generators and seeded RNG.
• godot-genre-sandbox — voxel/chunk worlds and cellular-automata sandboxes built on infinite terrain and CA scripts.
• godot-genre-open-world — chunk streaming and floating-origin layers that wrap multi-threaded chunk gen.

Master

• godot-master — library router and mirrored module entry for cross-skill discovery.