# text-maps DSL — Hex map tutorial A hands-on walkthrough: by the end you'll have built a small but complete hexcrawl 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 [hex map reference](dsl-reference-hex.md.txt). For dungeons and buildings, see the [dungeon tutorial](dsl-tutorial-dungeon.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.** Every step 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 hexcrawl map ``` map hexcrawl "Borderlands" ``` Render it — an empty map, same idea as the dungeon header. **Result:** ![Step 1 result](dsl-tutorial-images/hexcrawl-step1.svg) [Try it live](https://text-maps.tyrcho.com/#map/LYQwDgBAFgpgHgYwE4gO4BsICIBCB7JAExiXRADtCBnLAKCA) ## Step 2: place one hex Hexcrawl coordinates are `(q, r)` axial pairs you choose yourself — there's no automatic layout, because the hex grid *is* the geography: ``` map hexcrawl "Borderlands" hex 0,0 terrain: plains ``` Render it. One filled hex, colored and textured for `plains`. In the editor: ![Paint terrain](tool-icons/terrain.svg) **Paint terrain**, pick Plains, click a hex. **Result:** ![Step 2 result](dsl-tutorial-images/hexcrawl-step2.svg) [Try it live](https://text-maps.tyrcho.com/#map/LYQwDgBAFgpgHgYwE4gO4BsICIBCB7JAExiXRADtCBnLAKFtjggAYAaZ2iCAFxJQEtyALghgygqrSA) ## Step 3: label it, and place a neighbor ``` map hexcrawl "Borderlands" hex 0,0 terrain: plains label: "Kingsport" hex 1,0 terrain: forest ``` Render it — two adjacent hexes, different terrain colors, one labeled. Notice the terrain fill isn't a flat hexagon: it's traced as one organic, hand-drawn-looking shape per connected region. In the editor, ![Place POI](tool-icons/place.svg) **Place POI** puts an icon on a hex (pick it in its flyout), and a click on a placed icon names it. Its **Text only** pick writes a name with no icon (a `hex` with just a `label:`). **Result:** ![Step 3 result](dsl-tutorial-images/hexcrawl-step3.svg) [Try it live](https://text-maps.tyrcho.com/#map/LYQwDgBAFgpgHgYwE4gO4BsICIBCB7JAExiXRADtCBnLAKFtjggAYAaZ2iCAFxJQEtyALghgygqpwhkARjHQisAaUEBzKmALc6DeBACM7KbyQDhEAGYEYVbrSA) ## Step 4: fill a whole area at once with a zone Instead of declaring many individual hexes, a `zone` fills a rectangular range in one go — an axis-aligned rectangle on screen by default — and can carry its own single label, placed at the zone's center by default: ``` map hexcrawl "Borderlands" hex 0,0 terrain: plains label: "Kingsport" zone (2,-2)-(4,0) terrain: forest label: "Whispering Woods" ``` Render it — a whole forest region appears, with one label for the region rather than one per hex. In the editor: pick Forest on the front swatch of the **Terrain** group, then ![Terrain zone](tool-icons/zone.svg) **Terrain zone** and click two opposite corners. The editor holds two terrains, as Paint holds two colours: every terrain tool paints the front one with the left button and the back one with the right button, and the terrain is picked apart from the tool. To repaint a region drawn already, ![Fill](tool-icons/fill.svg) **Fill** floods the clicked hex's whole area of one terrain, as Paint's bucket does (Shift: that terrain everywhere); ![Pick terrain](tool-icons/pick.svg) **Pick terrain** (or Alt+click) takes the terrain of the hex you click, and ![Magic wand](tool-icons/wand.svg) **Magic wand** selects such areas (Shift adds one) to grow them hex by hex and repaint them. ![Line](tool-icons/line.svg) **Line**, ![Hexagon](tool-icons/hexagon.svg) **Hexagon** and ![Spray](tool-icons/spray.svg) **Spray** paint like their Paint namesakes. **Result:** ![Step 4 result](dsl-tutorial-images/hexcrawl-step4.svg) [Try it live](https://text-maps.tyrcho.com/#map/LYQwDgBAFgpgHgYwE4gO4BsICIBCB7JAExiXRADtCBnLAKFtjggAYAaZ2iCAFxJQEtyALghgygqpwhkARjHQisAaUEBzKmALc6tAF55yMCAAoATKwC0pgJQXjAFnbWpvJAOEQAZgRhVuU2XlFAHUofg0SNQhgvDxqOiA) ## Step 5: connect places with a road A road/river/path is one line with a waypoint chain — every hex between each pair of waypoints fills in automatically, so a route across many hexes only needs its turning points: ``` map hexcrawl "Borderlands" hex 0,0 terrain: plains label: "Kingsport" zone (2,-2)-(4,0) terrain: forest label: "Whispering Woods" road: (0,0)-(2,-2) ``` Add that line to the bottom of the file and render it. A road now runs from Kingsport to the forest. In the editor: ![Draw](tool-icons/draw.svg) **Draw** with ![Road](tool-icons/road.svg) Road picked, click Kingsport, then the forest's corner, then that hex again to finish. **Result:** ![Step 5 result](dsl-tutorial-images/hexcrawl-step5.svg) [Try it live](https://text-maps.tyrcho.com/#map/LYQwDgBAFgpgHgYwE4gO4BsICIBCB7JAExiXRADtCBnLAKFtjggAYAaZ2iCAFxJQEtyALghgygqpwhkARjHQisAaUEBzKmALc6tAF55yMCAAoATKwC0pgJQXjAFnbWpvJAOEQAZgRhVuU2XlFAHUofg0SNQhgvDxqHSQ8EEIRYzZmWzNLG1ogA) ## Step 6: add a river with its own color Rivers default to a tapering blue ribbon; override any of the three kinds' colors with an indented `color:` property if you want something else: ``` map hexcrawl "Borderlands" hex 0,0 terrain: plains label: "Kingsport" zone (2,-2)-(4,0) terrain: forest label: "Whispering Woods" road: (0,0)-(2,-2) color: gray river: (0,0)-(-1,0) ``` Add the river line and render — Kingsport now also sits at a river's edge. In the editor, pick ![River](tool-icons/river.svg) River next to ![Draw](tool-icons/draw.svg) **Draw**. Any road, river or path can also take an indented `name: "River Ash"`, written along the line in its own color. **Result:** ![Step 6 result](dsl-tutorial-images/hexcrawl-step6.svg) [Try it live](https://text-maps.tyrcho.com/#map/LYQwDgBAFgpgHgYwE4gO4BsICIBCB7JAExiXRADtCBnLAKFtjggAYAaZ2iCAFxJQEtyALghgygqpwhkARjHQisAaUEBzKmALc6tAF55yMCAAoATKwC0pgJQXjAFnbWpvJAOEQAZgRhVuU2XlFAHUofg0SNQhgvDxqHSQ8EEIRYzZmWzNLGykEPHQCEVUUAE96JH4ANxJU9MyLAEYnWiA) ## Step 7: assign territory with a country block A country is a `country:` property on every hex or zone that belongs to it. The border between countries is computed automatically wherever two adjacent hexes disagree — you never draw a border line yourself: ``` map hexcrawl "Borderlands" hex 0,0 terrain: plains label: "Kingsport" country: Astoria zone (2,-2)-(4,0) terrain: forest label: "Whispering Woods" country: Astoria hex -1,0 terrain: water road: (0,0)-(2,-2) color: gray river: (0,0)-(-1,0) ``` Render it. Both the plains hex and the forest zone now belong to Astoria — try adding a second country's worth of hexes/zones nearby (with a different `country:` name) and watch a border line appear exactly where they touch. In the visual editor, ![Country](tool-icons/country.svg) **Country** paints them: pick ![hex by hex](tool-icons/terrain.svg) (hex by hex) or ![by zone](tool-icons/zone.svg) (by zone) next to it and click the map. A new country asks for its name right on the first hex you paint (or a zone's second corner); type it and press Enter, and that name keeps painting until you change it. Painted hexes go into the country's `country:` block (a new block at the end for a new country), taking their terrain along, rather than getting a `country:` line each. To paint an existing country, type or pick its name in the flyout; its **+** starts another new country. The ![Select](tool-icons/select.svg) **Select** tool edits and removes them: click a road, river or path (or click the same hex again to cycle to the country under it), then press **Delete** or use the ![Delete](tool-icons/delete.svg) **Delete** button that appears above the map. Deleting a road/river/path removes its whole declaration; deleting a country removes every `country:` assignment to it and unwraps its `country:` block, so the terrain and icons stay. With a country selected, the bar above the map edits it: ![Move](tool-icons/move.svg) **Move** (the default) drags the whole country, shifting every one of its hexes by the same offset; ![Hex](tool-icons/hex.svg) **+** / ![Hex](tool-icons/hex.svg) **−** add or remove the hexes you click or drag over; ![Zone](tool-icons/zone.svg) **+** / ![Zone](tool-icons/zone.svg) **−** add or remove a zone, picked like the Zone tool's (click both corners, right-click to cycle the axis, then cancel, or just drag). The dropdown switches to another country without leaving the tool, and the **Rename…** field renames the selected country everywhere in the text (type the new name, then Enter). A hex that changes country is transferred: it leaves the other country's declaration and joins the new country's `country:` block, terrain and all (see the reference). Dragging a road point drops the waypoints the route no longer needs (a point the straight line between its neighbors crosses anyway). To move or copy a whole region, use ![Area](tool-icons/area.svg) **Area**: drag a rectangle (right-click for another shape, or to draw it freehand), then drag it elsewhere, or Ctrl/Cmd+C (or X to cut) and Ctrl/Cmd+V to paste a copy under the pointer — terrain, labels, icons and roads go along, each on its layer, while borders stay put unless a whole country is inside. An island cut out of the sea leaves sea behind it. A moved icon or road point stays selected, so you can drag it again right away, and deleting an icon also deletes its hex's label (untick the box in the message that appears to keep the label). **Result:** ![Step 7 result](dsl-tutorial-images/hexcrawl-step7.svg) [Try it live](https://text-maps.tyrcho.com/#map/LYQwDgBAFgpgHgYwE4gO4BsICIBCB7JAExiXRADtCBnLAKFtjggAYAaZ2iCAFxJQEtyALghgygqpwhkARjHQisAaUEBzKmALc6XBHgCu5bkgCeIgIJVuBfiHoAvPORgQAFACZWAWncBKL64ALOy+UrxIAsIQAGYEMFZSsvKKAOpQ-BokahApeHjUOhB6hsZmEJbWSLb0jBBeAIzsYXwggiKoIOH0SHgghCKubMz+Ht5+UnroBCKqKCbd-ABuJANDIw0htEA) Once a country spans several zones, the block form saves repeating the name: everything indented under `country:` defaults to that country. This listing shows only the country part of the map above (the same hex and zone, without the water hex, road and river), so its result differs: ``` map hexcrawl "Borderlands" country: Astoria hex 0,0 terrain: plains label: "Kingsport" zone (2,-2)-(4,0) terrain: forest label: "Whispering Woods" ``` **Result:** ![Step 7 (block form) result](dsl-tutorial-images/hexcrawl-step7-country-block-form.svg) [Try it live](https://text-maps.tyrcho.com/#map/LYQwDgBAFgpgHgYwE4gO4BsICIBCB7JAExiXRADtCBnLAKFoTwFdyAXJATwC4IBBK1gQCWIWhGjwIABgA0UseIisSKIeR5gyaqgvFkARjHQ8sAaTUBzKmAKs64gF55yMCAAoATDIC0HgJTebgAscn66SiogajwAZgQwAuEGRiYA6lBC1iSWEKl4eNR0QA) ## Step 8: add a scale and a compass rose Indented properties right under the `map hexcrawl` header apply to the whole map — the same `compass:` and `scale:` a building plan's header takes. `scale:` says how far one hex is from its neighbor (centre to centre), and draws a scale bar spanning a round distance: ``` map hexcrawl "Borderlands" compass: top-right scale: 10 km hex 0,0 terrain: plains label: "Kingsport" country: Astoria zone (2,-2)-(4,0) terrain: forest label: "Whispering Woods" country: Astoria hex -1,0 terrain: water road: (0,0)-(2,-2) color: gray river: (0,0)-(-1,0) ``` Render it. A compass rose sits in the top-right corner and a scale bar labelled `50 km` (5 hexes, "1 hex = 10 km") in the top-left, in a strip added above the hexes so neither hides any terrain. Both take an optional corner (`scale: 6 miles bottom-left`), and `compass:` an angle that turns north clockwise (`compass: top-right 30`). In the editor, ![Map settings](tool-icons/map-settings.svg) **Map settings** ticks both on. One more header line, `coords: on` (Grid coordinates in **Map settings**), names the hexes like a chessboard: letters for the columns along the top, from `A` at the left, and numbers for the rows down the left side, from 1 at the top, so you can point at hex `B7`. If the roads, borders or names are too thin to read at your zoom level, `line-width: 1.5` and `text-size: 1.5` (the **Line width** and **Text size** controls in **Map settings**) draw them half as thick or big again. A single road, label or country can be sized the same way with its own `line-width:` or `text-size:` line, multiplied by the header's (in the editor: select it, then **Line** and **Text** in the selection bar); see [Element sizes](dsl-reference-hex.md.txt#element-sizes-line-width-and-text-size). If your map is a whole world, `topology: sphere` or `topology: torus` (**World** in **Map settings**) says so: each row then wraps around, the **Turn** slider spins the world to bring any place to the middle (written as `turn: 90` in the header; the hexes keep their coordinates), and **File ▸ Open as globe in new tab** shows it as a 3D globe (see [World maps](dsl-reference-hex.md.txt#world-maps-topology-sphere-and-torus)). **Result:** ![Step 8 result](dsl-tutorial-images/hexcrawl-step8.svg) [Try it live](https://text-maps.tyrcho.com/#map/LYQwDgBAFgpgHgYwE4gO4BsICIBCB7JAExiXRADtCBnLAKAggT2DBCqoC4IAXPMAWiQBLAOZRu9CFQQh0MLgEYADBADWwWrVhwISgDRLJ3EiiHkuYMmaqSyAIxjouWANJmRVMAW50GTAK7k3EgAnlwAglS8wiCaAF545DAQABQATHr8aQCU-CkALAbZRiYgZlwAZgQwUbYgDk7YAOpQQp4k7hBNeHjUvox4gcFhEJHRQrFa8BD8CgYlSKbmEKggxkiaSHgghFwp+kq56Zk5kkzoBFwiKCGbQgBuJHsHR7NFtEA) **You now have a complete, small hexcrawl map** with terrain, a labeled settlement, a labeled region, a road, a river, a country border, a scale and a compass rose. From here, the [hex map reference](dsl-reference-hex.md.txt) covers everything else: the full terrain list, polygon and relative-move zone shapes, `axis:` (three alternate parallelogram zone shapes along the hex grid's own axes, instead of the default on-screen rectangle), POI icons on hexes/zones, `layer:` for the visual editor's show/hide groups, and the `hide-terrain:`/`hide-poi:`/`hide-paths:` declaration-order controls.