98 lines
3.3 KiB
Markdown
98 lines
3.3 KiB
Markdown
# Board format
|
||
|
||
The board is authored as **one 8x8 quadrant** (`board/quadrant.txt`, the top-left corner of
|
||
the board). The tooling rotates it 90° clockwise three times to build the full 16x16 board,
|
||
so every corner is identical by construction.
|
||
|
||
```
|
||
uv run dojo board validate # check board/quadrant.txt against the rules
|
||
uv run dojo board render -o board/board.txt # write the full board (generated, never edit)
|
||
```
|
||
|
||
Exit codes: `0` OK (warnings allowed), `1` design errors, `2` format errors or missing file.
|
||
|
||
## Notation
|
||
|
||
Classic ASCII maze notation. Each cell is 3 characters wide with its code in the middle;
|
||
walls sit between cells.
|
||
|
||
```
|
||
+---+---+---+
|
||
| S S | . |
|
||
+ +---+ +
|
||
| S 1 ? |
|
||
+---+---+---+
|
||
```
|
||
|
||
| Element | Walled | Open |
|
||
|---|---|---|
|
||
| Corner | `+` (always) | — |
|
||
| Between two rows | `---` | three blanks |
|
||
| Between two columns | `\|` | one blank |
|
||
|
||
- Lines starting with `#` and blank lines are ignored.
|
||
- Trailing blanks may be stripped by your editor; a missing character at the end of a line
|
||
reads as open.
|
||
- The quadrant file is 17 lines of 33 characters.
|
||
|
||
## Cell codes
|
||
|
||
| Code | Meaning |
|
||
|---|---|
|
||
| `S` | Safe Room |
|
||
| `D` | Central Dojo |
|
||
| `.` | Tatami |
|
||
| `A` | Allenamento |
|
||
| `F` | Fatica |
|
||
| `?` | Nebbia del Dojo |
|
||
| `P` | Passo Falso |
|
||
| `K` | Sfida |
|
||
| `1`–`9` | Tunnel; the two cells with the same digit are a pair |
|
||
|
||
## Quadrant rules (format errors — the board cannot be built)
|
||
|
||
- Exactly 8x8 cells, only the codes above.
|
||
- **Top and left borders** are the outer border of the board: fully walled.
|
||
- **Right and bottom borders are seams** shared with the neighbouring quadrants. Rotation maps
|
||
the bottom seam onto the right seam, so the right border at row *i* must equal the bottom
|
||
border at column *i*.
|
||
- `D` cells are exactly rows 6–7, columns 6–7 (the quadrant's share of the 4x4 Dojo).
|
||
- Each tunnel digit appears on exactly two cells.
|
||
|
||
Rows and columns are 0-based, top-left is `(0, 0)`. On the full board, quadrants are numbered
|
||
clockwise: 0 top-left, 1 top-right, 2 bottom-right, 3 bottom-left.
|
||
|
||
## Tunnel links — `board/legend.toml` (optional)
|
||
|
||
The CLI reads `legend.toml` from the quadrant's folder automatically (override with
|
||
`--legend`). By default a tunnel pair links its two cells inside the same quadrant. To link across
|
||
quadrants, give the digit a `quadrant_offset`:
|
||
|
||
```toml
|
||
[tunnels.3]
|
||
quadrant_offset = 1
|
||
```
|
||
|
||
Call `a` and `b` the two cells of the digit in reading order (row by row, left to right).
|
||
With offset `o`, `a` in quadrant *k* is linked to `b` in quadrant *k + o*. Offsets are 0–3.
|
||
|
||
## Design checks (`validate` errors and warnings)
|
||
|
||
Errors:
|
||
|
||
- a wall inside the Dojo;
|
||
- a quadrant without a Dojo entrance, or an entrance opening straight into a Safe Room;
|
||
- a Safe Room that does not contain its board corner, is not connected, does not have exactly
|
||
2 exits, or has both exits on the same side;
|
||
- a Safe Room that is a shortcut (walking through it is shorter than walking around it
|
||
between its two exits);
|
||
- any square that cannot be walked to from a Safe Room (tunnels not counted, Dojo impassable).
|
||
|
||
Warnings:
|
||
|
||
- Safe Room size other than 3x3;
|
||
- Tatami share outside 30–40% of playable squares.
|
||
|
||
The report also lists the square mix, number of tunnel pairs and Dojo entrances, and the
|
||
shortest walk from each Safe Room into the Dojo.
|