Procedural dungeon map generator for tabletop RPGs — generates hand-drawn-style dungeon layouts with rooms, passages, doors, water features, boss rooms, key shards, and safe rooms. Inspired by watabou's One Page Dungeon.
- Room placement with configurable sizes and shapes (rectangular, circular) — generates 4 up to 150 rooms per dungeon
- Intelligent passage routing connecting rooms with organic hallways and corridors
- Symmetry modes — None, Bilateral (mirror symmetry), Radial (180°/90° rotational)
- Configurable density — Sparse, Normal, and Tight room packing
- Automated doors with open/closed states and locked doors
- Stairs and dungeon exits for multi-level mapping
- Safe/respawn rooms every 20 rooms marked with a portal icon
- Boss rooms with glowing borders and key-shard requirements
- Key shard items — collectibles scattered through side-branch rooms
- Crosshatch shading with organic linework for a hand-sketched aesthetic
- Water features — procedural pools, lakes, puddles with ripple effects and organic shorelines
- Room decorations — columns, altars, fountains, dais platforms, rocks, stars, podiums, curtains, barrels, coffins
- High-quality output — render to PNG or SVG at any resolution
- Grid overlay for tabletop role-playing game play
- Map rotation with auto-recomputed bounds
- Noise-based water generation using marching squares with Chaikin curve smoothing
- Depth levels — Dry, Puddles, Pools, Lakes, Flooded
- Organic shorelines and ripple contour effects
150-room ULTIMATE dungeon rendered with crosshatch shading and water features:
Generate your own with python -m dungeongen.webview.app and select "ULTIMATE" size.
git clone https://github.com/wildfirebill/dungeongen.git
cd dungeongen
pip install -e .
python -m dungeongen.webview.appThen open http://localhost:5050 in your browser.
git clone https://github.com/wildfirebill/dungeongen.git
cd dungeongen
pip install -e .- Python 3.10+
- skia-python — high-quality 2D rendering
- numpy — noise generation
- Flask — web preview interface
- rich — structured logging
python -m dungeongen.webview.appOpens an interactive web interface at http://localhost:5050 where you can configure dungeon size, symmetry, water depth, rotation, and room labels, then export as PNG or SVG.
from dungeongen.layout import DungeonGenerator, GenerationParams, DungeonSize, SymmetryType
from dungeongen.webview.adapter import convert_dungeon
from dungeongen.map.water_layer import WaterDepth
params = GenerationParams()
params.size = DungeonSize.MEDIUM # TINY to ULTIMATE (4-150 rooms)
params.symmetry = SymmetryType.BILATERAL
generator = DungeonGenerator(params)
dungeon = generator.generate(seed=42)
dungeon_map = convert_dungeon(dungeon, water_depth=WaterDepth.POOLS)
dungeon_map.render_to_png('my_dungeon.png')
dungeon_map.render_to_svg('my_dungeon.svg')| Size | Rooms | Use Case |
|---|---|---|
| TINY | 4-6 | Quick one-shot, tutorial |
| SMALL | 6-10 | Short session dungeon |
| MEDIUM | 10-20 | Standard dungeon crawl |
| LARGE | 20-35 | Extended adventure |
| XLARGE | 35-50 | Large dungeon complex |
| XXLARGE | 50-75 | Mega-dungeon wing |
| XXXLARGE | 75-100 | Full mega-dungeon |
| MEGA | 100-125 | Massive dungeon |
| ULTIMATE | 125-150 | Maximum size dungeon |
| Type | Description |
|---|---|
NONE |
Fully asymmetric organic layout |
BILATERAL |
Mirror symmetry (left/right) |
RADIAL_2 |
180° rotational symmetry |
RADIAL_4 |
90° rotational symmetry |
| Level | Coverage | Description |
|---|---|---|
DRY |
0% | No water |
PUDDLES |
~45% | Scattered shallow puddles |
POOLS |
~65% | Connected pool network |
LAKES |
~82% | Large lakes and waterways |
FLOODED |
~90% | Mostly flooded dungeon |
dungeongen/
├── src/dungeongen/ # Main Python package
│ ├── layout/ # Dungeon layout generation
│ │ ├── generator.py # Procedural generator (rooms, passages, doors)
│ │ ├── numbering.py # Longest-path-first DFS room numbering
│ │ ├── models.py # Room, Passage, Door data models
│ │ ├── params.py # Generation parameters and constraints
│ │ └── validator.py # Layout validation and debugging
│ │
│ ├── map/ # Map rendering engine
│ │ ├── map.py # Main renderer (PNG/SVG output)
│ │ ├── room.py # Room interior rendering and decorations
│ │ ├── passage.py # Passage/corridor rendering
│ │ ├── water_layer.py # Procedural water generation
│ │ └── _props/ # Decoration props (columns, altars, etc.)
│ │
│ ├── drawing/ # Drawing utilities
│ │ ├── crosshatch.py # Crosshatch shading engine
│ │ └── water.py # Water and ripple rendering
│ │
│ ├── algorithms/ # Generic algorithms
│ │ ├── marching_squares.py # Contour extraction
│ │ ├── chaikin.py # Curve smoothing
│ │ └── poisson.py # Poisson disk sampling
│ │
│ ├── graphics/ # Graphics primitives
│ │ ├── noise.py # Perlin noise and FBM
│ │ └── shapes.py # Shape primitives
│ │
│ └── webview/ # Web preview application
│ ├── app.py # Flask web server
│ └── templates/ # HTML/CSS/JS templates
│
├── tests/ # Test suite
├── docs/ # Screenshots and documentation
├── debugger/ # Analysis and debugging tools
└── pyproject.toml # Python package configuration
Fixes and enhancements to the original codebase:
- Expanded dungeon sizes — Added
XXLARGE(50-75),XXXLARGE(75-100),ULTIMATE(125-150) tiers between XLARGE and MEGA - Safe/respawn rooms — Every 20th room tagged as a safe room with portal icon, shown in both SVG layout view and Skia map render
- Boss rooms & key shards — Red border glow on boss rooms, diamond key-shard icons, locked door padlock overlay, boss key-requirement labels in the Skia/PNG render pipeline
- Coordinate limit fixes — Raised hardcoded limits (4200 → 12800 map units) so MEGA/ULTIMATE dungeons render without crashing
- Auto-rotate transform — Map rotation (0-360°) applied around center with auto-recomputed bounds
- Room names & dungeon titles — Deterministic room name generation from tags/seed/number, dungeon title from seed, rendered on the map
- Webview UI — Rotation control, room name toggle, dungeon title toggle
This project was created by benjcooley. Thanks for the excellent procedural generation and rendering engine.
- watabou's One Page Dungeon — the hand-drawn crosshatch aesthetic and visual style draw heavily from watabou's work
- watabou's generators — more procedural content for tabletop RPGs
This is a complete Python rewrite, not a port. Options and behavior differ from the original. Notable gaps:
- Various edge cases and bugs remain — not everything works perfectly in every configuration
MIT License — see LICENSE for details.
