Generate parameters: size, rooms, seed, style and versions
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": falsegives 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 recordssecretRooms: 0andsecretDoors: 0. This seed gives five rooms, 12 doors and none of them secret."props": falsegives 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: falsewith a non-zerosecretRoomsorsecretDoorsis a400(field: "knobs.secretRooms"or"knobs.secretDoors"). Older generator versions refuse both switches with a400.
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
packto get the generator’s default (best for most uses). - Send a bare id (
"ink-stone") to get the newest version; the map records the exactid@x.y.zit 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_incompletebefore 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.