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)

{
  "board": {
    "style": "hex-of-hex",
    "minWidth": 5,
    "maxWidth": 9,
    "reference": {
      "layout": "annulus",
      "source": "circle-of-life-ring",
      "rotateWithBoard": true,
      "gap": 0.75,
      "styles": {
        "species": {
          "func": "flatten",
          "fg": "_context_fill",
          "bg": "_context_background",
          "opacity": 0.55
        },
        "species-0": 1,
        "species-3": 2,
        "species-6": 3,
        "species-9": 4,
        "arrows": "_context_strokes",
        "background": "_context_background",
        "ring": {
          "func": "flatten",
          "fg": "_context_fill",
          "bg": "_context_background",
          "opacity": 0.35
        }
      }
    }
  },
  "legend": {
    "A": {
      "name": "piece",
      "paint": {
        "fill": 1
      }
    },
    "B": {
      "name": "piece",
      "paint": {
        "fill": 2
      }
    }
  },
  "pieces": "-----\n------\n---A---\n----B--\n------\n---A---\n------\n-----"
}

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.

`localStash` area

Pyramid stash columns (Volcano-style capture rows, bag pools, Ice Palace hand/pool, etc.) render below the board on the default, stacking-3D, and stacking-expanding engines. See Engines for which games use which renderer.

type: "localStash".
Optional label, width (max stack columns per row), and spacing (horizontal gap between columns as a fraction of board cell size).
stash: array of columns. Each column is an array of legend keys, ordered bottom → top (column[0] is the bottom piece). Keys are opaque to the renderer; spacing and silhouette sizing come from each key’s entry in the top-level legend (name, not key digits).
Vertical spacing is derived from glyph names in that column: pyramid-up-*-3D entries use shared-base silhouette stacking; other pyramid glyphs use uniform solid stack offset. This is not tied to the renderer name.
Row layout: columns wrap at board width (or area width); short columns share a row baseline.
Legacy: "-" entries still consume a vertical slot without drawing a piece. New game code should emit dense columns only (no spacers). Property names are listed in the schema reference.

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,
        "scale": 1.25,
        "paint": {
          "fill": 1
        }
      },
      {
        "name": "tile-04",
        "scale": 1.25
      }
    ],
    "DomR35": [
      {
        "name": "piece-square-single",
        "rotate": -90,
        "scale": 1.25,
        "paint": {
          "fill": 2
        }
      },
      {
        "name": "tile-06",
        "scale": 1.25
      }
    ],
    "DomL22": [
      {
        "name": "piece-square-single",
        "rotate": 90,
        "scale": 1.25,
        "paint": {
          "fill": 3
        }
      },
      {
        "name": "tile-03",
        "scale": 1.25
      }
    ],
    "DomR22": [
      {
        "name": "piece-square-single",
        "rotate": -90,
        "scale": 1.25,
        "paint": {
          "fill": 4
        }
      },
      {
        "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"
          ]
        }
      ]
    }
  ]
}

Entry captions in a `pieces` area

Individual slots may show optional short text above or below the piece (or whole domino tile). This is separate from the area title (label at the top-left of the hand bar). Captions are plain strings, not i18n renderLabel objects.

Legend-key slot with caption:

{ "piece": "En1N", "text": "1", "textPosition": "below" }

piece — legend key (same as a bare string entry).
text — optional caption (typically one to three characters).
textPosition — "above" or "below"; defaults to "below" when text is set.

Domino tile with a whole-tile caption:

{ "domino": ["DomL35", "DomR35"], "id": "t0", "text": "×", "textPosition": "above" }

Click payloads are unchanged: legend-key slots still return the legend key; domino ends still return the _domino_… encoding.

Annotations

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