# text-maps DSL — Dungeon reference Information-oriented, exhaustive syntax reference for dungeon and building maps (`map dungeon`, `map building`): every declaration, property, accepted value and default. For what both map kinds share (syntax, comments, icon imports, the editor's tools), see the [DSL reference index](dsl-reference.md.txt). For a guided walkthrough, see the [dungeon tutorial](dsl-tutorial-dungeon.md.txt). For hex maps, see the [hex map reference](dsl-reference-hex.md.txt). ## Map header ``` map dungeon "The Sunken Keep" seed: 42 labels: legend ``` [Try it live](https://text-maps.tyrcho.com/#map/LYQwDgBAJgrgdgcwKYHs4QEQBUAWSIDK8A1kugNJJJgYBQEEAzlVAFwQAsATPRADYgARkj6N2fJMjhRaQA) - `map dungeon` or `map building` — required, first line. An optional quoted (or bare) title follows on the same line. This title is used beyond the DSL itself: it becomes the browser tab's page title, a readable (but purely cosmetic — never parsed back) hint in the shared URL, and the default filename for downloaded/exported images (in the browser and from the CLI's `-o` directory/bare-extension shorthand — see `CliArgs.Usage`/`--help`). - Header properties (indented under the `map` line): | Property | Values | Default | Meaning | |---|---|---|---| | `seed:` | integer | none | RNG seed for `generate dungeon` (see below); unused for a manually-authored map | | `style:` | any | none | parsed but currently has no rendering effect — reserved for a future visual-style switch | | `labels:` | `legend` \| `inline` | `legend` for `map dungeon`, `inline` for `map building` | see **Label styles** below | | `background:` | `plain` \| `hatch` \| `shadow-edge` | `hatch` for `map dungeon`, `plain` for `map building` | see **Background styles** below | | `compass:` | a corner (`top-left`, `top-right`, `bottom-left`, `bottom-right`, or `tl`/`tr`/`bl`/`br`), optionally followed by an angle in degrees | none (no compass) | a compass rose in that corner of the image; an empty value means `top-right`. The angle turns north clockwise from straight up (`compass: top-right 90` points N to the right) | | `scale:` | ` `, e.g. `2 m`, `5ft`, `1.5 m`, optionally followed by a corner | none (no scale bar) | one grid square is that long: draws a scale bar (default corner `top-left`) spanning a round length — e.g. `scale: 2 m` draws 5 squares labelled `10 m` | | `coords:` | `on` \| `off` | `off` | `on` names the grid squares like a chessboard, so a square reads `B7`: column letters along the top, `A` the leftmost column the map spans, then `B` ... `Z`, `AA`, `AB`; row numbers down the left, 1 the topmost row. These name squares on the picture; they are not `pos:` values (column `A` is whatever `col` the map starts at). A label that would sit under the compass rose or scale bar is left out. The editor's ![Map settings](tool-icons/map-settings.svg) **Map settings** → Grid coordinates toggles it | **Map type difference:** `dungeon` renders thick rock-carved walls (thin corridors are fine); `building` renders thin constructed walls and is meant for maps with multiple exterior exits. Same grammar either way — only the rendering style differs. **Label styles:** `legend` — rooms get a bold number, keyed to a "N - label" legend box below the map. `inline` — no numbers; each room's label is centred inside it. A single room can opt out of the map's style with its own `label-style:` property (see `room` below) — e.g. `label-style: inline` writes that one room's label inside it and drops it from the legend (the remaining legend rooms renumber contiguously). In the visual editor, double-click a room and pick **In legend** / **In room**. **Background styles:** `hatch` — dense diagonal cross-hatch fills the whole non-room area ("carved in rock"), the default for `map dungeon`. `plain` — flat white background, matching real floor-plan references; the default for `map building`. `shadow-edge` — a light hatch band hugging just each room/corridor's own boundary, fading to plain white beyond it, instead of `hatch`'s full-canvas fill. ## `room x` / `room size: x pos: ,` ``` room entrance 4x4 label: "Gatehouse" shape: rectangular room boss size: 4x4 pos: 12,5 label: "Boss" ``` - `` — a bare identifier (no spaces), referenced by `connect:` blocks. Ids must be unique: declaring the same id twice is an error (`Duplicate room id ''`). - `x` — size in grid squares (1 square = 30px). Written either positionally (`room hall 5x4`) or keyed (`room hall size: 5x4`). - `pos: ,` (optional, on the header line, before or after the size) — an absolute position: the grid square of the room's top-left corner, x east and y south, negatives allowed (`pos: -3,2`; `pos: 3, 2` with a space also works). A malformed value is a parse error. See **Absolute positioning** below. - Properties: | Property | Values | Default | |---|---|---| | `label:` | any string | none (no label drawn) | | `label-style:` | `legend` \| `inline` \| `none` | the map's `labels:` style — overrides it for this room only; `none` draws neither a number nor a label (e.g. a free-form corridor) | | `shape:` | `rectangular` \| `circular` \| `cave` (irregular hand-drawn outline) \| `half-disc ` \| `quarter-disc ` (see **Half and quarter discs** below) \| `custom` (authored outline — see **`shape: custom` + `contour:`** below) | `rectangular` | | `stairs:` | `up` \| `down`, optionally followed by a wall word (`stairs: up west`), then optionally a `col,row` cell (`stairs: down east 3,1`) | none | | `spiral-stairs:` | `up` \| `down`, optionally followed by a `col,row` cell (`spiral-stairs: up 0,2`) | none | | `ladder:` | `up` \| `down`, optionally followed by a `col,row` cell (`ladder: down 4,3`) | none | | `window: ` | comma-separated wall words, e.g. `window: north,south` | none | | `.: ` | see **Icon features** below | — | | `layer:` | any string (a named grouping) | none (always visible), or the enclosing `layer` block's | **Half and quarter discs.** `shape: half-disc ` draws half an ellipse filling the room's box, its round side facing `` (`north`/`south`/`east`/`west`, or `n`/`s`/`e`/`w`; `north` when omitted) and its flat wall on the opposite side — an apse is `room apse 6x3` + `shape: half-disc north`. `shape: quarter-disc ` draws a quarter of an ellipse whose arc bulges toward `` (`north-east`/`south-east`/`south-west`/`north-west`, or `ne`/`se`/`sw`/`nw`; `north-east` when omitted), the right angle sitting in the opposite corner — a round corner tower. The size is the whole box: a 6x3 half disc facing north has a 6-square flat wall and is 3 squares deep. A door on a flat side behaves exactly as on a rectangular room; a door on a round side sits where the corridor meets the arc (the corridor runs on into the box to reach it), and `position:` slides it along either kind of side. A `window:` on a round side sits on the arc too. See `examples/dungeon/half_and_quarter_discs.dsl`. `stairs:`/`spiral-stairs:`/`ladder:` are mutually independent — a room can declare more than one if it genuinely has both (rare, but not rejected). `stairs: up` alone faces north by default; the tapering step-bar shading (bold = near, thin = far) shows up vs. down without needing an arrow or text label. Spiral stairs are drawn with game-icons' `3d-stairs` icon (built in, no `import` needed), and a ladder or spiral stairs carries a small ▲/▼ arrow for up vs. down. Each of the three is one grid square, centred in the room by default. A trailing `col,row` puts it on that exact cell instead, counted like an icon's `col,row` from the room's top-left interior square (`0,0`): `stairs: down east 3,1` is the fourth column, second row, leading east. `3, 1` with a space also works. In the visual editor, the Add Item tool's stairs, spiral stairs and ladder buttons place the feature on the square you click, and stairs face the wall nearest the click. ### Turning an item: `rot:` Any item except a window can be turned: add `rot: ` anywhere in its value, clockwise, any whole number (normalised to 0–359, so `rot: -90` is `rot: 270`). It turns the item about its own centre: `ladder: up 2,1 rot: 90`, `gi.table: 3x1 1,2 rot: 90` (a 3×1 table standing upright), `gi.chest: rot: 45`. On a wall list (`gi.bed: north,south rot: 90`) it turns every copy. Stairs add it on top of the wall they face, so `stairs: down north rot: 90` looks like `stairs: down east`; the ▲/▼ arrow of a ladder or spiral stairs stays upright. In the visual editor, select an item with ![Select](tool-icons/select.svg) Select and press **R** to turn it a quarter turn clockwise (**Shift+R** anticlockwise), or double-click it for buttons and a box to type any angle; a quarter turn of stairs just changes the wall they face. The same popup resizes an icon (W × H squares) and, under **Change item**, swaps the item for another one picked from the same list as the Add item tool (stairs, ladders, icons, "More icons"), on the same spot and at the same angle. Without the popup: on a selected item the cursor turns into resize arrows over an icon's handles (drag to resize it in whole squares) and into a curved arrow just outside its corners (drag to turn it a quarter turn at a time, or by 15° holding Shift). A selected room turns the same way, by quarter turns (also **R** / **Shift+R**, or the room popup's ↺/↻ buttons): its size swaps, a pinned room keeps its centre, and everything in it turns with it; a free-form `outline:`/`shape: custom` room can't turn. A selected corridor's long walls show resize arrows: drag one to change its `width:`. ## `shape: custom` + `contour:` ``` room throne_room 8x6 shape: custom contour: - east: 8 - south: 4 - west: 3 - south: 2 - west: 5 - north: 6 ``` A hand-drawn outline instead of `cave`'s procedural random blob, for when you need a precise non-rectangular shape (an L-shaped room, a notch, ...). `contour:` is a dash-prefixed sequence of `direction: length` segments — the same grammar `connect:`'s `path:` uses (see below) — walked as a closed polygon starting at **the room's own top-left corner, `(0, 0)`** (x increases east, y increases south, same grid units as the room's declared `x`). The segments must sum back to exactly `(0, 0)` and their bounding extent must exactly match the declared `x` — tracing the example above: `(0,0) → east 8 → (8,0) → south 4 → (8,4) → west 3 → (5,4) → south 2 → (5,6) → west 5 → (0,6) → north 6 → (0,0)`, closing exactly with bounding box `[0,8]×[0,6]`, matching `8x6`. A contour that doesn't close or doesn't match its room's own declared size is a parse error naming the room. `contour:` is ignored (and validated) only when `shape: custom` is also set. ## `connect:` ``` connect: from: entrance door: wall: north type: locked swing: inside position: -1 to: great_hall door: type: closed swing: outside width: 2 length: 3 layer: "Upper Floor" ``` Joins two rooms — see **`length:`**/**`path:`** below for how (or whether) a corridor is routed between them. **A `connect:` always has to define its own corridor explicitly: giving neither `length:` nor `path:` at all means the same thing as `length: 0` — the two rooms sit glued together, doors facing directly into each other, no corridor drawn.** Full replacement for the older `connect -> ` single-line form (no longer accepted). - `from:`/`to:` — each names a room; together they must match declared `room` ids (otherwise: `connect entrance -> zzz: no room named 'zzz'`) and must be two different rooms (`from`/`to` naming the same room is an error). Two rooms can be connected more than once — e.g. a door on each of two walls, or a corridor plus a secret door: each further `connect:` block for the same pair (either way round) draws its own doors and corridor. The first one is the one that places the rooms; give the others a `position:` (or a `path:`) so they don't sit on top of it. Each may carry its own nested `door:` sub-block, indented one level further than `from:`/ `to:` itself; a `to:` with no `door:` sub-block draws the same door as `from:`'s (give `to:` its own `door:` for an independent one). - `door:` sub-block properties (nested under `from:` or `to:`): | Property | Values | Default | Meaning | |---|---|---|---| | `wall:` | `north`/`south`/`east`/`west` (`n`/`s`/`e`/`w`) | none (inferred from the corridor's own shape at this end) | which wall this end's door sits on | | `type:` | `open` \| `closed` \| `locked` \| `secret` | `open` | the door itself: `closed` is a solid leaf across the doorway, `locked` the same leaf with a padlock on it | | `swing:` | `default` (plain gap) \| `inside`/`in` \| `outside`/`out` \| `slide-left`/`slide-l` \| `slide-right`/`slide-r` | `default` | architectural leaf+arc (`inside`/`outside`, one leaf as wide as the door unless `leaves: 2`; an `open` door is drawn ajar, a `closed`/`locked` one stays shut with its swing shown as a thin arc and dashed ghost leaf) or a sliding panel (`slide-left`/`slide-right`; an `open` panel sits retracted beside the doorway, a `closed`/`locked` one blocks it with a dashed ghost of the panel and a chevron on the side it slides to); a `secret` door stays hidden in the wall, with its swing or slide drawn as a faint grey ghost | | `leaves:` | `1` \| `2` | `1` | a swinging door's leaves, whatever its width: `2` is a double door, two leaves hinged at the jambs meeting in the middle | | `position:` | a signed whole number of grid units | `0` (centred on the wall) | slides this end's door along its wall; positive moves east (on a north/south wall) or south (on an east/west wall) | - Top-level `connect:` properties: | Property | Values | Default | Meaning | |---|---|---|---| | `width:` | a whole number of grid units | `1` | passage width, shared by both ends | | `length:` | a whole number of grid units | `0` (glued — no corridor) | shorthand for a single straight run of this length, in whatever direction `direction:`/auto-placement resolves to; `length: 0` (the same as omitting it, and omitting `path:` too) collapses the passage entirely — the two rooms sit adjacent, doors facing directly into each other with no corridor drawn between them. A straight (`length:`, no `path:`) corridor never bends — it's always a single run along one cardinal direction; an explicit `path:` is the only way to author a bend | | `path:` | a dash-prefixed sequence of segments (see below) | none | an explicit multi-segment route, for a bend, several turns, or crossing another connection's own corridor — anything `length:` alone can't express | | `direction:` | `north`/`south`/`east`/`west` (`n`/`s`/`e`/`w`), or screen-relative `up`/`down`/`left`/`right` (`u`/`d`/`l`/`r`) | none (auto-placed by the layout engine) | the side of `from` that `to` sits on, `length:` squares away (centres lined up): an exact placement, read the other way round from `to` | | `layer:` | any string (a named grouping) | none (always visible), or the enclosing `layer` block's | groups this connection, see **`layer:`** below | | `stairs:` / `spiral-stairs:` / `ladder:` / `.:` | same values as on a room | none | an item placed in the corridor (no `window:` — a corridor has no walls of its own); a `,` counts grid squares from the corridor's own top-left square, and no position centres it in the corridor | `path:` and `length:` are mutually exclusive route shorthands — when `path:` is non-empty it takes precedence, and its own first segment's direction places the `to` room (not `direction:`). Each door's `position:` is clamped to stay inside its own wall (with room for the door itself), falling back to centred if the wall is too short for the requested offset at all. Setting only the `from`-end's `position:` slides both ends together, keeping a straight corridor; giving the two ends different values bends the corridor into a dogleg so it still reaches each door. Corridors and doors always sit on whole grid squares: a straight corridor runs along the square nearest the line between the two rooms (on an even-sized wall, whose midpoint is a grid line, that's the square just north/west of it), `position:` offsets move it by whole squares, and a dogleg's jog runs along a whole row or column. A room without a `pos:` is placed by the connection that reaches it. A connection with a `direction:` or a `path:` fixes exactly where its two rooms sit relative to each other, and reads the same both ways: `from: a`, `to: b`, `path: - north: 2 - east: 3` puts `a` and `b` exactly where `from: b`, `to: a`, `path: - west: 3 - south: 2` does. So no room is special (there is no root room): which room the layout starts from only decides where the whole map sits, never where a room sits next to its neighbours, and two connections that disagree are not "fixed" by nudging one of the rooms (they simply overlap). Every room lands on the grid: when lining up centres or turning on wall midpoints leaves a room half a square off, the room with an odd size along that axis moves north/west (its middle square then lines up with the door square on the even room's wall), and a `path:`'s last leg stretches or shrinks by that half square to still meet its wall. A connection with neither (just `from:`/`to:`, maybe a `length:`) is placed automatically: walking the connections outward from the room named `entrance` (or the first room), each such room takes the next of a few preset angles around the room it is reached from, `length:` beyond touching, moved clear of the rooms already placed. The visual editor's **Expand into rooms** writes a `direction:`/`length:` (or a `path:`) on every connection that places a room, and so does the first drag of a room in a map that still has automatic ones, so from then on moving a room never moves another one. A room with a `pos:` is placed exactly there instead — see **Absolute positioning** below. ### Absolute positioning (`pos:`) As soon as any room has a `pos:`, the map is laid out from those pinned rooms: - A pinned room sits exactly at its `pos:`, always on the grid. Its connections never move it: `length:` and `direction:` are ignored between two pinned rooms. - A `connect:` between two pinned rooms routes itself: a straight corridor on whole grid squares through the span the two rooms share (when they overlap by at least the passage `width:` along one axis), otherwise an L-shaped corridor that leaves one room and enters the other through perpendicular walls, bending on whichever side doesn't run through another room. An explicit `path:` is still drawn exactly as written. - A room without a `pos:` in such a map is placed relative to the pinned room(s) it connects to, exactly as before (`length:`, `direction:`, `path:`), and snapped onto the grid the same way. A group of rooms with no pinned room at all is laid out on its own, to the right of the rest. Mixing the two is fine, which makes it easy to draft a map by hand (or by an agent) with every room pinned and fine-tune it in the visual editor: there, dragging a room in a map that uses `pos:` rewrites just that room's `pos:` (snapped to the grid), and the editor's ![Snap to grid](tool-icons/snap.svg) **Snap to grid** button writes a `pos:` for every room at its current position, turning a relatively laid-out map into an absolute one. ### `path:` (and `contour:`) segment grammar ``` path: - north: 3 - west: 2 width: 2 - south: 5 ``` A dash-prefixed sequence, not bare indented `key: value` lines — a flat map would silently deduplicate two segments in the same direction (e.g. a zigzag with two separate `north:` legs), which a real route needs to allow. Each `- : ` item may carry extra properties as further-indented lines directly below it, exactly like a YAML sequence of one-or-more-key mappings — `width:` (a corridor `path:` segment only; meaningless on a room's `contour:`) overrides the connection's own passage width for just that one leg. A segment's length counts the squares of corridor it adds; each bend then takes the next square, so the corridor turns in the middle of a grid square rather than on a grid line. `- north: 0` followed by `- east: 2` leaves through the north wall, turns in the square right outside the door, and runs two more squares east to the next wall. A single straight segment is wall to wall, exactly its length. ## `generate dungeon rooms: [seed:] [style:]` ``` map dungeon generate dungeon rooms:10 seed:42 ``` [Try it live](https://text-maps.tyrcho.com/#map/LYQwDgBAJgrgdgcwKYHs4ChlyQJxAFyWnmTQhxRWAGcAuARgAYJqkkpaAWAJnSA) Replaces manual `room`/`connect` declarations with a BSP (Binary Space Partitioning) procedural layout: `rooms:` room count (default 8 if omitted, at most 500; `rooms: 12` with a space also works), `seed:` for reproducibility, `style:` currently unused. A document with a `generate dungeon` line ignores any `room`/`connect` lines also present. To edit a generated dungeon room by room, click **Expand into rooms** in the editor's hint bar: it replaces the `generate dungeon` line with the plain `room`/`connect:` declarations the generator produced (same ids, sizes and connections), which draw exactly the same map. ## Icon features (room furnishings/structures) Every room feature other than doors/windows/stairs is an Iconify icon, declared as `.: ` (the alias from an `import` line): ``` import icon-sets.iconify.design/game-icons as gi room hall 5x4 gi.stalactites: gi.ionic-column: north gi.colombian-statue: 2,1 gi.bed: north,south ``` The value grammar (all optional — an empty value after the colon is valid and means "default size, centred"): | Value form | Meaning | |---|---| | *(empty)* | default 1×1 size, centred (`Auto`) position | | a bare number, e.g. `2` | that size squared (2×2), centred position | | `x`, e.g. `2x3` | that exact size, centred position | | a wall word, e.g. `west` (`north`/`south`/`east`/`west`, `n`/`s`/`e`/`w`) | default size, biased toward that wall | | `,`, e.g. `2,1` | default size, precise grid-cell position (from the room's own top-left interior corner) | | a comma-list where **every** part is a wall word, e.g. `north,south` | one full-default-size icon **per side listed** (e.g. two beds) — the multi-instance furnishing case | | a size and a position, separated by a space, in either order — e.g. `3x3 4,5`, `2 north` | that size at that position (`,` is the icon's top-left square) — e.g. a 3×3 fountain: `gi.fountain: 3x3 4,2` | | any of the above plus `rot: ` — e.g. `3x1 1,2 rot: 90` | the same icon turned clockwise about its centre (see **Turning an item: `rot:`** above) | `window:` (a hardcoded structural symbol, not an icon) shares the same comma-list-of-sides grammar for multiple windows. The same key can also repeat, one line per copy — each line places its own icon, so a room can hold the same icon several times at different spots (this is what the visual editor's ![Add item](tool-icons/place.svg) Add item tool writes when you place an icon a room already has): ``` gi.torch: 1,1 gi.torch: 4,1 ``` ## Free-form shapes: `outline:` rooms, `wall:`, `stairs:`, `door:` For a plan traced from a sketch rather than built from connected boxes, four declarations take their shape straight from grid coordinates — the same idea as a [hexcrawl `river:`'s](dsl-reference-hex.md.txt#roads-rivers--paths) waypoints. They all use one **point list** grammar: ``` (x,y)-(x,y)-... absolute points on the grid lines (2,3)-(e 4)-(s 2) or moves from the previous point ``` - `(x,y)` is a point on the grid lines themselves — x east, y south, in grid squares; `(0,0)` is the top-left corner of the square that `pos: 0,0` names. Negatives are fine. - `( )` moves `n` squares from the previous point, `` one of `n`/`s`/`e`/`w`/`ne`/`nw`/`se`/`sw` (or `north`, `up`, `left`, ...). The first point must be absolute. - A shape's points are walked as a closed polygon (back to the first point). **Two points are a rectangle**: `(2,4)-(10,5)` is the box with those opposite corners. Free-form shapes are pinned where their points say: like a room with a `pos:`, nothing ever moves them. ### `room outline: ` — free-form rooms and corridors ``` room hall outline: (0,0)-(e 10)-(s 4)-(w 3)-(s 3)-(w 7) label: "L-shaped hall" room passage outline: (10,1)-(16,2) label-style: none ``` A room whose walls follow its outline instead of a `x` box — written instead of the size (no `size:`/`pos:` with it). Its points must be whole grid points; edges may be diagonal. Everything else about a room still applies (`label:`, icons, `layer:`, `connect:`, notes): its size and position are its outline's bounding box, so icon positions count from that box's top-left square. Its floor grid is clipped to the outline, and an inline label goes in the largest rectangle that fits inside it. A **corridor** is simply an outline room with `label-style: none`. Where two free-form rooms share a wall, both draw it: add a `door:` (an open one is a plain gap) wherever you want a passage. A **ring** — a balcony around a void, a gallery around a courtyard — is one outline that walks the outside, cuts in, walks the inside the other way and cuts back out along the same line. The cut is walked once each way, so no wall is drawn along it: ``` room gallery outline: (0,9)-(9,9)-(9,15)-(0,15)-(0,10)-(1,10)-(1,14)-(8,14)-(8,10)-(1,10)-(0,10) label: "Gallery" ``` In the visual editor, dragging an outline room moves its whole outline (every absolute point shifts; relative moves follow). ### `wall: ` — thick walls ``` wall: (3,-1)-(6,0) wall: (2,4)-(4,5)-(3,6) ``` A solid, hatched wall of any shape — the thick wall between two halls, a pillar, a collapsed area. Drawn over the rooms declared above it, so it can straddle their walls; a room declared below it is drawn over it, cut into the rock (except a room the wall stands wholly inside: the wall is then a pillar, still drawn on top). Properties: `layer:`, and `width:` to draw it along a path of squares instead (see [paths](#paths-connect-with-route-and-wall-with-width)). In the visual editor, the ![Path](tool-icons/draw.svg) **Path** tool draws one (pick **Solid wall**, see [paths](#paths-connect-with-route-and-wall-with-width)). With **Select**, drag a wall (or a `stairs:` flight, a route or a free `door:`) to move it by whole squares — the arrow keys nudge the selected one — and drag the handles on the sides and corners of a selected wall, flight or corridor to resize it, like a room. ### `stairs: ` — stairs spanning several squares ``` stairs: (16,0)-(18,4) up: east ``` A flight of steps filling its shape (usually a rectangle), one step per quarter square across the flight, the lines getting bolder toward the top, with an arrow pointing up. (Not to be confused with a room's own `stairs:` property, an indented one-square symbol.) | Property | Values | Default | Meaning | |---|---|---|---| | `up:` | `north`/`south`/`east`/`west` (or `n`/`up`/`left`/...) | `north` when the shape is taller than wide, else `east` | the side the flight climbs toward | | `layer:` | any string | none | | Stairs along a path of squares, that turn, are a `connect:` with a `route:` and a `climb:` (see [paths](#paths-connect-with-route-and-wall-with-width)); the ![Path](tool-icons/draw.svg) **Path** tool draws them (pick **Stairs**, then up or down). ### Paths: `connect:` with `route:`, and `wall:` with `width:` ``` connect: route: (10,2)-(e 6)-(s 4) from: hall to: crypt door: type: locked connect: route: (13,2)-(s 5) width: 2 climb: down wall: (0,9)-(e 9) width: 1 ``` A **path** is drawn square by square: its points are **squares** (the square whose top-left corner is that grid point), each leg runs along a row or a column (a diagonal leg is an error), and the band is `width:` squares wide (`1` by default, up to `20`) — growing south of a leg along a row and east of a leg along a column, so each turn is a square block. - A `connect:` with a `route:` is a passage drawn where you want it: an open corridor, or a flight of stairs when it has a `climb:` (`up`: it climbs from the route's first square to its last; `down`: the other way). Floor where it runs, a wall where it meets rock. Unlike a room-to-room `connect:`, it can join **0, 1, 2 or more** rooms: every end that runs into a room or another passage gets a **door** there, and rooms along the way open onto it. Every route of a layer forms **one network**: where two of them meet or cross — a T, a crossroads — the passage stays open. Stairs get steps across each leg, winders at each turn (regular steps fanning out at equal angles from a small curve round the inner corner) and an arrow toward the top. - `from:`/`to:` are optional on a route: they name the room its first (`from:`) or last (`to:`) square runs into, and the room must exist. Either can carry a nested `door:` sub-block (`type:`, `swing:` as on a room `connect:`; `swing: inside` opens out of the passage, `outside` into it) for that end's door — with no room to name, write a bare `from:` or `to:` over the `door:`. An end with no `door:` gets an open doorway. Two routes meeting end to end share one door. - A route takes `width:`, `climb:`, `from:`, `to:` and `layer:` — not `length:`, `direction:`, `path:` or items. - `wall:` with `width:` is a solid wall along the path (a `wall:` without `width:` is a polygon). A **door** elsewhere in a passage — across it, at a junction — is a free [`door:`](#door-point-point--doors-placed-on-the-grid) on the grid line where you want it. In the visual editor, the ![Path](tool-icons/draw.svg) **Path** tool draws all three: pick **Corridor**, **Stairs** (then up or down) or **Solid wall**, and its width (**1**/**2**/**3**, 1 by default). Click square after square — the path turns where it needs to, going the longer way first — then click the last square again or press **Enter** to finish; or drag to draw a straight one in one go. The arrow keys draw too, one square at a time from the square under the pointer (**Backspace** undoes one). Right-click undoes the last square, **Escape** drops the shape. A corridor or stairs whose end runs into a room gets that room as its `from:`/`to:`. Starting on a corridor makes a branch. With **Select**, a straight path gets the side and corner handles of a room (widening it past its length turns it); a path that turns gets a handle at each end and one for its width. Double-click a wall, a flight or a corridor to turn it into another kind — corridor, stairs, solid wall or a room (`room areaN outline:`, a two-point shape of whole squares or any path) — to turn stairs around, to duplicate it or to delete it. Any selected room, shape or icon can also be copied with **Ctrl/Cmd+C** and pasted with **Ctrl/Cmd+V**: the copy lands a square aside (a room next to the original, under a fresh id like `hall2`), and pasting again sets the next copy aside from the last one. ### Moving and copying an area The ![Area](tool-icons/area.svg) **Area** tool works on a rectangle of grid squares (right-click switches to **freehand**, where you draw the outline: the squares it goes through and those it encloses): drag one to select what lies entirely inside it — rooms (with their items, the connections between them and their notes) and free-form walls, stairs, doors and `route:` passages. Then drag the selection to **move** it all by whole squares, press Ctrl/Cmd+C to **copy** it (Ctrl/Cmd+X to **cut** it) and Ctrl/Cmd+V to **paste** the copy with its top-left corner under the pointer (the pasted copy is selected, ready to be dragged), Delete to remove it, Escape to drop the selection. Rooms move and paste through their `pos:` — a map still laid out relatively is pinned first, like **Snap to grid** — and pasted rooms get fresh ids (`hall2`), which their copied connections, notes and passages follow; a passage copied without the room it ran into forgets that end. Each pasted declaration goes back into the `layer` block it came from, so it stays on its layer. The Path tool's fourth kind, **Room**, draws a room by two corners: drag from one corner square to the other, or click both — it writes `room roomN WxH pos: x,y` (on the active layer, if any). With the ![Merge](tool-icons/merge.svg) **Merge** tool, a click on a room, then on a room touching (or overlapping) it, makes the two one free-form room (`room outline: …`, keeping the first one's label and items; connections to the second one now lead to it). A hole the two leave enclosed between them is filled with a solid `wall:`, and a wall they overlap is cut down to the part that showed (a room drawn across a pillar splits it in two), so the map looks the same. A click on a drawn corridor or flight, then on another one of the same kind and width whose end meets its own (stairs climbing the same way), makes them one route with both far ends' `from:`/`to:` and doors. The pointer says why when two can't be merged; **Escape** (or a click on nothing) drops the first pick. A free-form room's handles stretch its outline, moving the points on the dragged side. Doors: double-click the door at the end of a route to pick its type, swing and leaves (single or double) (written under its `from:`/`to:`). With ![Connect](tool-icons/connect.svg) **Connect**, a click on a drawn corridor puts a door of the type picked next to the tool across it (on the nearest grid line), or sets the type of the door at its end. Double-click any free door or doorway to edit it the same way. ### `door: -` — doors placed on the grid ``` door: (10,1)-(10,2) type: closed door: (2.5,7)-(3.5,7) swing: south ``` A door anywhere along a wall line, independent of any `connect:` — the way to put doors in free-form rooms. Its two points are its ends, along one horizontal or vertical line; **halves are allowed**, so a one-square door can sit in the middle of a two-square wall (`(2.5,7)-(3.5,7)`). | Property | Values | Default | Meaning | |---|---|---|---| | `type:` | `open` \| `closed` \| `locked` \| `secret` | `open` | same looks as a `connect:` door; `open` with no swing is a plain gap with jambs | | `swing:` | `default` \| `north`/`south`/`east`/`west` \| `inside`/`outside` \| `slide-left`/`slide-right` | `default` | a hinged leaf opening toward that side (`inside` = south/east, `outside` = north/west), or a sliding panel | | `leaves:` | `1` \| `2` | `1` | one leaf or a double door, whatever the door's width (as on a `connect:` door) | | `layer:` | any string | none | | ## `layer ""` — a layer block: its content, stacking and opacity ``` layer "Ground floor" room hall outline: (0,0)-(8,5) label: "Hall" door: (8,2)-(8,3) layer "Upper floor" opacity: 50% room bridge outline: (-2,1)-(10,2) connect: from: bridge to: hall ``` A top-level block (`layer: ` is the same thing, spelled like the hexcrawl block). Every declaration indented under it — `room`, `connect:`, `wall:`, `stairs:`, `door:` — is on that layer, without repeating its name; a declaration's own `layer:` property still wins over the block's. Comments inside the block are indented too: a line at column 0 ends the block. A block with nothing in it declares an empty layer (what the editor's Layers panel writes when you create one). | Property | Values | Default | Meaning | |---|---|---|---| | `opacity:` | a percentage (`40%`) or a fraction (`0.4`) | `100%` | how opaque the whole layer is, to see the floor below through it | Layers stack in the order each one **first appears** in the text — a `layer` block or a `layer:` property, whichever comes first (first = bottom, unlayered content always below every layer). Each layer is drawn complete — floors, walls, stairs, doors, labels — before the next one, so an upper floor covers the floor below. Several blocks may name the same layer; the last `opacity:` set wins (an explicit `100%` counts). **In the visual editor**, the ![Layers](tool-icons/layers.svg) Layers panel lists every layer, top of the stack first: - type a name and press Enter (or **+**) to create a layer — it's appended as an empty `layer ""` block, so it lands on top; - the radio button (◉) picks the **active layer**: rooms and connections added with Add room / Connect go on it — written inside its block when it has one — and an item dropped into an unlayered room puts that room on it. "(none)" adds unlayered content; - the checkbox shows or hides a layer (picking a hidden layer as the active one shows it again); - the slider sets a layer's opacity for this session, starting from the DSL's `opacity:` — a view setting that doesn't change the DSL; - 🗑 deletes a layer. If anything is on it, the panel asks what to do with it: delete it too (its blocks, the declarations tagged with it, and any `connect:`/`note` left pointing at one of its rooms), move it to another layer (`layer:` properties are rewritten and blocks renamed, keeping the other layer's own `opacity:`), or move it to no layer (blocks are unwrapped). Undo brings it all back. ## `layer: ` A plain property on `room`/`connect:` and on the free-form `wall:`/ `stairs:`/`door:`, for a declaration outside any layer block: ``` room vault 4x4 layer: "Upper Floor" connect: from: entrance to: vault layer: "Upper Floor" ``` The standalone CLI's static render always shows every layer (stacked and with each layer's `opacity:`, see the `layer ""` block above). A room or connection on no layer is always visible, regardless of any layer's hidden state. Toggling a layer's visibility never changes any room's position — room placement is computed once by the layout engine from the full, unfiltered room/connection graph; layer visibility is applied only when rendering that already-laid-out map. ## `note of : ` A top-level statement (not indented under anything), independent of a room's own `label:` — a room can carry any number of notes: ``` note left of vault: A battered chest holds a scarf and a few silver coins. note north of vault: A tapestry on the wall depicting the land around the halls. ``` Renders as a One Page Dungeon-style callout: a word-wrapped text box connected by a leader line to the room it annotates, positioned outward from the room on the given `` — the same compass/screen-relative vocabulary as `connect:`'s `direction:`/`wall:` (`north`/`south`/`east`/`west` or `up`/`down`/`left`/`right`). Multiple notes on the same room+side stack along that wall. A note whose `` doesn't match any room is silently dropped rather than erroring. Callouts can protrude past the map's own bounding box on any side, so the rendered viewBox expands to fit them. See also the [dungeon tutorial](dsl-tutorial-dungeon.md.txt) for a guided introduction and the `examples/dungeon/` directory for complete maps.