TerrainForge

TerrainForge Showcase

A comprehensive Rust library for procedural terrain and dungeon generation with semantic analysis capabilities.

Crates.io: https://crates.io/crates/terrain-forge

Features

15 Generation Algorithms: BSP, Cellular Automata, WFC, Delaunay Triangulation, Glass Seam Bridging, Noise Fill, and more
Thread-safe: Algorithm trait is Send + Sync — generate on any thread
Serializable configs: All algorithm configs implement Serialize/Deserialize
Spatial Analysis: Distance transforms, pathfinding, morphological operations
Semantic Layers: Game-agnostic metadata for entity spawning and region analysis
Advanced Prefab System: JSON support with transformations
Requirements System: Generate maps meeting specific constraints
Connectivity Utilities: Shortest-path extraction, path carving, marker connections
Grid utilities: Flood fill, region labeling, neighbor queries, line drawing built into Grid

Quick Start

[dependencies]
terrain-forge = "0.7"

use terrain_forge::{Grid, ops};

fn main() {
    let mut grid = Grid::new(80, 60);
    ops::generate("bsp", &mut grid, Some(12345), None).unwrap();
    println!("Generated {} floor tiles", grid.count(|t| t.is_floor()));
}

Novel Algorithm: Glass Seam Bridging

The Glass Seam Bridging Algorithm is a novel connectivity algorithm designed specifically for TerrainForge. It ensures map connectivity by finding the optimal set of tunnels to connect disconnected floor regions while minimizing total tunnel length.

📄 Read the full algorithm specification
📄 Download the research paper (PDF)

Key features:

Perimeter Gradient Descent (PGD) optimization for optimal tunnel endpoints
Edge pruning pipeline with Delaunay triangulation, angular sector, and occlusion filters
Multi-terminal support for connecting spawn points, exits, and POIs
Configurable optimization profiles from real-time to quality-focused generation

Connectivity Demonstration

Before GSB	After GSB

97 disconnected regions (highly fragmented)	23 connected regions (76% reduction)
0.21 connectivity • 29.1% floors	0.78 connectivity • 31.2% floors

Color-coded semantic analysis showing dramatic connectivity improvement (+0.57 connectivity, +2.1% floors) on cellular automata caves (160×120 grid)

Algorithms

Algorithm	Description	Semantic Support
`bsp`	Binary Space Partitioning - structured rooms	✅ `for_rooms()`
`cellular`	Cellular Automata - organic caves	✅ `for_caves()`
`dla`	Diffusion Limited Aggregation	✅ `default()`
`drunkard`	Drunkard Walk - winding passages	✅ `default()`
`maze`	Perfect maze generation	✅ `for_mazes()`
`rooms`	Simple room placement	✅ `for_rooms()`
`voronoi`	Voronoi diagram regions	✅ `default()`
`wfc`	Wave Function Collapse	✅ `default()`
`percolation`	Physics-based generation	✅ `default()`
`diamond_square`	Fractal heightmaps	✅ `default()`
`fractal`	Fractal terrain	✅ `default()`
`noise_fill`	Noise-driven threshold fill	✅ `default()`
`agent`	Multi-agent carving	✅ `default()`
`glass_seam`	Region connector	✅ `default()`
`room_accretion`	Brogue-style organic dungeons	✅ `for_rooms()`

Documentation

Usage Guide - Comprehensive examples and API documentation
Patch Notes - Detailed version history and changes
API Documentation - Complete API reference

Version History

v0.7.0 - Code quality, thread safety, serialization, bug fixes, performance
v0.6.0 - Unified ops facade, pipeline model, NoiseFill expansion
v0.4.0 - Spatial Analysis & Quality of Life improvements
v0.3.0 - Semantic Layers and Requirements System
v0.2.0 - Advanced Algorithms (WFC, Percolation, Fractal)
v0.1.0 - Foundation with core algorithms and grid system

Demo Framework

# Generate basic terrain
cargo run --bin demo -- gen bsp -s 12345 -o output.png

# Semantic generation with visualization
cargo run --bin demo -- gen room_accretion --semantic --text -o semantic.txt

# Compare algorithms
cargo run --bin demo -- compare bsp cellular maze -s 12345

License

Licensed under the MIT License. See LICENSE for details.

terrain-forge 0.7.0