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 |
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 (mm), 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) and cellSize tiles snap to |
nodeSize | number .optional() | Default node-marker radius (mm) 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 |
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 |
type | string .optional() | Free-form category label — a renderer hint for colour or style (land vs. sea, track colour) |
weight | number .optional() | Positive numeric cost on the edge (a route length, a movement cost) |
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; 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