The map JSON, field by field
Every map is one JSON document in the format isodelve-map@1. The examples on this page come from the real map map_1t2nde66019682yc (seed my-first-dungeon, 30 × 24, gen-1.2.0, Ink Stone 1.1.0). The document is about 16 KB, or under 2 KB gzipped, because it describes what is where and never contains pixels.
Coordinates and the 5 ft grid
- One cell is one 5 ft square (
grid.cellFt: 5; 1.524 m in the art pack). xruns east (left to right on a top-down plan),yruns south (top to bottom). Cell(0, 0)is the north-west corner.- Cells are addressed by integers. Wall lines sit between cells, so a wall on the line
y = 6separates row 5 from row 6. - Positions that need a centre, such as lights, use half cells:
[28.5, 4.5]is the centre of cell(28, 4). - The four isometric angles (
iso0,iso90,iso180,iso270) are only ways of looking at the map. The document has one orientation; the angle is chosen when you draw it (Drawing a map).
Compass: where north is
A map’s north never changes: it is the top of the grid, row 0, the direction of decreasing y. East is increasing x. Anything that says “the north wall” (such as gen-1.3.0 clue text) means this map north, whichever way you look at the map.
- Top-down plan: north is up, east is right, south is down, west is left.
- Isometric views: the plan is turned 45° and squashed into diamonds, so north points along a diamond edge, not straight up the screen. With east up-right, north is up-left at
iso0(the default). Each view turns the map a quarter turn, so north moves around the screen:
| View | North on screen | East on screen |
|---|---|---|
iso0 (default) |
up-left | up-right |
iso90 |
down-left | up-left |
iso180 |
down-right | down-left |
iso270 |
up-right | down-right |
gen-1.3.0 maps with clues spell this out in a top-level orientation object:
"orientation": { "north": "-y", "east": "+x", "south": "+y", "west": "-x",
"note": "north = top of the grid (row 0, y decreasing); east = increasing x (right). In the iso views north is up-left on screen at iso0 (the default), down-left at iso90, down-right at iso180 and up-right at iso270." }
PNG renders of those maps carry a small compass in the top-left corner with an N at the needle’s tip, in both the game-master and the player (secrets=hide) views, turned to match the view. If you draw maps yourself and let people turn the view (a VTT with four corner views, say), turn the compass with the view; the map’s north, and any text about it, stays the same.
Top-level fields
| Field | Example | Meaning |
|---|---|---|
id |
"map_1t2nde66019682yc" |
Stored map id (map_ + 16 characters). Added by the API. |
format |
"isodelve-map@1" |
Document format. Check it before parsing. |
generatorVersion |
"gen-1.2.0" |
Generator that built the map. |
seed |
"my-first-dungeon" |
Seed used (always a string). |
pack |
"ink-stone@1.1.0" |
Exact art pack version to draw it with. |
type, theme |
"inside-dungeon", "crypt" |
Map type and dressing theme. |
params |
{…} |
The full, normalized parameters, defaults filled in. Replay these to rebuild the map. |
orientation |
{"north":"-y",…} |
gen-1.3.0 with clues: which way the compass points on the grid (Compass). |
clues |
array | gen-1.3.0 with clues on: hints to secret doors (clues). |
grid |
{…} |
The floor plan (below). |
rooms, corridors, doors, props, lights |
arrays | The contents (below). |
paths |
{…} |
Route structure (below). |
stats |
{"attempts":1,"floorCells":200} |
Generator attempts used and number of floor cells. |
renders |
{iso0: url, …} |
Server PNG URL per angle. Added by the API. |
links.self |
url | Where to fetch this JSON again. Added by the API. |
grid: the floor plan
"grid": {
"w": 30, "h": 24, "cellFt": 5,
"palette": ["", "floor.slab.a", "floor.slab.d", "floor.cracked.a", "floor.slab.b", "floor.slab.c", "floor.rubble.a",
"floor.stairs.down", "wall.seg.full.b", "wall.seg.full.a", "wall.seg.full.c", "portal.door.closed",
"portal.arch.open", "portal.door.open", "portal.secret.closed", "portal.doorway.open",
"portal.portcullis.closed", "vertex.corner.full", "vertex.straight.full", "vertex.t.full"],
"floor": [ "… 720 numbers …" ], "floorRot": [ "… 720 …" ],
"edgeH": [ "… 750 …" ], "edgeV": [ "… 744 …" ],
"vertex": [ "… 775 …" ], "vertexRot": [ "… 775 …" ]
}
The layers hold small numbers that index into palette, the list of piece ids used in this map. Index 0 is always "", meaning nothing there.
| Layer | Length | Index of position (x, y) | Holds |
|---|---|---|---|
floor, floorRot |
w × h |
y * w + x |
Floor piece of cell (x, y) and its rotation |
edgeH |
w × (h + 1) |
y * w + x |
Piece on the horizontal line y, spanning x to x + 1 (walls, doors) |
edgeV |
(w + 1) × h |
y * (w + 1) + x |
Piece on the vertical line x, spanning y to y + 1 |
vertex, vertexRot |
(w + 1) × (h + 1) |
y * (w + 1) + x |
Wall joint (end, straight, corner, T, cross) at grid point (x, y) and its rotation |
Rotations (floorRot, vertexRot, and rot on props) are quarter turns, 0 to 3.
const id = (layer, i) => map.grid.palette[map.grid[layer][i]];
const W = map.grid.w;
id("floor", 3 * W + 27); // floor piece of cell (27, 3)
id("edgeH", 6 * W + 27); // "portal.arch.open": door d1 on line y = 6
id("edgeV", 2 * (W + 1) + 10); // "portal.secret.closed": secret door d11 on line x = 10
Piece ids
Piece ids read as kind.case.variant, for example wall.seg.full.a, vertex.corner.full, portal.door.closed, prop.throne.a. The kinds are floor, wall (segments), vertex (joints), portal (doors, arches, doorways, portcullises, secret doors, breaches), prop and light. Wall heights are full, cut (cutaway, 3 ft) and half. The art pack manifest lists all 91 pieces with their properties (Art packs).
rooms
{ "id": "r2", "type": "entrance", "bounds": [26, 2, 3, 4], "doors": ["d1"],
"contents": ["prop.stairs-up.a", "light.torch.a", "prop.crate.a"] }
-
boundsis[x, y, width, height]in cells: this entrance covers cells x 26 to 28, y 2 to 5 (15 ft by 20 ft). -
typeis the room’s role, for exampleentrance,boss,treasure,shrine,guard,storage,tomb,ossuary,library. -
doorslists door ids on the room’s walls;contentslists the pieces placed in it. -
Secret rooms have
"kind": "secret"and idss1,s2… Normal rooms have nokindfield. In gen-1.3.0 a hallway cache is also a secret room: a 3 × 3 room off a corridor, behind a secret door found from that corridor, and listed inpaths.secretCaches. -
gen-1.3.0 rooms also carry
details: 1 to 3 short lines for the game master to read aloud or paraphrase, on every room, including secret rooms and rooms with nothing in them. See Room details.
corridors
{ "id": "c1", "connects": ["r2", "r3"], "cells": [[27, 6], [27, 7]] }
The rooms a corridor joins and every cell it covers. A breach’s rubble passage is appended to the cells of the corridor it joins.
A gen-1.3.0 secret passage is a corridor with "secret": true: a hidden 1-wide passage between two ordinary rooms that are not neighbours, with a secret door at each end. It is a shortcut, never the only way anywhere, and it has no dressing inside.
{ "id": "c5", "connects": ["r1", "r5"], "cells": [[15, 3], [16, 3], [17, 3], "… 26 cells …"], "secret": true }
doors
{ "id": "d1", "edge": { "x": 27, "y": 6, "dir": "h" }, "piece": "portal.arch.open",
"between": ["r2", "c1"], "state": "open", "locked": false }
edgeplaces the door on a wall line:dir: "h"meansedgeHat line y = 6, x 27 to 28;dir: "v"meansedgeV. The same piece appears in the grid layer at that index.betweennames the two spaces it connects (room or corridor ids).stateis"open","closed"or"secret".lockedis a separate true/false flag; a closed door can be locked or not.
Secret doors
{ "id": "d11", "edge": { "x": 10, "y": 2, "dir": "v" }, "piece": "portal.secret.closed",
"between": ["r1", "s1"], "state": "secret", "locked": false, "secret": true,
"trigger": { "piece": "prop.bookshelf.a", "cell": [10, 1] } }
secret: trueandstate: "secret"; the piece looks like plain wall.trigger(present on most secret doors) names the prop that opens it and its cell, close to the secret door on the side players explore from. It is a game-master note; renders do not mark it. Never show it to players.- The critical path never requires a secret door.
- gen-1.3.0 adds
opensto every secret door: how it opens andfrom, the room or corridor it is found from. The piece is stillportal.secret.closedand the state still"secret", so older readers see an ordinary secret door.
"opens": { "style": "pivot", "from": "c4" }
"opens": { "style": "shelf", "from": "r4", "dir": "right", "toward": "w",
"cover": { "piece": "prop.bookshelf.a", "cell": [21, 20], "slideTo": [20, 20] } }
pivot: the stone leaf swings open.shelf: a bookshelf door. A bookshelf (also listed inprops) stands oncover.cellin front of the door and slides one cell tocover.slideTowhen it opens;diris left or right as seen by the explorer facing the wall,towardthe same direction on the grid. A shelf door has no separatetrigger: the bookshelf is the mechanism.breach: truemarks a wall knocked through (portal.breach.open, at most one per map, only whendecay > 0).
props
{ "piece": "prop.chest.a", "at": [12, 3], "rot": 2, "room": "r1" }
atis the cell the prop stands on. For props bigger than one cell (prop.feast-table.ais 2 × 1,prop.dais.ais 2 × 2; seefootprintin the manifest),atis the north-west cell of the footprint after rotation, and width and depth swap whenrotis odd.rotis quarter turns,roomthe room it belongs to.- Light sources are props too (
light.torch.a,light.candles.a,light.brazier.a…), and each also appears inlights.
lights
{ "at": [28.5, 4.5], "radiusFt": 20, "color": "#ffb46b", "piece": "light.torch.a" }
Centre position in cells, radius in feet and colour, ready for a VTT’s dynamic lighting.
paths
"paths": { "critical": ["r2", "r3", "r1", "r4"], "branches": [["r3", "r5"]], "deadEnds": [],
"secret": [["r1", "s1"]], "breaches": [] }
critical: rooms in order from the entrance to the boss, following doors only.branches: optional side routes off the critical path;deadEnds: rooms the generator marks as dead ends.secret:[parentRoom, secretRoom]pairs.breaches:{ door, room, corridor, connects }for a breach, if any.secretPassages(gen-1.3.0):{ corridor, doors, connects }for each secret passage, for example{ "corridor": "c5", "doors": ["d11", "d12"], "connects": ["r1", "r5"] }.secretCaches(gen-1.3.0):{ corridor, room, door }for a hallway cache, for example{ "corridor": "c4", "room": "s2", "door": "d10" }.
clues: hints to secret doors
gen-1.3.0 maps have a clues array: things the party can notice or find that point toward a secret door, written to read aloud. Here are three clues from the map with seed s4-a (48 × 40, rooms 6 to 9, secretRooms: 2, level: 2):
{ "id": "h5", "kind": "sign", "style": "scratches", "room": "r6", "area": "east wall", "at": [40, 33],
"targets": ["d19"], "clarity": "vague", "sense": "sight", "difficulty": "easy",
"text": "Something heavy has scraped the stone near the east wall, and more than once.",
"gm": "Points to d19, the bookshelf secret door in the east wall of r6, into s1.",
"t": { "id": "sign.scratches.v4", "vars": { "area": "the east wall" } } }
{ "id": "h1", "kind": "found", "style": "map-scrap", "room": "r1", "at": [43, 8], "piece": "prop.note.a",
"targets": ["d20"], "clarity": "vague", "sense": "sight", "difficulty": "easy",
"text": "A torn corner of a hand-drawn plan. The storeroom is drawn larger than it should be, and one wall is inked twice.",
"gm": "Points to d20, the swinging stone secret door in the south wall of r8 (the storeroom), into s2. Found loose on the floor at 43,8.",
"t": { "id": "found.map-scrap.v1", "vars": { "place": "the storeroom" } } }
{ "id": "h3", "kind": "life", "style": "journal", "room": "r3", "at": [39, 21], "piece": "prop.book.a",
"targets": ["d19"], "person": { "name": "Garret Starke", "role": "acolyte" },
"text": "A journal kept by Garret Starke, acolyte: \"Third night of frost. Nobody will let me sweep near the shrine. They say the dust there keeps its own counsel.\"",
"gm": "Points to d19, the bookshelf secret door in the east wall of r6 (the shrine), into s1. By Garret Starke, acolyte. Found loose on the floor at 39,21.", "…": "…" }
kindis what sort of clue it is:sign: something noticed in the room or corridor the secret door is found from (scratches, a draft, a smell, odd stonework…), placed by wall side witharea.found: a note, map scrap, diary page or rubbing lying 1 to 3 rooms away that names the place to look.life: a piece of someone’s life (a journal, a letter, a ledger or a book of remembrance) by a named, invented person, with one vague hint in it.
textis for the players, once they find or notice the clue.gmis a plain note for the game master: which door it points to and where the item lies. Never showgmto players.targetslists the secret door ids the clue points to.roomandatare where the clue is; a found or life item sits in ahostprop (a chest, desk, bookshelf…) or lies loose with its ownpiece(prop.note.aorprop.book.a).tis the template id and its values, so a translation or a different voice can rebuild the line.- False clues: a few clues point at nothing. They have
targets: [],falseClue: true, andgmstarts with “False clue:”. There are at most 2 per map and they read just like true ones. Never showfalseClueto players either. - Clues never name the door or how it opens, and never use coordinates or ids in
text.
How many clues a map gets and how plain they are is set by knobs.clues, knobs.clueClarity and knobs.level (Generate parameters). On a 48 × 40 map they add about 2 KB of JSON.
Room details (flavor lines)
{ "id": "r6", "type": "shrine", "details": [
"The floor is worn smooth in a small patch where many people once knelt.",
"The pillars are carved with climbing vines, the leaves worn to stubs."] }
Lines come from the room’s role, what is in it, the map’s decay, or plain atmosphere for empty rooms, and no line repeats on a map. They are pure atmosphere: they never point at a secret door, so it is safe to read them to the players. Turn them off with knobs.flavor: false. About 0.8 KB of JSON per map.
Keeping secrets out of the players’ view
If you show a map to players (a VTT, a shared screen), hold back everything that gives secrets away until the party finds them:
- secret doors (
secret: true), theirtriggerandopens, and secret rooms (kind: "secret"); paths.secret,paths.secretPassagesandpaths.secretCaches;- in each clue:
gm,falseClueandtargets. Show a clue’stextonly once the party notices or finds it.
The PNG render has a player view for the same reason: secrets=hide draws secret doors as plain wall and leaves secret rooms out (Drawing a map).
params: secrets and props on or off
params records every knob with the value actually used. gen-1.3.0 adds secretDoors and two switches: with "secrets": false the map has no secret rooms, caches, passages or secret doors (and records secretRooms: 0, secretDoors: 0); with "props": false the only prop is the entrance’s prop.stairs-up.a, lights is empty and secret doors have no trigger or bookshelf. See Generate parameters.
Validating a document
format === "isodelve-map@1".floor.length === w*h,edgeH.length === w*(h+1),edgeV.length === (w+1)*h,vertex.length === (w+1)*(h+1).- Every palette id and prop piece exists in the pack named by
pack(the API checks this before returning a map). - If you edit a map, keep these invariants, and keep
generatorVersionandseedas a record of where it came from: an edited map can no longer be regenerated from its seed.
Next: Art packs.