IsoDelve

Home › Developer guide › Generate parameters: size, rooms, seed, style and versions

Generate parameters: size, rooms, seed, style and versions

Developer guide · updated

POST /v1/maps takes a JSON object. Every field is optional; an empty body {} gives you a random default dungeon. The limits below come straight from the generator’s validation code.

The full body

{
  "seed": "crypt-7",
  "size": { "w": 30, "h": 24 },
  "rooms": { "min": 4, "max": 5 },
  "theme": "crypt",
  "type": "inside-dungeon",
  "knobs": {
    "loopiness": 0.2,
    "propDensity": 0.5,
    "require": ["entrance", "boss", "treasure"],
    "secretRooms": 1,
    "decay": 0.3,
    "clutter": 0.5
  },
  "pack": "ink-stone@1.1.0",
  "generatorVersion": "gen-1.2.0"
}

Reference

Field Type and limits Default What it does
seed string or number, up to 128 characters (numbers are turned into strings) random 10-character string, returned in the map Starting point for every random choice. Same seed and settings = same map.
size.w, size.h integers, 12 to 64, capped by your plan (Free: 40) 30 × 24 Grid size in 5 ft squares. 30 × 24 is 150 ft by 120 ft.
rooms.min, rooms.max integers, 1 to 12, max ≥ min 4 and 5 How many normal rooms to place (secret rooms are extra).
theme "crypt" "crypt" The dressing style. Only crypt exists in phase 1.
type "inside-dungeon" "inside-dungeon" Map type. Outdoor and cave types come later.
knobs.loopiness number 0 to 1 0.2 How many extra connections create loops instead of a tree of corridors.
knobs.propDensity number 0 to 1 0.5 How much loose dressing fills rooms.
knobs.require array of "entrance", "boss", "treasure" all three Room roles that must exist. The entrance is always included.
knobs.secretRooms integer 0 to 3 (gen-1.2.0+) 1 Hidden rooms behind secret doors. 0 turns them off (on gen-1.2.0 a treasure room may still have a secret door; use secrets: false on gen-1.3.0 for none at all).
knobs.decay number 0 to 1 (gen-1.2.0+) 0.3 Wear and ruin: cracks, crumbled and collapsed walls, rubble, broken props, at most one breach.
knobs.clutter number 0 to 1 (gen-1.2.0+) 0.5 Furniture groups (bed and nightstand, desk and chair, hearth and firewood…).
knobs.secretDoors number 0 to 1 (gen-1.3.0+) 0.15 How often the newer secrets appear: bookshelf doors, hallway caches and secret passages.
knobs.secrets true or false (gen-1.3.0+) true false turns off all secret content: no secret rooms, caches, passages or secret doors.
knobs.props true or false (gen-1.3.0+) true false places no props at all, only the entrance’s stairs up. Secret doors stay, as plain doors with no trigger.
knobs.clues true or false (gen-1.3.0+) true (always false with secrets: false) Clues to secret doors: signs in the room, found notes and pages, life snippets, and a few false clues marked for the GM. secrets: false with clues: true is an error.
knobs.clueClarity "vague" or "clear" (gen-1.3.0+) "vague" Vague clues hint at an area; clear clues name the feature. Neither names the door or how it opens.
knobs.level integer 1 to 20 (gen-1.3.0+) none (a middle setting) Party level, for any game system: higher levels get fewer clues.
knobs.flavor true or false (gen-1.3.0+) true 1 to 3 read-aloud detail lines for every room (rooms[].details).
pack "id@x.y.z" or a bare id such as "ink-stone" (= newest) the generator’s default pack Which art pack the map is built for. The map records the exact version.
generatorVersion "gen-1.0.0", "gen-1.1.0", "gen-1.2.0", "gen-1.3.0" the current one (gen-1.3.0) Which generator to run. Every listed version is frozen: pin one to keep its maps forever.

About “style”: there is no separate style parameter. The look of a map comes from the art pack (pack), the dressing from theme, and the feel from the knobs: decay for ruin, clutter for furniture, secretRooms for hidden areas, loopiness for layout.

Size and rooms together: the generator refuses a grid too small for the rooms you ask for. The check is roughly 25 squares per room against 60% of the grid. Real response for 6 rooms on a 12 × 12 grid:

{"error":{"code":"bad_request","message":"size: too small for 6 rooms","field":"size"}}

Example: six rooms, pristine, no secret rooms

curl -s -X POST https://api.isodelve.com/v1/maps \
  -H "Authorization: Bearer $ISODELVE_KEY" -H "Content-Type: application/json" \
  -d '{"seed":"guide-six-rooms","size":{"w":36,"h":30},"rooms":{"min":6,"max":6},"knobs":{"secretRooms":0,"decay":0,"clutter":0.3}}'

The real result has exactly six rooms (entrance, tomb, shrine, boss, treasure and guard), no secret room, 10 doors and 28 props.

Turning secrets or props off

Some tables don’t want secret rooms, and some tools draw their own furniture. gen-1.3.0 has two plain on/off switches:

