Grids & boards
A grid turns a zone into a structured board:
a chessboard, a hex wargame map, a point-to-point route network, or an
open lattice that tiles snap to. A grid lives on a zone whose
role is grid and whose
arrangement is grid — the grid spec then
describes the cells, nodes, and edges components can sit on.
Like everything else in taybl, a grid is scaffold, not a rules engine. It gives components named spots to land on; it never enforces legal moves, adjacency, or turn order. Players move pieces between cells by hand.
The four grid types
A grid’s type picks how its spots are laid out:
type | Use it for | Notes |
|---|---|---|
square | A rank-and-file board (chess, checkers) | Needs either a cells list or both width and height |
hex | A hex map (Catan, wargames) | Same cell rules as square, plus an orientation |
graph | A point-to-point network (Pandemic, Ticket to Ride) | Defined by nodes + connections rather than a cell block |
open | An unbounded tile lattice (Carcassonne, dungeon crawls) | No fixed cells; tiles snap to an openGrid lattice at runtime |
A fixed square/hex grid renders unpainted by default — no grey
background, so you can drop in your own board art as a surfaceAsset. Cells
with an explicit color still show it; to see empty cell boundaries, turn on
Show grid lines (gridLinesVisible).
Cells, nodes, edges, regions
Depending on the type, a grid is built from a few kinds of part:
| Field | Type | Meaning |
|---|---|---|
width / height | number .optional() | Cell-block dimensions for a square/hex grid; an alternative to listing cells |
cells | array .optional() | Explicit positioned cells — each an id, plus optional coordinates (axial {q, r, s}, how hex boards are positioned), offset (table units), label, color, region. On a hex board this list is the board: a hex exists exactly when it has an entry |
orientation | flat | pointy .optional() | Hex lattice rotation. flat = a flat edge at 12 o’clock; pointy = a vertex at 12 o’clock. Must match the hex tile art. Default flat |
nodes | array .optional() | Vertices / intersections — placement targets distinct from cells (a Catan settlement spot, a Pandemic city) |
connections | array .optional() | Edges between cells / nodes (see below) |
regions | array .optional() | Named groups of cellIds (a board’s territories or sectors) |
openGrid | object .optional() | Required when type is open: the lattice (square | hexPointy | hexFlat), cellSize, and optional autoFit, spacing, gridLinesVisible (see below) |
openGrid.cellSize | object | The tile pitch (table units). Hex lattices auto-tessellate — tiles touch regardless of the authored width/height ratio, so you set one cell size (the tile’s long axis) |
openGrid.spacing | number .optional() | Extra gap between tiles as a fraction of the pitch. 0 / unset = tiles touch; 0.15 = a 15% gap. The tile size is unchanged — only the spacing grows |
openGrid.autoFit | boolean .optional() | Tiles scale down so the whole lattice fits inside the zone box |
openGrid.gridLinesVisible | boolean .optional() | Draw faint cell outlines across the board box — a graph-paper placement guide. Default (unset) = hidden; suppressed when the zone has printed surface art |
openGrid.alwaysSnap / openGrid.neverSnap | string[] .optional() | Component ids that override how a dropped piece is placed on the lattice. By default a piece snaps to a cell only when it covers at least half a cell (tiles snap; smaller meeples/markers free-place at the exact point). List a component under alwaysSnap to force it onto cells, or neverSnap to always free-place it. Set from the Grid card’s Snapping behavior control |
nodeSize | number .optional() | Default node-marker radius (table units) for a graph grid |
nodesVisible | boolean .optional() | Whether node markers + routes are drawn during play. Default (unset) = hidden — the graph is an invisible scaffold so pieces sit on the printed board art |
freePlacement | boolean .optional() | graph grids only. Whether the open area around the nodes accepts pieces. Default (unset) = allowed; set false for a strict node-only board. Set from the graph inspector’s Allow pieces anywhere on the board checkbox |
fit | object .optional() | A sub-rectangle of the zone box (fractions, 0..1) the cell block fills — aligns cells over board art whose printed grid doesn’t span the whole image |
gridLinesVisible | boolean .optional() | Draw faint grid lines for a fixed square/hex grid — a placement guide when the zone has no board image. Default (unset) = hidden; the grid is otherwise unpainted, so players can drop in their own board art. Suppressed over printed surface art |
fillCells | boolean .optional() | Pieces and tokens on this board render at their cell’s size instead of their own. Default (unset) = each piece keeps its own size |
Making pieces fill their cell
By default a piece on a board renders at its own size — the size set on the component — which is what you want when a piece is deliberately smaller than its cell: a number chit on a Catan terrain hex, a scoring marker on a track space. On an abstract board it is usually not what you want: a chess king drawn to fill its square ends up floating small in the middle of it.
Turn on Pieces fill their cell (fillCells) and every piece and token
snapped to a cell takes the cell’s size instead. It applies to square and
hex boards. Cards on a cell already fill it, with or without this setting.
If a piece still needs breathing room inside its square, give the component
a padding value — that inset is applied on top, so you keep per-component
control without going back to hand-tuned sizes. Ask Pip “make the pieces
fill their squares” and it will set this for you.
Connections (edges)
A graph grid’s connections[] are the edges between nodes (or cells). An
edge with an id becomes a placement target itself — a road between two
cities, a Ticket to Ride route you drop train cars onto:
| Field | Type | Meaning |
|---|---|---|
from / to | string | The two endpoints (cell, node, or open id) |
id | id .optional() | When set, the edge is a droppable placement target |
bidirectional | boolean .optional() | Equivalent to directed: false. Mutually exclusive with directed |
directed | boolean .optional() | true = traversal only from→to (a one-way segment). Default = undirected |
The open area around a graph’s nodes
A graph board is more than its nodes and routes. The rest of it — the ocean
on a Pandemic map, the margin beside a route network, the corner where you
park the cubes you haven’t used yet — is open play by default: drop a
piece there and it stays exactly where you released it.
Nodes and routes still win. A drop that lands on a city goes to that city,
exactly as before; only a drop that misses every node, route and cell is
free-placed. Free-placed pieces are stored as a freepoint_x_y position — the
same thing an Open play (freeform) zone uses — so you can also pin one in
setup by dragging a component from the library straight onto the map.
Turn it off with Allow pieces anywhere on the board in the graph inspector if your board should be strictly node-only. (Before this existed, a drop that missed every node made the piece disappear — it stayed in the zone with no position, so nothing drew it. If you have an older game where pieces vanished on the map, this is why, and it is now fixed.)
How to edit in the Studio
Open your game → Layout tab and select the board zone. For square/hex
grids, the Zone inspector exposes the grid dimensions, a Show grid
lines checkbox, and a Pieces fill their cell checkbox; the fit
overlay lets you drag the cell block to line up with a board image. For a graph
grid, the graph inspector opens: toggle into Move, Add, or
Connect mode to drag nodes onto their printed spots, drop new nodes, and
click two nodes to link them. The same panel toggles nodesVisible, toggles
Allow pieces anywhere on the board (freePlacement), and sets the default
node size, with one-click “Fit nodes to box” and “Match box
aspect” fixes for aligning the topology over a surface image.
Adding and removing hexes
On a hex board the cell list is the board — a hex exists because
cells[] has an entry for it. (This is the one thing the Regions
section does not control: a region is a label over cells that already
exist, so shortening its cell list renames nothing and removes nothing.)
The Grid card's Cells panel is where that list lives. Each hex is a chip: hover one to make it glow on the board, click its × to remove it. Tick Edit on board to work on the canvas instead — click a hex to remove it, and click any dashed outline to add a hex there. Dashed outlines ring the whole board, so the same gesture grows it outward. Removing a hex is not undoable; Reset is the way back.
A hex never leaves quietly. If a starting piece is placed on it, or it is the last cell of a region, the panel says so and waits for you to confirm — and when you do, that piece and that region go with the hex, so nothing is left pointing at a cell that no longer exists. Removing an empty hex just removes it.
To reshape a board wholesale, use Regenerate as hexagon: pick a radius (2 → 19 cells, the classic 3-4-5-4-3 island; 3 → 37, adding the sea ring) and rebuild. Hexes that survive keep their colour, label and region, and your existing regions are kept and trimmed rather than replaced.
One thing to expect: cell names like “NE · outer” are derived from where the hex sits in the board's rings, so trimming the outer ring renames the hexes that remain. Names you type yourself stay put.
Related
- Zone roles — the
gridrole - Zone arrangement — the
gridarrangement - Component rendering — board art via
surfaceAsset - Layout — where the board zone sits