Initial commit, with rules 0.5 and basic bots

2026-09-26 16:01:46 +02:00
commit 0aaf113fc3
32 changed files with 4206 additions and 0 deletions
@@ -0,0 +1,97 @@
+# 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.