Topologies

The five spatial structures that underpin every board game in the engine.

The universal adapter

Topologies are the engine's defining architectural insight. Every package above topologies defines a contract (movement rays, adjacency, layout). Topologies implement that contract. The consuming package never knows which topology it's using.

This means a piece movement rule written for grid automatically works on hex if both implement the same traversal contract. New topologies auto-work with all existing higher packages.

Grid

Rectangular boards with cells addressed by algebraic notation (a1, b2, etc.).

Games: Chess (75 variants), Draughts (20), Go (14), Xiangqi (8), Shogi (25), Reversi, Tafl, Dou Shou Qi.

Layouts:

• cells — pieces occupy squares (chess, draughts)
• intersections — pieces on line crossings (go, xiangqi, shogi)
• cross — cross-shaped subset of grid (pachisi, chaupar)

Coordinates: Algebraic — a1 (bottom-left) to h8 (top-right for 8x8).

topology:
  type: grid
  rows: 8
  cols: 8
  layout: cells    # or intersections, cross

Hex

Hexagonal boards using axial coordinates (q, r).

Games: Hex, Y, Nukes, Glinski Chess, McCooey Chess, Hex Shogi.

Shapes:

• hexagonal — regular hexagonal board defined by radius
• triangular — triangular board defined by side length
• Rectangular — defined by rows + cols
• Explicit — array of [q, r] coordinate pairs

Coordinates: Axial — q,r pairs (e.g. 0,0 is centre, 1,-1 is adjacent).

topology:
  type: hex
  shape: hexagonal
  radius: 5
  orientation: pointy   # or flat

Track

Linear or circuit paths with numbered positions.

Games: Backgammon (8 variants), Landlord's Game (5 editions), Royal Ur.

Coordinates: Zero-indexed position numbers — 0 to positions-1.

topology:
  type: track
  positions: 24

Pit

Mancala-family sowing layouts with pits and optional stores.

Games: Kalah, Oware, Bao, Congkak, Pallanguzhi, Toguz Korgool, Sungka, Ayo.

Coordinates: pit-0 to pit-N (playing pits), store-0, store-1 (end stores).

topology:
  type: pit
  cols: 6          # pits per side
  rows: 2          # sides (default 2)
  stores: true     # end stores (default true)

Graph

Arbitrary node-edge structures for boards that aren't regular grids.

Games: Morris (7 variants), Stern-Halma (5), Nyout, Asalto.

Structures:

• concentric-rings — Morris boards (2-4 rings with midpoint connections)
• star — Chinese Checkers / Stern-Halma (6-pointed star)
• perimeter-cross — Nyout (circular with cross shortcuts)
• grid-cross — Asalto (grid with fortress extension)

Coordinates: Node IDs — n0, n1, etc. (auto-generated) or custom IDs from explicit node definitions.

topology:
  type: graph
  structure: concentric-rings
  params:
    rings: 3
    midpoints: true

Registry

Topologies are registered at packages/topologies/registry.js. All 5 built-in types auto-register when packages/topologies/index.js is imported. Custom topologies can be added at runtime:

import { register } from 'packages/topologies/registry.js'

register('triangular', {
  factory: (config) => createTriangularTopology(config),
  schema: { type: 'triangular', required: ['sideLength'] }
})