Technical Reference

Deep-dive into notation systems, data formats, board architecture, and engine internals.

Triumvirate Notation v4.0

The server uses column-row notation: columns A–L, rows 1–12. Examples: E2, A1, L12.

Column Layout

Total: 96 valid cells out of 144 (12×12). The 48 invalid cells are: E5–H8, I1–L4, A9–D12.

120° Rotational Symmetry

The board has three-fold rotational symmetry. Each segment is a 120° rotation of the others. The mapping tables between segments preserve all geometric properties (adjacency, diagonals, rays).

Triumvirate v4.0 Full Specification

Design Principles

• Every cell's address encodes its sector (which player's territory), ring (distance from center), and position (depth + flank)
• The system has no "gaps" — unlike classic A–L notation where E5–H8, I1–L4, A9–D12 are invalid
• 120° rotational symmetry is explicit: rotating W→B→R in coordinates is a simple letter substitution

Coordinate Format

Regular cells: [Sector][Ring]/[Opponent][Depth].[Flank]

• Sector (W/B/R) — which player's home segment the cell is in
• Ring (0–3) — distance from the board center. Ring 0 = adjacent to rosette, Ring 3 = back row
• Opponent (W/B/R) — which neighboring sector the cell faces (left or right neighbor)
• Depth (0–3) — distance from the border between the two sectors
• Flank (0–3) — horizontal position within the row

Rosette cells: C/[Source].[Neighbor]

Six cells where three segments meet. C = Center. Source and Neighbor identify which two sectors are joined at that point.

Piece Names

Buried Level Metric

Buried Level = Ring + Depth (range 0–6). Measures how "deep" a cell is in the board:

• 0 — rosette cells (most active, triple junction)
• 1–2 — inner cells (high tactical activity)
• 3–4 — middle cells (moderate activity)
• 5–6 — corner cells (most passive, back row)

Conversion Formulas

The mapping between classic and Triumvirate notation follows these rules:

• White sector: columns A–H, rows 1–4. Ring = 4 − row. Left half (A–D) faces Black, right half (E–H) faces Red.
• Black sector: columns A–D + I–L, rows 5–8. Ring = row − 5. Columns are inverted (L→0, K→1, etc.).
• Red sector: columns E–H + I–L, rows 9–12. Ring = 12 − row. Columns are inverted.

The LLM Bot's notation_converter.py implements the complete bidirectional conversion. See the LLM Bot — Triumvirate Notation section for usage details.

3PF Format (Three-Player FEN)

A compact text representation of the full board position, analogous to FEN in standard chess. Contains 7 space-separated fields:

wRA1,wNA2,...,rRL12 w wKQ.bKQ.rKQ - aaa 0 1

TPGN Format (Three-Player PGN)

An extension of PGN for three-player games:

[Event "Triumvirate Game"]
[White "Bot1"]
[Black "Bot2"]
[Red "SmartBot"]
[Result "1-0-0"]

1. E2-E4 D7-D6 I11-I10
2. D2-D3 ...

Headers follow PGN conventions. Move notation uses from-to format. Results: 1-0-0 (white wins), 0-1-0 (black wins), 0-0-1 (red wins), 1/2-1/2-1/2 (draw).

JSON Formats

Move JSON

{
  "from": "E2",
  "to": "E4",
  "type": "normal",
  "player": "white",
  "captured": null,
  "promotion": null
}

Position JSON

{
  "pieces": [
    {"cell": "E2", "type": "Pawn", "color": "white", "owner": "white"}
  ],
  "active_player": "white",
  "castling": {"white": {"K": true, "Q": true}, ...},
  "move_number": 1
}

Board Architecture

Game Engine

Testing & Verification

Test Suites

Running Tests

# All tests
python -m pytest -v

# Engine only
python -m pytest tests/ -v

# Server only
python -m pytest server/tests/ -v

# Single file
python -m pytest tests/test_engine_game.py -v

# Pattern match
python -m pytest -k "checkmate" -v

# With coverage
python -m pytest --cov=. --cov-report=term-missing

Test Organization

• tests/test_engine_*.py — Game, Executor, Move tests
• tests/test_rules_*.py — Checkmate, stalemate, castling, draw
• tests/test_board_*.py — Hex geometry, coordinates, adjacency
• tests/test_pieces_*.py — Piece movement, captures
• tests/test_state_*.py — GameState, BoardState, serialization
• tests/test_evaluation_*.py — All evaluation pipeline stages
• tests/test_game_io_*.py — 3PF, TPGN, JSON roundtrips
• server/tests/test_*.py — API, WebSocket, matchmaking, auth, session