Concepts

The JSON document describes the game table: at minimum a board and pieces. Optional sections add glyphs, side areas, and annotations.

Top-level structure

Property	Required	Role
`renderer`	no	Which rendering engine to use (default: `default`)
`board`	yes	Board geometry and style
`pieces`	yes	Piece placement (format varies by renderer)
`legend`	no	Maps keys to glyphs/colours
`areas`	no	Side panels (stashes, buttons, etc.)
`annotations`	no	Overlays for moves and highlights
`options`	no	Renderer flags

See the schema reference for the authoritative property list.

Board

The board is drawn first. Styles include square grids, vertex boards, hex fields, sowing pits, circular boards, and many more. See Boards.

Board reference charts

Some games attach a prebuilt reference chart beside or around the playfield (e.g. Scribe’s glyph table, Circle of Life’s food-web ring). Use the optional board.reference property:

layout: "sidebar" or "annulus"
source: built-in registry id (scribe-chart, scribe-chart-left, scribe-chart-right, circle-of-life-ring) or a legend key to override artwork. A string applies to every side in sides; an array is paired by index with sides.
sides: sidebar only — any combination of "left", "right", "top", and "bottom" (1–4 unique sides). Bottom charts are placed above areas. Legacy position is equivalent to a single-entry sides array.
styles: optional map of slot ids → colours for regions marked data-ref-fill / data-ref-stroke in the SVG
rotateWithBoard: false keeps the chart fixed when the playfield rotates (sidebar charts); true rotates with the board (annulus rings)

Pieces

Usually a string grid (rows separated by \n) where each character maps to a legend entry that represents a piece on the board. Specialized renderers use arrays or structured objects instead. See Engines.

Legend

Maps short keys to glyph definitions — simple names, composite arrays, gradients, player colours, text glyphs, etc. See Glyphs.

Areas

Specialized sections, usually below the board, to provide additional information: piece stashes, button bars, Homeworlds stashes, polyomino holding areas, and more.

`track` area

A read-only mini-board for score tracks and similar peripheral grids. Each track accepts any valid boardBasic declaration plus a top-level-style pieces grid (string rows, comma rows, or nested arrays). Tracks use the global legend only — there is no per-area legend. Row/column labels are off by default (labels: true to show them). Tracks do not rotate with the main board and are not clickable in the default renderer.

position: "left", "right", "top", or "bottom" (default "bottom").
width: optional display size in main-board cell units (distinct from board.width / board.height, which set the track grid geometry). For top and bottom, this is the display width (defaults to main board width). For left and right, this is the display height (defaults to main board height). The track is scaled uniformly to fit.
When the display size matches the playfield along that axis, the track is aligned to the playfield edge (top/left); otherwise it is centered on that axis.
Multiple tracks on the same side stack outward in areas declaration order.
annotations: optional array of standard board annotations scoped to the track grid.

Domino tiles in a `pieces` area

Domino pairing is area-only. Board placement continues to use separate half legends in adjacent cells (see Glyphs — domino-style blocks).

In a pieces area, an entry may be a domino tile ref that fuses two existing legend keys into one flat 2:1 tile:

{
  "type": "pieces",
  "label": "Your hand",
  "pieces": [
    { "domino": ["DomL35", "DomR35"], "id": "t0" }
  ]
}

domino — legend keys for the west (left) and east (right) ends, in that order. Each end is styled independently in legend (glyphs, colours, opacity, etc.). The renderer does not interpret tile contents.
id — optional stable handle for click payloads (defaults to the tile index).

Each end is individually clickable. The click handler receives boardClick(-1, -1, piece) with piece encoded as:

_domino_{indexOrId}_{leftKey}_{rightKey}_{L|R}

For example, clicking the left end of tile t0 whose ends are DomL35 and DomR35 returns _domino_t0_DomL35_DomR35_L.

Hand tiles use the same board cell size and 0.85 placement scale as pieces on square* boards, so legend scale values that compensate for board downscaling should look consistent between the board and the hand.

Rows wrap at the board width in cells (each domino tile counts as two cells and is never split across rows).

{
  "board": {
    "style": "squares",
    "width": 4,
    "height": 4
  },
  "legend": {
    "DomL35": [
      { "name": "piece-square-single", "rotate": 90, "colour": 1, "scale": 1.25 },
      { "name": "tile-04", "scale": 1.25 }
    ],
    "DomR35": [
      { "name": "piece-square-single", "rotate": -90, "colour": 2, "scale": 1.25 },
      { "name": "tile-06", "scale": 1.25 }
    ],
    "DomL22": [
      { "name": "piece-square-single", "rotate": 90, "colour": 3, "scale": 1.25 },
      { "name": "tile-03", "scale": 1.25 }
    ],
    "DomR22": [
      { "name": "piece-square-single", "rotate": -90, "colour": 4, "scale": 1.25 },
      { "name": "tile-03", "scale": 1.25 }
    ]
  },
  "pieces": [
    [[], [], [], []],
    [[], [], [], []],
    [[], [], [], []],
    [["DomL22"], ["DomR22"], [], []]
  ],
  "areas": [
    {
      "type": "pieces",
      "label": "Your hand",
      "rotateWithBoard": false,
      "pieces": [
        { "domino": ["DomL35", "DomR35"], "id": "t0" },
        { "domino": ["DomL22", "DomR22"] }
      ]
    }
  ]
}

Annotations

Drawn above pieces: move arrows, enter/exit markers, dots, outlines, etc. See Annotations.