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.setcell() for large-scale updates — Updating 10,000 cells individually is slow. Prepare a TileMapPattern and use setpattern() or setcellsterrain_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 [procgenseedhistory.gd](scripts/procgenseedhistory.gd): one RandomNumberGenerator per level/chunk; persist seed + state for shareable runs.
2. Async chunks — MANDATORY [multithreadedchunkgen.gd](scripts/multithreadedchunkgen.gd): WorkerThreadPool.addtask → compute data off-thread → calldeferred("finalizechunk") 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

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

Available Scripts

Core (always start here)

• [procgenseedhistory.gd](scripts/procgenseedhistory.gd) — MANDATORY seeded RandomNumberGenerator with push/pop state history
• [multithreadedchunkgen.gd](scripts/multithreadedchunkgen.gd) — MANDATORY WorkerThreadPool → call_deferred chunk finalize pattern

2D layout & placement

• [drunknardwalkpath.gd](scripts/drunknardwalkpath.gd) — MANDATORY for tunnels/paths (pass local RNG, never global randi())
• [bsptreerooms.gd](scripts/bsptreerooms.gd) — MANDATORY for structured floor plans
• [cellularautomatadungeon.gd](scripts/cellularautomatadungeon.gd) — MANDATORY for organic caves
• [poissondisksampling2d.gd](scripts/poissondisksampling2d.gd) — MANDATORY for blue-noise prop/enemy placement
• [wavefunctioncollapselite.gd](scripts/wavefunctioncollapselite.gd) — MANDATORY lite WFC with entropy + max_iterations
• [wfclevelgenerator.gd](scripts/wfclevelgenerator.gd) — full WFC with tile-library adjacency rules
• [procgengraphlayout.gd](scripts/procgengraphlayout.gd) — graph-before-geometry via AStar2D/3D

Noise & 3D

• [fastnoisenoise2dmaster.gd](scripts/fastnoisenoise2dmaster.gd) — MANDATORY FastNoiseLite → Image heightmaps
• [meshgeninfiniteterrain.gd](scripts/meshgeninfiniteterrain.gd) — runtime ArrayMesh terrain with LOD potential
• [procgenmarchingcubesbase.gd](scripts/procgenmarchingcubesbase.gd) — 3D mesh from voxel data
• [marchingsquaresmetaballs.gd](scripts/marchingsquaresmetaballs.gd) — 2D contour extraction
• [lsystemtreegen.gd](scripts/lsystemtreegen.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 addsurfacefromarrays(Mesh.PRIMITIVETRIANGLES, arrays) to create the mesh.
• Performance: Use createtrimeshcollision() 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](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 getimage()/getnoise2d() 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 — addtask + 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 — setpattern / terrain connect batching so large CA/WFC grids do not call setcell 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.