IsoDelve

Home › Developer guide › The map JSON, field by field

The map JSON, field by field

Developer guide · updated

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).
  • x runs east (left to right on a top-down plan), y runs 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 = 6 separates 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"] }
  • bounds is [x, y, width, height] in cells: this entrance covers cells x 26 to 28, y 2 to 5 (15 ft by 20 ft).

  • type is the room’s role, for example entrance, boss, treasure, shrine, guard, storage, tomb, ossuary, library.

  • doors lists door ids on the room’s walls; contents lists the pieces placed in it.

  • Secret rooms have "kind": "secret" and ids s1, s2… Normal rooms have no kind field. 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 in paths.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 }
  • edge places the door on a wall line: dir: "h" means edgeH at line y = 6, x 27 to 28; dir: "v" means edgeV. The same piece appears in the grid layer at that index.
  • between names the two spaces it connects (room or corridor ids).
  • state is "open", "closed" or "secret". locked is 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: true and state: "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 opens to every secret door: how it opens and from, the room or corridor it is found from. The piece is still portal.secret.closed and 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 in props) stands on cover.cell in front of the door and slides one cell to cover.slideTo when it opens; dir is left or right as seen by the explorer facing the wall, toward the same direction on the grid. A shelf door has no separate trigger: the bookshelf is the mechanism.
  • breach: true marks a wall knocked through (portal.breach.open, at most one per map, only when decay > 0).

props

{ "piece": "prop.chest.a", "at": [12, 3], "rot": 2, "room": "r1" }
  • at is the cell the prop stands on. For props bigger than one cell (prop.feast-table.a is 2 × 1, prop.dais.a is 2 × 2; see footprint in the manifest), at is the north-west cell of the footprint after rotation, and width and depth swap when rot is odd.
  • rot is quarter turns, room the room it belongs to.
  • Light sources are props too (light.torch.a, light.candles.a, light.brazier.a…), and each also appears in lights.

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.", "…": "…" }
  • kind is 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 with area.
    • 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.
  • text is for the players, once they find or notice the clue. gm is a plain note for the game master: which door it points to and where the item lies. Never show gm to players.
  • targets lists the secret door ids the clue points to. room and at are where the clue is; a found or life item sits in a host prop (a chest, desk, bookshelf…) or lies loose with its own piece (prop.note.a or prop.book.a).
  • t is 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, and gm starts with “False clue:”. There are at most 2 per map and they read just like true ones. Never show falseClue to 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), their trigger and opens, and secret rooms (kind: "secret");
  • paths.secret, paths.secretPassages and paths.secretCaches;
  • in each clue: gm, falseClue and targets. Show a clue’s text only 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

  1. format === "isodelve-map@1".
  2. floor.length === w*h, edgeH.length === w*(h+1), edgeV.length === (w+1)*h, vertex.length === (w+1)*(h+1).
  3. Every palette id and prop piece exists in the pack named by pack (the API checks this before returning a map).
  4. If you edit a map, keep these invariants, and keep generatorVersion and seed as a record of where it came from: an edited map can no longer be regenerated from its seed.

Next: Art packs.