curl -s -X POST https://api.isodelve.com/v1/maps \
  -H "Authorization: Bearer $ISODELVE_KEY" -H "Content-Type: application/json" \
  -d '{"seed":"guide-no-secrets","generatorVersion":"gen-1.3.0","knobs":{"secrets":false}}'
  • "secrets": false gives a map with no secret content at all: no secret rooms, hallway caches or secret passages, and no secret doors (the treasure room gets an ordinary locked door). The map records secretRooms: 0 and secretDoors: 0. This seed gives five rooms, 12 doors and none of them secret.
  • "props": false gives rooms, corridors, walls and doors with no props: no furniture, chests, decor, lights or trigger props. The entrance keeps its stairs up (the way in) and the boss room its stairs down. Secret doors stay, as plain pivot doors with no trigger.
  • Both default to true, and turning one off doesn’t move the rooms or ordinary corridors of a seed.
  • Sending secrets: false with a non-zero secretRooms or secretDoors is a 400 (field: "knobs.secretRooms" or "knobs.secretDoors"). Older generator versions refuse both switches with a 400.

Clues and room details

gen-1.3.0 maps come with clues to their secret doors and a few lines of description for every room. Both are on by default. For a low-level party with plain clues:

curl -s -X POST https://api.isodelve.com/v1/maps \
  -H "Authorization: Bearer $ISODELVE_KEY" -H "Content-Type: application/json" \
  -d '{"seed":"guide-clues","generatorVersion":"gen-1.3.0","knobs":{"level":2,"clueClarity":"clear"}}'
Party level First clue per secret door Second clue Third clue (larger maps)
1 to 4 always 60% 30%
5 to 10, or no level always 40% 20%
11 to 20 85% 25% 10%

A room holds at most 2 clues and a map at most 3 more than its number of rooms. Turn clues off with "clues": false and room details off with "flavor": false; the rest of the map stays the same. These four knobs are rejected on gen-1.2.0 and older. What the fields mean, and which ones to keep from players: The map JSON.

Example: empty body

curl -s -X POST https://api.isodelve.com/v1/maps \
  -H "Authorization: Bearer $ISODELVE_KEY" -H "Content-Type: application/json" -d '{}'

The real result recorded "seed": "pj9vzynkp1" (random), gen-1.2.0, ink-stone@1.1.0, a 30 × 24 grid, four rooms plus one secret treasure room. Save the seed if you like the map.

Seeds and reproducibility

The same seed + parameters + generator version always produce the same layout, byte for byte, and the pack never changes the layout. To rebuild a map later, keep its seed, generatorVersion and params (all in the response), or just keep the JSON. Replaying the recorded params with the same generatorVersion gives the same map.

Pinning a generator version

New generator versions improve maps, which changes the output for existing seeds. Old versions stay available, so pin the version when you need a map to stay the same forever:

curl -s -X POST https://api.isodelve.com/v1/maps \
  -H "Authorization: Bearer $ISODELVE_KEY" -H "Content-Type: application/json" \
  -d '{"seed":"my-first-dungeon","generatorVersion":"gen-1.1.0"}'

Real result: generatorVersion: "gen-1.1.0", pack: "ink-stone@1.0.0" (that version’s default pack), four rooms (entrance, boss, treasure, storage). The same seed on gen-1.2.0 gives a different dungeon with a secret library.

Generator Default pack Notes
gen-1.0.0 ink-stone@1.0.0 Launch generator
gen-1.1.0 ink-stone@1.0.0 Unique required props; feast table and dais kept clear of doors
gen-1.2.0 ink-stone@1.1.0 Secret rooms, decay, broken props, furniture groups, secret-door triggers
gen-1.3.0 (current) ink-stone@1.1.0 Bookshelf doors, hallway caches, secret passages, clues and room details, orientation; knobs secretDoors, secrets, props, clues, clueClarity, level, flavor

Older versions refuse the newer knobs instead of silently ignoring them (real response):

{"error":{"code":"bad_request","message":"knobs.decay: needs gen-1.2.0 or later (got gen-1.1.0)","field":"knobs.decay"}}

And an unknown version lists what exists:

{"error":{"code":"bad_request","message":"unknown generatorVersion gen-9.9.9","field":"generatorVersion","available":["gen-1.0.0","gen-1.1.0","gen-1.2.0","gen-1.3.0"],"generators":[…]}}

Choosing a pack

  • Omit pack to get the generator’s default (best for most uses).
  • Send a bare id ("ink-stone") to get the newest version; the map records the exact id@x.y.z it resolved to, so it stays reproducible.
  • Pin "ink-stone@1.1.0" when you cache sprites for one version and want every map to match it.
  • A map that would use pieces the pack lacks is refused with 422 pack_incomplete before anything is stored. Ask for a newer pack.
  • Additional art packs (paid plans only) are coming later; Ink Stone is the only pack today.

Parameter errors at a glance (all real responses)

Request Response
"size":{"w":8,"h":30} 400 bad_request, size.w: must be between 12 and 64, field: "size.w"
"theme":"forest" 400 bad_request, theme: one of crypt
"pack":"no-such-pack" 400 pack_not_found, no pack no-such-pack
body that isn’t JSON 400 bad_json
body over 16 KB 413 too_large

Every 400 carries a field you can show next to the right input. Next: The map JSON.