delve generator

dungeon generator
and map layout

map

1what it is

Delve generator makes a dungeon from a number. Pick a seed, a size and a theme: it grows a dungeon (rooms, locked doors and their keys, switches, secret doors, one-way paths, a boss), draws it as a map and writes a GM key that names every room and what it holds. Seed, size and theme always give the same dungeon; its layout seed and corridors always give the same map of it, so any map can be shared as those five settings.

The theme names the rooms and picks the look: classic is hand-inked in the manner of Dyson Logos' maps, cyber glows in neon on black, plain is a clean catalogue map. Not every dungeon is a place underground, so the graph view shows the dungeon as what it is, rooms and the gates between them: a heist, a starship deck, a city district.

on the map page

2how it works

  1. generate

    A graph grammar grows the dungeon from the start room to the goal. Each rule rolls a d20 to pick a variant: a locked door with its key somewhere else, a switch that opens a gate, a mini-boss, a bonus room. Harder content sits closer to the boss. Small rooms of one kind are merged, then a solver walks from the start, picking up keys, to prove the goal can be reached. Size sets how far it grows; the theme only changes names and look, so one seed gives the same dungeon in every theme.

  2. write it down

    The dungeon becomes a JSON file: rooms, gates, keys, what lies where. Export it to keep it, load it back later; everything after this step reads only the file.

  3. lay out

    Every room gets a shape (rectangle, L or T) from the layout seed, then the rooms are placed so each door joins two rooms and nothing overlaps, loops first, after Ondřej Nepožitek's graph-based algorithm. When a part does not fit it backs up and tries again. Most doors get a short corridor. Now and then no layout is found: another layout seed usually fixes it.

  4. draw

    The map is drawn as SVG: numbered rooms, a mark for each kind of door, a key column and a title. Every look tags a gate with a letter shared with its key and marks one-way doors with a chevron; classic and cyber also draw a bar for locked, dots for a portcullis and an S for secret, plain a dashed line for secret. The GM key lists the same numbers.

3the grammar

The rules the generator follows, on one sheet. Each card is a rule; its variants are drawn as small graphs, with the d20 range that picks each one per size. It is the Combined grammar, grown from fantomx11's Zelda dungeon generator on the RPG.net forum.

Combined dungeon grammar: rule cards with d20 ranges per size and variant diagrams
scroll sideways · open full size

4how we built it

2021-11
A Python dungeon generator after fantomx11's grammar: a graph of rooms and gates, no map. Version 1.0 in December.
2024-11
The Python code tidied up: dungeon utilities apart from the grammars.
2026-10-25
Python generator 2.0: the Combined grammar paced by difficulty, sizes, themes, a JSON export and a GM key. The same day this project starts: a design for the map layout, checked against Nepožitek's thesis and the Edgar source.
2026-10-26
The layout engine, ported from the thesis: planarity, chains, room shapes, configuration spaces, simulated annealing.
2026-10-27
Map render, command line and this viewer; corridors; L and T rooms. The generator ported from Python to TypeScript, its known issues fixed; from then on the TypeScript version is the only one.
2026-10-28
The Dyson look: hatched rock, thick walls, floor grid; door symbols, wobbly walls and shadow the day after.
2026-10-30
The neon look for cyber, one theme select for names and look, the graph view, the grammar sheet and this page.

Built step by step with Claude Code: each step a written plan, a branch, tests first and a code review before it was merged. A benchmark of 16 fixed dungeons, laid out five times each, runs on every change to the layout. Plan and progress: STATUS.md.

5references