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, optional offset (table units), label, color, region |
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 |
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 |
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 |
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 and a Show grid
lines 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 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.
Related
- Zone roles — the
gridrole - Zone arrangement — the
gridarrangement - Component rendering — board art via
surfaceAsset - Layout — where the board zone sits