# text-maps DSL — Dungeon tutorial A hands-on walkthrough: by the end you'll have built a small but complete dungeon map from nothing, one step at a time, rendering it after every step so you always see the effect of what you just typed. It teaches by doing, not by explaining every option: for the full list of properties and values, see the [dungeon reference](dsl-reference-dungeon.md.txt). For hex maps, see the [hex map tutorial](dsl-tutorial-hex.md.txt). **Before you start**, open the app and have somewhere to render each step: - Browser: run `make dev`, open `http://localhost:8082`, and paste each step's DSL into the textarea — the map updates live. - Or the CLI, if you'd rather work from a text file: ```sh make native native/target/scala-3.3.3/text-maps-native -i map.txt -o map.svg # re-run after each edit ``` **The editor's tools.** Most steps can also be done with the visual editor's tools; each step names the tool it uses. The icon, the map kind and the behaviour of every tool are listed once, in [the editor's tools](dsl-reference.md.txt#the-visual-editors-tools) table of the reference. --- ## Step 1: an empty dungeon Every dungeon map starts with one line: ``` map dungeon "The Sunken Keep" ``` Render it. You'll get a valid, empty map — a title and nothing else. That's expected: a `map` header alone is already a complete document. **Result:** ![Step 1 result](dsl-tutorial-images/dungeon-step1.svg) [Try it live](https://text-maps.tyrcho.com/#map/LYQwDgBAJgrgdgcwKYHs4QEQBUAWSIDK8A1kugNJJJgYBQQA) ## Step 2: add a room Add a `room` declaration below the header. A room needs an id (you'll reference it later) and a size in grid squares: ``` map dungeon "The Sunken Keep" room entrance 4x4 ``` Render it. You now have one floor tile on the map, no label yet. **Result:** ![Step 2 result](dsl-tutorial-images/dungeon-step2.svg) [Try it live](https://text-maps.tyrcho.com/#map/LYQwDgBAJgrgdgcwKYHs4QEQBUAWSIDK8A1kugNJJJgYBQtATiisBGQC4MhwDG+ALAA9+tIA) ## Step 3: label it Indent a `label:` property under the room (indentation is what attaches a property to the declaration above it): ``` map dungeon "The Sunken Keep" room entrance 4x4 label: "Gatehouse" ``` Render it — the room now shows its label. **Result:** ![Step 3 result](dsl-tutorial-images/dungeon-step3.svg) [Try it live](https://text-maps.tyrcho.com/#map/LYQwDgBAJgrgdgcwKYHs4QEQBUAWSIDK8A1kugNJJJgYBQtATiisBGQC4MhwDG+ALAA9+tCBAA2IAEZJxALkwBxEOyQ4UMAM5I6QA) Once a map has several rooms, a dungeon numbers them and lists the labels in a legend below the map. To write one room's label inside the room instead, add `label-style: inline` to it (or double-click the room in the visual editor and pick **In room**): ``` room entrance 4x4 label: "Gatehouse" label-style: inline ``` ## Step 4: add a second room and connect them A `connect:` block joins two rooms by id (`from:`/`to:`) and automatically places the second one next to the first — you don't position rooms yourself, the layout engine does that from the connections, and no room is special: a connection places its two rooms the same way whichever end you read it from. A `connect:` always has to say what's between the two rooms, though: give it a `length:` (grid units) for an actual corridor, or leave it out entirely (same as `length: 0`) for the two rooms to sit glued together with nothing but a doorway between them: ``` map dungeon "The Sunken Keep" room entrance 4x4 label: "Gatehouse" room great_hall 8x6 label: "Great Hall" connect: from: entrance to: great_hall length: 2 ``` Render it. Two rooms, one corridor, one open doorway. **Result:** ![Step 4 result](dsl-tutorial-images/dungeon-step4.svg) [Try it live](https://text-maps.tyrcho.com/#map/LYQwDgBAJgrgdgcwKYHs4QEQBUAWSIDK8A1kugNJJJgYBQtATiisBGQC4MhwDG+ALAA9+tCBAA2IAEZJxALkwBxEOyQ4UMAM5I6jZqwQMkKgPo4Q48RAAcggGyiJ02QoyKjKiAAkL43TzQ4JB52OUcAMyZgBQ4uXiRHdhQFQ2N2M19HcTIEdhwFACZaIA) In the visual editor, the ![Connect](tool-icons/connect.svg) **Connect** tool writes this block for you: click a room, then another — rooms that touch get a doorway, rooms apart a corridor, routed so every room stays where it's drawn. The buttons next to it pick the door: ![Open](tool-icons/door-open.svg) open, ![Closed](tool-icons/door-closed.svg) closed, ![Locked](tool-icons/door-locked.svg) locked, ![Secret](tool-icons/door-secret.svg) secret. (![Add room](tool-icons/add-room.svg) **Add room** adds a room already connected to the one you click.) Two rooms can be connected more than once: pick the same pair again and the new door or corridor is laid beside the first one (its `door:` gets a `position:`). ## Step 5: make that doorway a locked door Give the `from:` end its own nested `door:` sub-block, indented one level further, with a `type:` property: ``` map dungeon "The Sunken Keep" room entrance 4x4 label: "Gatehouse" room great_hall 8x6 label: "Great Hall" connect: from: entrance door: type: locked to: great_hall length: 2 ``` Render it — the doorway now draws as a locked door instead of a plain open gap. (Try `secret` too, and see how it disappears into the wall.) Only the `from:` end got a `door:` here, so the `to:` end draws the same locked door — give `to:` its own `door:` sub-block to make the two ends independently typed. **Result:** ![Step 5 result](dsl-tutorial-images/dungeon-step5.svg) [Try it live](https://text-maps.tyrcho.com/#map/LYQwDgBAJgrgdgcwKYHs4QEQBUAWSIDK8A1kugNJJJgYBQtATiisBGQC4MhwDG+ALAA9+tCBAA2IAEZJxALkwBxEOyQ4UMAM5I6jZqwQMkKgPo4Q48RAAcggGyiJ02QoyKjKiAAkL43TzQ4JB52OUcAMyZgBQ4uXiRHMShmBjCxdIh2AE8wJAVxFB5SKEd2FAVDY3YzX0dxMgR2HAUAJlogA) ## Step 6: add a third room with a different shape ``` map dungeon "The Sunken Keep" room entrance 4x4 label: "Gatehouse" room great_hall 8x6 label: "Great Hall" room vault 4x4 label: "Vault" shape: circular connect: from: entrance door: type: locked to: great_hall length: 2 connect: from: great_hall door: type: secret to: vault length: 2 ``` Render it. Three rooms, a locked door, and a secret door leading to a round vault. Other shapes: `cave` (an irregular outline), `half-disc north` (an apse: the round side faces north, the flat wall south) and `quarter-disc south-east` (a corner tower whose arc bulges south-east). In the visual editor, double-click a room to change its shape from the same list as when adding one. **Result:** ![Step 6 result](dsl-tutorial-images/dungeon-step6.svg) [Try it live](https://text-maps.tyrcho.com/#map/LYQwDgBAJgrgdgcwKYHs4QEQBUAWSIDK8A1kugNJJJgYBQtATiisBGQC4MhwDG+ALAA9+tCBAA2IAEZJxALkwBxEOyQ4UMAM5I6jZqwQMkKgPo4Q48RAAcggGyiJ02QoyKjKiAAkL43UxYIADcQGHF2CCERMUkZeUwANVDwujFNczAkBR4ASwYeMJAGeh40OCQedjlHADMmYAUOLl4kRzEoZgZqsR6IdgBPTIVxFB5SKEd2FAVDY3YzX0dxMgR2HAUAJhKyiqra+pmPefNLNuhO7t6+wayIbR4jdknp4OSnmJW1zdogA) ## Step 7: furnish a room with an icon Import an Iconify icon set once, near the top of the file, then reference any icon in it as `.`: ``` map dungeon "The Sunken Keep" import icon-sets.iconify.design/game-icons as gi room entrance 4x4 label: "Gatehouse" room great_hall 8x6 label: "Great Hall" gi.ionic-column: north room vault 4x4 label: "Vault" shape: circular connect: from: entrance door: type: locked to: great_hall length: 2 connect: from: great_hall door: type: secret to: vault length: 2 ``` Render it — a column icon appears near the Great Hall's north wall. Browse more icons at [icon-sets.iconify.design](https://icon-sets.iconify.design) (any set works, not just `game-icons`) and try adding one of your own. In the visual editor, the ![Add item](tool-icons/place.svg) **Add item** palette offers a curated selection of `game-icons` that fit inside a room (furniture, light, storage, traps, remains), plus stairs, ladders and windows; the hexcrawl ![Place POI](tool-icons/place.svg) **Place POI** palette offers overland landmarks instead. Need an icon that isn't there? Find it on [icon-sets.iconify.design/game-icons](https://icon-sets.iconify.design/game-icons/) (typing in the palette's search box with no match links straight to a search there), then paste its name (`stone-throne`) or its page link into the palette's **More icons** box: it's checked, added under **My icons** for that kind of map, and selected, ready to click onto the map. In the text, any `game-icons` name works as `gi.` without going through the palette at all. Stairs, spiral stairs and ladders can sit on a precise square the same way: `stairs: down east 3,1` puts a flight leading east on the fourth column, second row; without a `col,row` they're centred in the room. Any item except a window can also be turned: add `rot: 90` (or any angle, clockwise) to its line — `gi.table: 3x1 1,2 rot: 90` stands a long table upright, `ladder: up rot: 45` sets a ladder at a slant. In the editor, select the item and press **R** for a quarter turn (**Shift+R** the other way), or double-click it to type an exact angle. That double-click popup also resizes an icon and swaps an item for another, picked from the same list as the Add item tool, without moving it. You can also grab a selected item directly: the cursor shows resize arrows on an icon's handles and a curved arrow just outside its corners, to turn it. Rooms turn too, a quarter turn at a time (R, or drag just outside a selected room's corner), with everything inside them. To move an item once it's placed, pick **🖱 Select** and drag it: drop it elsewhere in its room (it lands on the grid square under the cursor, or against the wall it's dropped near) or in another room. A click selects it instead (its line is selected in the text too, scrolled into view); the arrow keys then nudge it a square and Delete removes it. The same goes for every other element on the map — rooms, doors, corridors, and the free-form walls, stairs and doors of Step 9. To move several at once, ![Area](tool-icons/area.svg) **Area** selects everything inside a rectangle you drag (right-click to draw it freehand): drag the selection to move it, or Ctrl/Cmd+C (or X to cut) and Ctrl/Cmd+V to paste a copy (with fresh room ids) under the pointer. Items go in corridors too: under a `connect:` block, the same `stairs:`, `ladder:` or icon line as in a room (`ladder: down 2,0` counts squares from the corridor's top-left square). In the editor, ![Add item](tool-icons/place.svg) **Add item** drops one in a corridor and ![Select](tool-icons/select.svg) **Select** moves it along the corridor or into a room. **Result:** ![Step 7 result](dsl-tutorial-images/dungeon-step7.svg) [Try it live](https://text-maps.tyrcho.com/#map/LYQwDgBAJgrgdgcwKYHs4QEQBUAWSIDK8A1kugNJJJgYBQAlsGCgE4AuE9AxmgLQDOSNvwB03NPQBmATxFQk-egjgB6BCGBJe4uPwgg9CerVosUKYBDJsWIOF3wAWAB6PaECABsQAIySeALkwAcRA2JBwUGEE6U3NLBBYkMIB9HBBPTwgADmcANncvX38gjGCksIgACQzPOg8jMQkuXh5PGGA4ILhWNhwTMwsIADcQGE8OFzcPbz9AzAA1MYn6iH50sCQgrnoWLnGQFhMeODgkLjYAwskzYCDrW3skQo8ocxYrjy+INmlNoM8KC4pCghTYKCCiWSbDStUKnjICD6QQATMc0GcLp8IDcLJCKjD0pkXtB3tjvr9-mtzkk2GCISNlnSZojkRA0UA) ## Step 8: pin rooms to the grid So far every room's position came from its connections. You can instead give a room an absolute position — the grid square of its top-left corner, like a hex's coordinates — with the keyed header form `room size: x pos: ,`: ``` map dungeon "The Sunken Keep" room entrance size: 4x4 pos: 0,1 label: "Gatehouse" room great_hall size: 8x6 pos: 6,0 label: "Great Hall" room vault size: 4x4 pos: 17,8 label: "Vault" shape: circular connect: from: entrance door: type: locked to: great_hall connect: from: great_hall door: type: secret to: vault ``` Render it. Every room now sits exactly on the grid, and the corridors follow from where the rooms are: straight where two rooms face each other, with an automatic bend where they don't — no `length:` or `path:` needed. This is the handiest form for drafting a map by hand (or having an agent draft it) and then fine-tuning it in the visual editor, where dragging a pinned room moves it one grid square at a time. ![Snap to grid](tool-icons/snap.svg) **Snap to grid** writes these `pos:` for you, from where each room is drawn now. Rooms without a `pos:` still work in the same map: they are placed from their connections, as before. Add `coords: on` under the `map` line (or tick Grid coordinates in **Map settings**) to name the squares like a chessboard: column letters along the top from `A` at the left, row numbers down the left from 1 at the top, so you can point at square `B7`. **Result:** ![Step 8 result](dsl-tutorial-images/dungeon-step8.svg) [Try it live](https://text-maps.tyrcho.com/#map/LYQwDgBAJgrgdgcwKYHs4QEQBUAWSIDK8A1kugNJJJgYBQtATiisBGQC4MhwDG+AzgEsAXkgBcEACwAPSRDAp+EgAwAaAIy0IEADYgARkh0SMAcRDskOFDH5I6jZqwQMkFgPo4QOnRCGiJAA5pADZ5RQkQ1WUtXQMjE1NXCwgACW8dByYWCAA3EBgddj8RcSlZcKUIdQB2VUDYvUNjTAA1AqK6bX4vMDKeQQYeQpAGeh40OCQedjFYgDMmYAkOLl4kWO0oZgY57X2IdgBPPokdFB5SKFj2FAkXN3ZPDPHJ6dmFpfvkp68fTegOz2B0OJzKdh4rnYNzueQ60KAA) ## Step 9: trace a plan free-form When you're copying a plan from a sketch, it's often easier to draw each shape straight on the grid than to build it from boxes and connections. Start a `map building` (thin walls, plain background) and give rooms an `outline:` — grid points, like a hexcrawl river's waypoints, either absolute `(x,y)` or a move from the previous point such as `(e 4)`: ``` map building "The Old Mill" compass: top-right scale: 2 m import icon-sets.iconify.design/game-icons as gi room hall outline: (0,0)-(e 10)-(s 4)-(w 3)-(s 3)-(w 7) label: "Hall" gi.fountain: 2x2 1,1 room passage outline: (10,1)-(16,2) label-style: none wall: (3,-1)-(6,0) stairs: (16,0)-(18,4) up: east door: (10,1)-(10,2) type: closed door: (2.5,7)-(3.5,7) swing: south ``` Render it. The hall is L-shaped, the passage is just a narrow room with no label (two points make a rectangle), `wall:` draws a hatched thick wall, `stairs:` a flight spanning several squares that climbs east, and each `door:` sits exactly on the wall line between its two points — halves are allowed, so the south door is centred on a grid line. A swinging door has one leaf; add `leaves: 2` for a double door. The fountain takes both a size and a position, and the header's `compass:` and `scale:` add a compass rose and a scale bar (one square = 2 m). Corridors and stairs can also follow a **path** of squares that turns, drawn where you want it: a `connect:` with a `route:` instead of rooms to join. `connect:` then `route: (16,5)-(e 4)-(s 3)` is an open passage one square wide; add `climb: up` (or `down`) and it is a flight of stairs. Each end that runs into a room or another passage gets a door, so a route can join no room, one, two or more; name the rooms with `from:`/`to:` to give their doors a `door:` sub-block, as for any `connect:`. A `wall:` given a `width:` reads its points the same way. Routes join up, so a branch makes a T (see the [reference](dsl-reference-dungeon.md.txt#paths-connect-with-route-and-wall-with-width)). In the visual editor, the ![Path](tool-icons/draw.svg) **Path** tool draws them: pick Corridor, Stairs (up or down) or Solid wall and a width, then click square after square and click the last one again (or drag a straight run, or use the arrow keys). Its **Room** kind draws a room from one corner to the other, and the **Merge** tool joins two corridors, two flights or two touching rooms into one (click one, then the other). With **Select**, drag a wall, flight or corridor to move it, or its handles to resize it; double-click it to turn it into another kind or turn stairs around, and double-click the door at a route's end to change it. **Connect** puts doors in a drawn corridor. **Result:** ![Step 9 result](dsl-tutorial-images/dungeon-step9.svg) [Try it live](https://text-maps.tyrcho.com/#map/LYQwDgBARgrglgGwCZwHYHMICIAqALAUwgHlkIBZRBLAKAggGMB7YMEAZ3YC4IAXJsAFoATnHR5edCOwYgEBHgCYIwGjTismw3hDjNUg9gV7sAdHqao4AMwCeppAXZjUAenQhgBQRdTsIHBDocGrCTCwQeHIIEEwwvAhoChAAFAAMADRpAJSCKUQAjDl5-gAsuSkA7hAAzBX+dXnVAOzZUgggUAQIPFgAEtG09MGm1nGovCBoSgAeygUZBaHhwBBsnCDoRHEJSTwpRYsVBQBsGYpt9B1dCIa8tvI8qJYEapXR+zUZggUVZzlqdiTODCbipU5ZY4ADgy5SkMDAPAIHEkNCQ4WE+0OvzyhwuUnuYGSDAQTCMSDRGP2ilMAFYMq08jU6QzLtJKmh0Dx2Ds8DQgA) ## Step 10: stack two floors A `layer ""` block puts everything indented under it on that layer — no need to repeat the layer's name on each room. Layers stack in the order they appear (first = bottom), and a block can say how opaque its layer is: ``` map building "The Old Mill" layer "Ground floor" room hall outline: (0,0)-(8,5) label: "Hall" room store outline: (8,1)-(11,4) label: "Store" door: (8,2)-(8,3) layer "Upper floor" opacity: 50% room bridge outline: (-2,1)-(10,2) label: "Bridge" stairs: (-2,-2)-(-1,1) up: north ``` Render it. The upper floor's bridge is drawn over the hall, half transparent, so you can see how the two floors line up. In the visual editor, the ![Layers](tool-icons/layers.svg) **Layers** panel lists the floors: tick a floor to show or hide it, slide its opacity while you work, pick the active floor (◉) that new rooms and doors go on, create a floor with **+** or delete one with 🗑. (A single declaration can also carry its own `layer: ""` property instead of sitting in a block.) **Result:** ![Step 10 result](dsl-tutorial-images/dungeon-step10.svg) [Try it live](https://text-maps.tyrcho.com/#map/LYQwDgBARgrglgGwCZwHYHMICIAqALAUwgHlkIBZRBLAKBoRAE8CAnbAcRYHsZUkIAZgi5cWtCBG5dgEPCAQIIPAC4I0BAFwQAFAAYANLoCUAWm0AOfQFYjNCRIZQCCLVgAS86nQlSZAZ2VRIhU1VE0dSwBGU21IyP0AFlt7CEdnVwBlQJYCWjsIJBEWLQt9ACYYywBmW3omVmwAVTAwBqEi8SUwEABjOGVGLStdAFJvSREZKBY4JHRgmFV1EpMy-WizSIMK-IcQJxdsACEZudzxgJA4Fj8VtdWYk3jo3YgYMC1UUWU8IA) ## Step 11: let the generator draw one, then make it yours Instead of writing every room, you can ask for a whole dungeon: replace the rooms and connections with one `generate dungeon` line. `rooms:` is how many rooms, and `seed:` picks one dungeon among all possible ones (the same seed always draws the same map, another seed a different one): ``` map dungeon "The Endless Halls" compass: top-right scale: 5 ft generate dungeon rooms:12 seed:45 ``` **Result:** ![Step 11 result](dsl-tutorial-images/dungeon-step11.svg) [Try it live](https://text-maps.tyrcho.com/editor.html#map/the-endless-halls/LYQwDgBAJgrgdgcwKYHs4QEQBUAWSICicUANkgM7kQASIJJ5GAUBBAMYrBgiUBcEAFxRgAtACcAlghwCWEcmzpJ+AVggAzWU2RwkYkAPyxEqdGJSdyvAIwAmeUiRReAFhVMgA) Try a few seeds until you like one. To change a room, open it in the editor and click **Expand into rooms** in the hint bar under the map: the `generate dungeon` line is replaced with the `room` and `connect:` declarations it stands for (`room entrance 3x5`, `room room_1 3x4`, …), which draw exactly the same map: each connection gets the `direction:` and `length:` (or `path:`) that keeps its room in place, so dragging one room in the editor afterwards leaves all the others where they are. From there it's an ordinary dungeon: label the rooms, add doors and icons as in the steps above, or pin it to the grid (Step 8) to move rooms one square at a time. **You now have a complete, playable dungeon.** From here, the [dungeon reference](dsl-reference-dungeon.md.txt) covers every remaining option: stairs, windows, procedural generation (`generate dungeon`), corridor width and multi-segment `path:` routes, per-end door swings/positions/walls (including sliding doors), custom room contours, absolute `pos:` positioning, the free-form shapes (outlines, rings, walls, stairs and doors), the full icon-positioning grammar, and `layer:` for grouping content into the visual editor's show/hide groups.