How IsoDelve works
IsoDelve has two halves that never mix: a generator that decides what the dungeon is, and an art pack that decides what it looks like. The generator produces a small map document. The art pack is a set of sprites your app downloads once. Keeping them apart is what makes maps tiny, reproducible and easy to restyle.
1. The generator lays out the dungeon
Each call starts from a seed. The generator places four or five rooms (you can change the range) on a grid of 5 ft squares, connects them with corridors and doors, and gives each room a role: an entrance with stairs, a shrine, a guard room, an ossuary, a treasure room, a boss room. It works out the critical path from the entrance to the boss, and adds optional branches and dead ends depending on the loopiness setting.
Then it furnishes the rooms. Furniture comes in logical groups with some randomness: a bed with a nightstand, a desk with a chair, a hearth with firewood, a throne on the wall farthest from the doors. Tall props stay off door approaches so tokens can always get through. The clutter dial moves a map from sparse to busy.
2. Secrets and ruin
By default one secret room hangs off a normal room, behind a door drawn as plain wall. gen-1.3.0, the default generator, adds bookshelf doors, small hallway caches and hidden passages, and a single switch (knobs.secrets: false) turns every secret off. Most secret doors have a trigger nearby (a bookshelf, sconce or statue), recorded in the map file for the game master. Secret rooms are never on the critical path, so a party can always finish the dungeon without finding them.
The decay dial wears the dungeon down: cracked floors, crumbled and collapsed walls with rubble spilling out, broken furniture, scattered weapons and armor, and at most one breach knocked through a wall into a rubble passage. At 0 the halls are pristine; at 1 they are a ruin.
3. Every map is checked
Before a map is returned, a validator checks it against a long list of rules: rooms are reachable, required props are present and unique where they should be, furniture stays clear of doors, and secret doors and their triggers are placed correctly. If a layout fails, the generator tries again, and if it still can't build a valid map the API returns an error rather than a broken map.
4. The map document
The result is a JSON document of about 15 KB. It lists the grid as palette indexes, walls and doors on cell edges, rooms with bounds and contents, doors with their state, props, light sources with color and radius, and the paths. It also records the seed, the generator version and the art pack, which is everything needed to rebuild it. The API docs show a real one.
5. The art pack draws it
Every piece of the kit, from a floor slab to a portcullis, is modeled once in 3D. That single model is rendered to sprites at four isometric angles and three scales, and packed into atlases with exact anchor points. Because 2D sprites and the future 3D models come from the same source, they can never drift apart.
Art packs are versioned and immutable. A map records the exact pack version it was made for, so it draws the same way forever. The first pack, Ink Stone, has a hand-inked look on parchment, with 91 pieces in version 1.1.0. It is free for everyone. Browse it in the gallery.
6. Four angles and cutaway walls
Because each piece exists at iso0, iso90, iso180 and iso270, a viewer can rotate the map in quarter turns by switching sprite sets. Wall segments also come in cutaway and half heights, so a viewer can lower walls that would hide the floor. Server renders use short walls (walls=cutaway) by default, so every room is visible; ask for walls=full for tall walls. Doors, and secret doors in the game master's view, keep their full height.
7. Draw it yourself, or let the server render it
Most apps draw maps client-side from the cached pack: no per-map image traffic and instant rotation. If you just want a picture, the API composites a PNG for any angle, scale and wall mode and caches it.
Guarantees
- Determinism. Same seed, parameters, generator version and pack produce the same map, byte for byte.
- Stable versions. Older generator versions stay callable. Any change to output ships as a new version.
- Additive API.
/v1only gains fields; it never removes or renames them. - Original art. Every piece is built for IsoDelve.
Next: see who IsoDelve is for or jump to the quickstart.