# TerrainForge Demo Framework
## Overview
The TerrainForge demo framework is a standalone CLI tool for visualizing and testing procedural generation algorithms. Located in `demo/`, it serves as both a testing harness and example of how to use TerrainForge in real applications.
## Architecture
The demo framework is implemented as a separate Rust crate that depends on TerrainForge, mimicking how end users would integrate the library. This ensures the public API remains clean and usable.
```
demo/
├── Cargo.toml # Separate crate depending on terrain-forge
├── manifest.toml # Manifest of demos/runs (semantic, png, hires, showcase)
├── scripts/demo.sh # Manifest-driven runner
├── src/
│ ├── main.rs # CLI entry point with clap
│ ├── config.rs # JSON config parsing and algorithm building
│ ├── render.rs # PNG and text output
│ └── manifest.rs # Manifest loading helpers
├── configs/ # Saved configuration files
└── output/ # Generated assets grouped by demo id
```
## Usage
### Command Line Interface
```bash
# Generate single algorithm
cargo run -- gen bsp -s 12345
# Run saved configuration
cargo run -- run configs/brogue_style.json
# Compare multiple algorithms
cargo run -- compare bsp cellular room_accretion
# List manifest demos / run a subset
./scripts/demo.sh --list
./scripts/demo.sh semantic
./scripts/demo.sh png --run cellular_views
```
### Output Formats
- **PNG**: Grayscale images (floor=light, wall=dark)
- **Text**: ASCII representation for terminal viewing
- **Metrics**: Connectivity, density, generation time
## Configuration System
The framework uses JSON configurations that map directly to TerrainForge's API structures.
### Basic Algorithm
```json
{
"name": "simple_bsp",
"width": 80,
"height": 60,
"seed": 12345,
"algorithm": "bsp"
}
```
### Algorithm with Parameters
```json
{
"name": "organic_caves",
"algorithm": {
"type": "cellular",
"initial_floor_chance": 0.45,
"iterations": 5,
"birth_limit": 5,
"death_limit": 4
}
}
```
### Room Accretion (Brogue-style)
```json
{
"name": "brogue_dungeon",
"algorithm": {
"type": "room_accretion",
"templates": [
{ "Rectangle": { "min": 5, "max": 12 } },
{ "Circle": { "min_radius": 3, "max_radius": 8 } },
{ "Blob": { "size": 10, "smoothing": 2 } }
],
"max_rooms": 15,
"loop_chance": 0.15
}
}
```
### Pipeline Composition
```json
{
"name": "rooms_then_smooth",
"pipeline": [
"rooms",
{ "type": "cellular", "iterations": 2 }
]
}
```
### Layered Generation
```json
{
"name": "cave_network",
"layers": [
{ "algorithm": "cellular", "blend": "replace" },
{ "algorithm": "drunkard", "blend": "union" }
]
}
```
### Effects Processing
```json
{
"name": "connected_regions",
"algorithm": "rooms",
"effects": [
{
"name": "connect_regions_spanning",
"config": {
"extra_connection_chance": 0.2
}
},
"remove_dead_ends"
]
}
```
### Prefab Rotation
```json
{
"name": "rotated_prefabs",
"algorithm": {
"type": "prefab",
"library_path": "prefab_library.json",
"tags": ["room"],
"placement_mode": "overwrite",
"allow_rotation": true,
"max_prefabs": 5
}
}
```
## Implementation Details
### Config Parser
The `config.rs` module handles JSON deserialization and algorithm construction:
```rust
#[derive(Deserialize)]
pub struct Config {
pub name: Option<String>,
pub width: usize,
pub height: usize,
pub seed: Option<u64>,
// Generation (one of these)
pub algorithm: Option<AlgorithmSpec>,
pub pipeline: Option<Vec<AlgorithmSpec>>,
pub layers: Option<Vec<LayerSpec>>,
// Post-processing
pub effects: Vec<EffectSpec>,
}
#[derive(Deserialize)]
#[serde(untagged)]
pub enum AlgorithmSpec {
Name(String),
WithParams {
#[serde(rename = "type")]
type_name: String,
#[serde(flatten)]
params: HashMap<String, serde_json::Value>,
},
}
```
### Algorithm Building
The framework dynamically constructs algorithm instances based on JSON configuration:
```rust
fn build_algorithm(spec: &AlgorithmSpec) -> Box<dyn Algorithm<Tile>> {
match spec {
AlgorithmSpec::Name(name) => ops::build_algorithm(name, None).unwrap(),
AlgorithmSpec::WithParams { type_name, params } => {
ops::build_algorithm(type_name, Some(params)).unwrap()
}
}
}
```
### Effects System
Effects are applied sequentially after generation:
```rust
use terrain_forge::ops;
fn apply_effects(grid: &mut Grid<Tile>, effects: &[EffectSpec], rng: &mut Rng) {
for effect in effects {
let result = match effect {
EffectSpec::Simple(name) => ops::effect(name, grid, None, None),
EffectSpec::WithConfig { name, config } => {
ops::effect(name, grid, Some(config), None)
}
};
if let Err(err) = result {
eprintln!("{}", err);
}
}
}
```
## Test Suite
Use the manifest runner to regenerate demo outputs for quick regression coverage:
```bash
./scripts/demo.sh --list
./scripts/demo.sh semantic
./scripts/demo.sh png
./scripts/demo.sh showcase
```
For deeper validation, run targeted configs directly with `cargo run -- run <config>`, or add a dedicated QA demo block to `manifest.toml`.
## Validation System
Configs can include validation constraints:
```json
{
"validate": {
"connectivity": 0.8, // Minimum connected floor percentage
"density": [0.3, 0.6], // Floor density range
"regions": [1, 5] // Number of disconnected regions
}
}
```
The framework reports validation results and can fail builds on constraint violations.
## Current Capabilities
The demo framework fully supports all TerrainForge v0.2.0 features:
### Algorithms (14 total)
- Basic: `bsp`, `cellular`, `drunkard`, `maze`, `rooms`
- Advanced: `room_accretion`, `voronoi`, `dla`, `wfc`, `agent`
- Terrain: `diamond_square`, `fractal`
- Utility: `glass_seam`, `percolation`
### Composition
- **Pipeline**: Sequential algorithm chaining
- **Layers**: Parallel generation with blend modes (replace, union, intersect)
### Effects (15+ total)
- **Morphology**: `erode`, `dilate`, `open`, `close`
- **Connectivity**: `bridge_gaps`, `remove_dead_ends`, `connect_regions_spanning`
- **Spatial**: `distance_transform`, `dijkstra_map`
- **Filters**: `gaussian_blur`, `median_filter`
- **Transform**: `mirror`, `rotate`, `scatter`
### Features
- **Room Templates**: Rectangle, Circle, Blob (via room_accretion)
- **Prefab Rotation**: Automatic 90°/180°/270° variants
- **Region Analysis**: Public `label_regions()` API
- **Spanning Tree**: Connectivity with loop control
## Future Work
While the demo framework is feature-complete for current TerrainForge capabilities, potential enhancements include:
### Configuration Enhancements
- **Prefab File Format**: External `.des`-style vault definitions
- **Parameter Validation**: JSON schema validation for configs
- **Config Templates**: Reusable parameter sets
### Output Improvements
- **Interactive Viewer**: Web-based exploration tool
- **Animation**: Step-by-step generation visualization
- **3D Export**: Height-based mesh generation
### Testing Extensions
- **Regression Testing**: Automated visual diff detection
- **Performance Benchmarks**: Algorithm timing comparisons
- **Fuzzing**: Random parameter space exploration
### Library Extensions
- **Semantic Layers**: Region metadata, spawn markers, connectivity graphs
- **Advanced Sampling**: Poisson distribution, constraint-based placement
- **Entity Integration**: Game-agnostic spawn slot generation
### Semantic Layer Support
The most significant potential enhancement would be **semantic layers** - extending TerrainForge output beyond tiles to include entity spawning metadata:
```json
{
"name": "semantic_dungeon",
"algorithm": "room_accretion",
"semantic_layers": {
"regions": true,
"markers": ["loot_slot", "enemy_spawn", "light_anchor"],
"masks": ["walkable", "no_spawn"],
"connectivity": true
}
}
```
This would enable the demo framework to:
- **Visualize regions**: Color-coded room/corridor/clearing identification
- **Show spawn markers**: Overlay entity placement slots on generated maps
- **Export metadata**: JSON output with semantic annotations for game integration
- **Validate constraints**: Ensure proper marker distribution and connectivity
**Implementation Impact**: Would require extending the config parser to handle semantic layer requests and updating the renderer to visualize the additional data layers.
These enhancements would be implemented as the library grows and user needs evolve, maintaining the framework's role as both testing harness and integration example.