A RuleSpec is one JSON document that completely describes a game mode: the board, the pieces, how they move, what happens when they meet, and how somebody wins. It is what the Lab edits, what gets published to the library, and what travels inside every game so a player who has never heard of your mode can still play it.
Three rules define the format, and everything else follows from them:
- It is data, never code. The server decides what is legal in a real game, and the server cannot run your JavaScript. So a rule is a shape, not a function — which is also why a mode a stranger wrote is safe to play.
- It is finite. Every list has a cap, every question is a bounded look at the board, and nothing recurses forever. The cost of a position is bounded before anybody plays it.
- It is open by combination. Every slot is a list, and almost every entry
can carry a
when. New kinds of game come from new combinations far more often than from new fields. If you are looking for a field that does not exist, try composing two that do.
Two interpreters read this format and must agree exactly:
frontend/src/engine/ and backend/internal/game/spec/. A shared corpus of
positions pins them together — conformance/corpus.json, read byte-for-byte by
a test in each language — and either one disagreeing is a failing test in two
languages.
v2 is a superset of v1. Every v1 document is a valid v2 document and means
exactly what it always meant, so a spec that declares "spec": 1 is read
unchanged. Six additions, each marked v2 where it appears below:
| what it added | what it cost | |
|---|---|---|
| Hexagonal boards | board.topology: "hex" |
one coordinate substitution; diagonal stops existing |
| Boards that are not rectangles | board.shape, board.holes |
a mask over the same grid; edge and corners are read off the outline |
| History-aware conditions | hasMoved, lastMove, lastTo, lastFrom |
those bits must enter the position hash |
| Relational regions | line, sandwich, surrounded |
a region is a board walk, not a coordinate test |
| Royal pieces | pieces[].royal |
move generation becomes O(moves × replies), only for a mode that declares one |
| Fog of war | visibility.mode: "fog" |
the client stops being a second authoritative reader |
| The reserve | reserve, place.fromReserve, capture.toReserve |
a hand joins the position hash, only for a mode that declares one |
Plus two smaller things the additions needed: a place movement kind, so a game
can put pieces down instead of moving them, and a convert effect, so pieces can
change sides without being taken. place carries
onlyIfEffective, which is what makes a
placement game's "only where it turns something over" one sentence in the
document rather than two that have to be kept the same by hand.
A placement puts a piece on an empty square, so its from and to are the
same square. That is what lets every condition, effect and record keep working
unchanged — and it means two squares do not always identify one move. A mode with
two place rules has two different legal moves on b2, and b2-b2 names both.
So a placement that had a choice is written Kind@square:
d7-d6 an ordinary move
Cross@b2 a placement, and what it put down
A piece id may not contain an @ (ids are [A-Za-z][A-Za-z0-9 _-]*), so the
split is unambiguous even for an id holding a - or a space. b2-b2 still
reads, as a placement naming no kind, which resolves the way it always did —
every archived record and every hand-written corpus line is unaffected.
This is Total War, the mode this project shipped first, written out completely. Nothing in it is optional except the comments.
Infiltration, in specs/infiltration.json, is the same document with the
effects removed and one win condition instead of two:
"win": [
{ "id": "infiltration", "when": { "in": ["to", { "home": "opponent" }] },
"result": "mover", "reason": "infiltration" }
]Note what Infiltration does not say. It has no annihilation rule, so losing your last piece is not a loss — it leaves you with no legal move, which the engine calls a stalemate draw. That is a real rule of the mode, expressed by leaving something out.
Three rules apply to every mode and are not yours to write:
- Stalemate is a draw. A player to move with no legal move draws. The engine
asks your movement rules, so custom movement, blocking and immobile pieces
are all covered.
v2: a side that owns a royal piece and is attacked when it runs out of moves is checkmated instead, which is what makes the inherited rule correct chess stalemate for free. - Threefold repetition is a draw. The same board, territory, side to move and history slice, three times.
- Resignation. Nothing about it belongs in a spec.
You cannot turn those first two off. They belong to the engine and apply to
every mode identically, so a spec that claimed to change them would be making a
promise the authoritative server could not keep — and the validator refuses one
that tries. "draw": { "noRepetitionDraw": true } is an error, by name.
draw states the one rule that is yours, a cap on how long a game may run:
"draw": { "moveLimit": 200 }It depends only on the move number, which is why every reader can honour it. Use it for a mode whose win condition might never fire — and check with the playtester, because "might never fire" is exactly what it reports.
"board": { "width": 11, "height": 7, "topology": "square", "palette": "walnut" }Any rectangle from 3 to 26 a side, up to 361 tiles. Files are letters a
onwards, left to right. Ranks are numbers from 1 upwards, starting at Player
Two's home boundary — so on a 9×9 board Player Two starts on rank 1 and Player
One on rank 9, and a1 is the corner of Player Two's home.
startingPosition.rows has to be exactly this shape, one string per rank from
rank 1 up. Each character is a piece's symbol — upper case for Player Two,
lower case for Player One — or . for empty. Territory follows the pieces at setup, so a piece
standing on a square owns it before anybody moves.
v2: startingPosition.territory states the ground instead, one row of R, B
or . per rank, for a mode that wants its armies standing on neutral ground.
That default is a fact about the position, not an instruction to the board. A
board only colours ground when something in the document gives it a meaning — a
rule that claims or sets it, a starting territory, or a condition that reads
territory or share. Otherwise the colour would be saying that Chess's back
two ranks matter, which no rule in Chess believes. In its place the board colours
the squares a side is trying to reach, read off the win conditions: the far
rank in Breakthrough, the corners in Hnefatafl. See frontend/src/engine/ground.ts.
Player One moves first.
The two sides are red and blue in the document, and Player One and Player
Two on every screen. The document's words are machinery — the owner of a tile,
the case of a symbol, the side a predicate names — and they are not a claim about
colour: board.inks below lets an author paint either side ivory or ebony, which
is what makes "Red's pieces are ivory" a sentence that argues with itself. Turn
order is the one thing about a side that no control can change, so that is what a
reader is told. red is Player One; blue is Player Two.
palette is a named theme — slate, walnut, sand, moss, ink, orchid,
ice — and never a picture. v1 painted an uploaded image under the board and had
to keep the squares translucent over it, because a board nobody can read is not a
board anybody can play on. A palette cannot fail that way.
"board": { "width": 8, "height": 8, "inks": { "red": "ivory", "blue": "ebony" } }inks.red and inks.blue are named materials — crimson, cobalt, ivory,
ebony, jade, brass, violet, pewter — and default to crimson and
cobalt, which is what every game published before this field existed is
painted in.
The raster art behind figure is one drawing per piece, in no colour: a
near-black outline, a mid-tone body, a white highlight. The ink is dropped into
that mid-tone when the board is drawn, by an SVG duotone whose middle stop is
the named colour. So ivory and ebony are the same king, a set is a choice
rather than seventeen more files, and this field is why the art directory holds
one file per piece instead of a red one and a blue one.
Two independent choices rather than one named pair, because the pairs people actually want do not factor: ivory against ebony is a chess set, crimson against ebony is draughts, crimson against cobalt is this site.
red and blue here are the format's two sides — the owner of a tile, the case
of a symbol — and not a claim about colour, which is the whole point of the
field. Screens name them by turn order instead, because "Red's pieces are ivory"
is a sentence that argues with itself: red is Player One, who moves first,
and blue is Player Two.
Paint, never a rule. Nothing in either reader looks at it, and the fingerprint leaves it out — a recolour is the same game, and thirty recolours of Chess are not thirty games.
The one thing an ink can get wrong is both sides wearing it. A raster piece is a cutout with no side ring behind it, so its colour is the only thing that says whose it is, and two ivory kings validate, publish and play as two kings nobody can tell apart. The validator warns and does not refuse: a mode whose pieces are all letters is unaffected, and paint has never been allowed to stop a document.
"board": { "topology": "hex", "width": 9, "height": 9, "palette": "ice" }topology defaults to "square", so every existing spec is unchanged.
Hex uses axial coordinates (q, r) with pointy-top orientation, because
axial keeps a tile's neighbours as six fixed offsets — which means the movement
rules, the region tests and the mover-relative frame all keep working with one
substitution rather than a second engine. The board is the axial rhombus
0 ≤ q < width, 0 ≤ r < height: the shape the game of Hex is played on, drawn
as a parallelogram with each rank offset half a tile from the one below it.
What changes:
all6replacesall8.orthogonalmeans the six neighbours.diagonalandall8do not exist on hex, and a spec that asks for one is a validation error rather than a silent empty set. The same the other way:all6on a square board is an error.- The mover-relative names survive, because "away from your own home" is
still well defined.
forwardis the two neighbours that advance a rank,backwardthe two that retreat one,sidewaysthe two that advance none, andforwardDiagonalthe two hex-diagonals that advance exactly one rank. That is what keeps one rule serving both sides. - Offsets are read in the topology's own frame. On square the mover's frame
flips
y; on hex it is the point reflection — both axial components negated — which is the same mirror expressed in the coordinates hex has. - Distance is the hex metric, so
{ "distance": { "n": 1 } }means "the neighbours" on both boards.
rows and columns mean much less on hex, which is why v2 added ring and
distance; home, corners, edge, all, origin and destination all
still mean something and are preferred.
"board": { "topology": "hex", "width": 11, "height": 11, "shape": "hexagon" }
"board": { "width": 9, "height": 9, "holes": [[3,3],[4,3],[5,3],[3,4]] }A board is stored as a rectangle and always will be: every coordinate here is
an (x, y) into one, every layout row is a rank of it, and rect regions and
file letters are written against it. So a board that is not a rectangle is not a
second kind of board — it is a mask over the same one. A tile outside the
mask is simply not on the board: nothing stands on it, no move lands on it, no
region contains it, and no slide passes through it. That is the same
substitution hex was, done once more, and it is why every movement rule,
condition and region in this document is unchanged by it.
Two fields, and they compose.
shape is the outline, and it is always the largest such shape that fits
the rectangle, centred — so none of them takes a radius or an arm width, and the
width and height dials keep meaning what they meant.
rect |
both | The whole rectangle. The default, and every v1 spec's meaning. |
hexagon |
hex only | The hexagon of hexes. On 11×11 that is the 91-tile board hexagonal chess is played on. |
triangle |
both | Standing on rank 1. On hex the ranks lose one tile each going up, which is a triangle of hexagons; on square it is a pyramid filling the rectangle. |
diamond |
square only | The four corners cut off. |
cross |
both | The middle third of the files plus the middle third of the ranks. |
Asking for hexagon on a square board, or diamond on a hex one, is a
validation error rather than a silent wrong shape — the same refusal diagonal
gets on a hex board, for the same reason.
holes is a list of [x, y] pairs cut out of that outline, at most 128 of
them. It is the escape hatch that keeps the five names a convenience rather than
a ceiling: any board they cannot say is one of them with holes in it, and a hole
is a pair of numbers rather than a new field. A hexagon with its centre knocked
out is {"shape": "hexagon", "holes": [[5, 5]]}.
What a cut board changes, and it is a short list:
edgeis a tile with a missing neighbour andcornersis a tile the board turns at — half its neighbours or fewer. On an uncut board those are exactly the rim and the four corners they always were, on both topologies; on a hexagon they are its rim and its six corners. This is what keeps "get a piece to the edge" a rule you write once and play on any shape.shareis a share of the tiles the board has, so a hexagon's middle is not diluted by the four corners of the rectangle it is stored in.centeris nudged onto the board when the middle of the rectangle was cut out, soringanddistancenever measure from nowhere.startingPosition.rowsis still the whole rectangle, one row per rank of the same width. A cut tile is written., and a piece standing on one is a validation error naming the square.
A board must keep at least five tiles. A board that comes apart into islands with no path between them is a warning, not an error: it is usually a hole somebody did not mean to leave, and occasionally the whole idea.
chequer is paint and nothing else — no rule in this format reads a tile's
colour. auto (the default) is the chequer on square and bands by rank on hex;
bands is bands on either; none is one colour; and three is the proper
three-colouring (q − r) mod 3, where every hexagon's six neighbours are the
other two colours in turn. That is the colouring a hexagonal board is printed
with, and the one two colours provably cannot give it.
"pieces": [
{ "id": "Cow", "symbol": "C", "glyph": "🐄" },
{ "id": "Stone", "symbol": "S", "shape": "circle", "fill": "solid" },
{ "id": "King", "symbol": "K", "glyph": "👑", "royal": true },
{ "id": "Scout", "symbol": "T" }
]id is what the rest of the spec refers to, and it is also the value that
appears on a tile — one name per piece, so a rule about a Cow and the square a
Cow is standing on use the same word. Empty and Unknown are reserved.
symbol is one letter, unique in the mode, and it is how the piece is written in
a layout and in the archive.
description v2 is one line of intent, and never a restatement of the
rules — "the Jarl is not a fighter, he is a runner". What a piece does is
generated from the document and shown directly beneath it, on the rules card and
in the Lab, so a description that contradicts the rules is contradicted on the
same screen. Nothing records what the rules said when it was written: a stored
fingerprint would fire on a rename or a reorder, and a staleness signal people
learn to click past is worse than none.
Capped at 140 characters, shorter than the document's own text fields. Twelve kinds at 400 characters of CJK is 89% of the 16 KiB budget, so prose alone could push a spec past the publish cap — and the generated behaviours sit immediately beneath the box, so a longer one only invites restating them. Leave it out and every reader generates one instead.
beats is a directed graph of [attacker, defender] pairs — not a cycle. The
standard game is a three-cycle, but nothing requires that:
Rock-Paper-Scissors-Lizard-Spock is ten pairs, a one-sided matchup is one pair,
["Pawn", "Pawn"] is a kind that takes its own kind the way a chess pawn does,
and a piece nothing captures is a piece that is simply never taken. The validator
warns about the last one, because it usually makes an annihilation win
unreachable.
capture.mode decides how contact resolves at all:
| mode | meaning |
|---|---|
beats |
the graph decides. The default. |
always |
anything takes anything, like chess. |
never |
nothing is ever captured; win some other way. |
mutual |
both pieces are removed, unless the graph says otherwise. |
Art lives inside the rule document. Nothing is hosted. Four layers, all of them a few bytes of JSON, and they fall back in this order:
-
figure— a drawing this site ships, named rather than uploaded:group names the court kingqueenrookbishopknightpawnclassic sets rockpaperscissorslizardspockcheckerchecker-kingbeewaspqueen-beedronetokens meeplestonediedominotabletcards cardspadeheartclubwar swordshieldspearbowcannonbanneraxehelmetbombflagshipground wallgateanchortowerhousetentweather and stone flamedropboltsnowflakeleaftreemountainsunmoonwavethe quest keychestpotionscrolltorchgemcoinfar away rocketalienrobotghostmarks crowneyechevronskulltargetgearhourglassbelllockcompassscalesThe layer emoji cannot cover.
♚is a letterform rather than a picture, so Extended_Pictographic refuses the whole chess set except♟— which left the six most-copied pieces in the world unsayable, and a queen drawn as"shape": "star"was the honest best the other layers could do. The same is true of every other game's own pieces:♠is a letterform too, and there is no codepoint at all for a meeple, a go stone on its intersection or a shogi tablet. The name is the art: no upload, no fetch, no bytes in the document.Most are drawn in one ink in the same 100×100 frame, so a board that mixes them reads as one set rather than as a scrapbook — which is the other thing the glyph layer cannot do. The classic sets row is the exception: those are the complete pieces of games this site ships whole, painted rather than inked, and each one is drawn twice — once per side. A name is still just a name in the document either way.
-
glyph— a single emoji. Still the answer for a goose, and for anything that wants colour. -
shape—circle,square,triangle,diamond,starorhex, with afillofsolid,hollow,halfordotted. What abstract games actually want: a checkers piece is a disc, not a drawing. -
the letter —
symbolon a disc. The final fallback, and enough to invent a piece without drawing one.
Side identity is never baked into a drawing. There is one drawing per kind
and whose it is goes on when it is drawn, so nothing can drift between one
player's version and the other's — and fog gets its "seen but unidentified"
rendering for nothing: draw the ring, omit the glyph. Two ways it goes on. A
silhouette or glyph sits inside a ring in the side's colour. A painted
classic set has no ring — the cutout is the whole piece — so the side's
board.inks colour is dropped into the drawing's mid-tone by a duotone filter at
draw time; the art itself is colourless. Fog still has the ring to fall back to.
The glyph rule: accept one Extended_Pictographic character, plus an
optional variation selector or skin-tone modifier. Reject ZWJ sequences and
regional-indicator (flag) sequences. One rule, two problems closed: flags are
the politically loaded corner of the emoji space and render as two bare letters
on many Linux builds, and ZWJ sequences fall apart into separate glyphs at tile
size. Note that a chess symbol like ♚ is not Extended_Pictographic and is
refused; ♟ is, and is accepted.
img:<digest> references and board.art and cover are reserved and
unsupported. A document carrying one still validates, with a warning, and draws
its glyph, shape or letter instead. The syntax is reserved so uploads can arrive
later without a format break.
"pieces": [{ "id": "King", "symbol": "K", "royal": true }]Legality gains exactly one filter: after your move, no opponent pseudo-legal
move may capture your royal piece. From that, check, checkmate and pins all
fall out, and a new end reason checkmate names it in the record.
The honest cost: move generation becomes O(moves × opponent moves), because each candidate move needs the opponent's replies generated to be filtered. On a chess-sized board that is nothing; on 19×19 with twelve kinds it is real, and it multiplies straight into the playtester.
So: only a mode that declares a royal piece pays for it. No royal, no filter,
identical performance to v1. This is also what keeps "capture the king" available
as a deliberate design choice rather than a limitation — it is one ordinary win
condition (count of the opponent's King is zero) and it needs no royal flag.
specs/rps-chess.json does it that way on purpose; specs/chess.json and
specs/kings-cross.json use the flag.
At most two royal kinds a side.
movement is a list, and a piece's moves are the union of every rule that
applies to it. Two rules for the same piece give it both. Omit piece and a
rule applies to every kind.
"movement": [
{ "kind": "step", "dirs": "all8", "distance": 1 },
{ "kind": "jumpOver", "dirs": "all8", "captureJumped": true, "piece": "Rock" }
]| kind | what it does |
|---|---|
step |
a fixed distance in a direction (default 1), ignoring what is between. distance: 1 is the standard king step. |
slide |
any distance up to maxDistance, stopped by the first occupied square. A rook or a bishop — and the right shape for a pawn's double step, which must not jump a piece. |
leap |
straight to an offset, whatever stands between. A knight. |
jumpOver |
over the adjacent piece to the square beyond, optionally taking what was jumped. The checkers move. With captureJumped: true it is a capture, so it exists only over a piece this one can take; with it false it is a leapfrog and hops anybody, your own pieces included. |
place v2 |
put a new piece on an empty square instead of moving one. from and to are the same square, so every condition, effect and record keeps working unchanged. piece names the kind, at restricts where, fromReserve draws it out of a hand, and onlyIfEffective is below. Two place rules naming different kinds are two different moves on one square — see naming a placement. |
castle v2 |
two pieces move at once. The chess castle, and the only kind that names a second piece. with names the partner, distance is how far the initiator goes, and the safety rules are below. |
dirs is a named set or an explicit list of offsets:
- square:
all8,orthogonal,diagonal,sideways - hex:
all6,orthogonal,sideways - both, relative to the mover so one rule serves both sides:
forward,forwardDiagonal,backward
Anything else is { "offsets": [[1, 2], [2, 1]] }, which is how a knight or a
one-way piece is written. Offsets are in the mover's own frame: +y is
forward, away from your own home. A symmetric set — a knight's eight — reads the
same either way.
Three more fields on any rule:
targets:"empty","enemy", or"any"(the default). A pawn's quiet move istargets: "empty".when: a condition, asked before the move with bothfromandtoknown. The rule only applies when it holds — which is how a first-move-only double step is written. (Everywhere else — effects, win conditions — a condition is asked after the move. Movement is the exception because the move has not happened yet.)stalledmay not appear here; see below.mustCapture: when any move satisfying this rule exists, only moves like it are legal. Checkers' forced capture. Applied after the royal filter, so a capture that would hang your king does not force anybody to play it.
targets and mustCapture are refused on a castle: every square a castle
touches has to be empty already, so neither would restrict anything, and a field
that is read and found to say nothing is the bug class this format closes rather
than tolerates.
{ "kind": "castle", "piece": "King", "with": "Rook", "dirs": "sideways" }That line is the whole of chess castling, both wings. The initiator walks each
of dirs until it meets a piece; that piece is the partner exactly when it is
the mover's own, one of the with kinds, and has never moved. Everything
between the two of them has to be empty, which is a castle's whole path
condition. The initiator finishes distance squares along — two unless it says
otherwise — and the partner lands on the square the initiator crossed last,
which is what makes h1-f1 and a1-d1 one rule instead of two written out.
Three things it means precisely:
- It is still one pair of squares. The move is
e1-g1on the wire, in the archive and under the player's finger. Nothing above the interpreter learns a second shape of move, and a castle is unambiguous because no other rule takes a King frome1tog1. withis why the kind exists. "That Rook has never moved" is a question about a square the mover is not standing on, andhasMovedonly asks aboutfromandto. Nowhencan reach it.- Both
movedbits are set, the initiator's and the partner's. Castling rights are therefore part of the position hash already, and two boards that differ only in whether a castle is still available are different positions.
| field | default | what turning it on means |
|---|---|---|
mayStartInCheck |
false |
it may castle while under attack |
mayPassThroughAttack |
false |
it may cross a square where it could be taken |
The defaults are the rule everybody knows, so a mode that wants chess writes neither. Both are about the initiator and both are free in a mode with no royal piece, where an attack has nothing to mean.
The square it lands on is not a policy here. Every move in this format already has to leave royalty safe, so castling into check is refused by the filter a step passes through, and no opt-out reaches it.
The partner's path is not a rule. On a queenside castle the Rook crosses
b1, and b1 being attacked does not stop it — only the King is forbidden to
cross a square where it could be taken. This is the rule chess engines most often
get wrong, and conformance/corpus.json carries a case named after it.
Which leaves the interesting part: "the square the King passes over is not attacked" is a question about a square nobody lands on, and this format's condition language cannot reach it. It does not have to. It is the same question as "would the King be safe standing there", and previewing a position to ask whether royalty is takeable is exactly what the royal filter already does. So the answer is that filter, pointed one square short of the destination — a probe with no effects run, because a mode whose captures explode would otherwise detonate the square the King is standing on.
Everything else about when and where a castle may happen is the ordinary
when, asked before the move with both squares known:
// Kingside only, and not before move ten.
{ "kind": "castle", "piece": "King", "with": "Rook", "dirs": "sideways",
"when": { "and": [{ "in": ["to", { "columns": [6] }] },
{ "gt": [{ "moveNumber": true }, 10] }] } }"movement": [{ "kind": "place", "piece": "Disc", "onlyIfEffective": true }]The placement is legal exactly on the squares where the move's own on: "move"
effects change the board. Othello's rule, and specs/reversi.json is the
whole of it: one placement rule, one convert over a line, and nothing else.
It exists because that rule could already be written and could only be written
twice — once as a when that made the square legal, and again as the effect that
fired there:
// What Reversi used to say. Two copies of one board walk.
"movement": [{ "kind": "place", "piece": "Disc",
"when": { "any": { "tiles": { "region": { "line": { … } } } } } }],
"effects": [{ "on": "move", "do": [{ "convert": { "tiles": { "region": { "line": { … } } },
"to": "mover" } }] }]Nothing held the two lines together. Narrowing the flip to orthogonal and
forgetting the other copy gives a game you may play where nothing turns over;
narrowing the legality and forgetting the flip gives one that turns pieces over
on squares it will not let you play. Both validate, both play, and the rules card
reads correctly for whichever copy it happened to find. With onlyIfEffective
there is one copy, in the effect, and editing what the placement does edits
where it may go.
Three things it means precisely:
- The placement itself is not an effect. The square is expected to end up
holding the piece you put down, on the ground it already had. Only a further
change counts — which is why a
promoteon arrival, or aremovethat takes the new piece straight back off, is acting. extraTurnis not acting. It writes nothing to the board, and going again is not a thing the placement did to the position.- It costs a move played per empty square. The answer is the effects
themselves rather than a reading of them, which is the only version that cannot
drift from what the move actually does. It cannot recurse: effects run in a
context with no move generation in it, so a
stalledinside one answers false rather than asking this question again.
A place rule with onlyIfEffective and no on: "move" effect has nothing to
be effective at, so it refuses every square. That is a warning, not an error:
it is the "opening with no legal move" case, and the Lab writes a document one
rule at a time.
A condition is a yes-or-no question about the position after the move, and it
is the same little language everywhere: on a movement rule's when, on an
effect's when, and on a win condition's when.
Combine them with { "and": [...] }, { "or": [...] }, { "not": ... }.
Compare numbers with eq, lt, lte, gt, gte, each taking a pair:
{ "gt": [{ "count": { "owner": "mover", "piece": "Rock" } }, 2] }The numbers you can compare are:
| term | is |
|---|---|
7 |
itself |
{ "count": <filter> } |
how many tiles match |
{ "row": "to" } / { "column": "to" } |
a coordinate of the move just played (or "from") |
{ "moveNumber": true } |
how many moves have been played |
{ "share": "red" } |
a side's territory as a fraction from 0 to 1 |
And the questions that are not comparisons:
| condition | holds when |
|---|---|
{ "in": ["to", <region>] } |
the move landed inside a region |
{ "captured": true } |
the move took something |
{ "moved": "Rock" } |
the piece that moved is one of these kinds |
{ "any": { "tiles": <filter>, "where": <condition> } } |
some matching tile satisfies it |
{ "all": { "tiles": <filter>, "where": <condition> } } |
every matching tile does, and there is at least one |
{ "hasMoved": "from" } v2 |
that square's piece has moved before |
{ "lastMove": { … } } v2 |
a question about the move before this one |
{ "stalled": "opponent" } v2 |
that side has no legal move in the position after this one |
all over an empty set is false, not vacuously true: "every one of my pieces
has reached the far side" must not hold for a player with no pieces left. A mode
that wants the vacuous reading writes { "not": { "any": … } }.
stalled is the one predicate that costs a move generation, which is why a
movement rule's own when may not ask it — that would be a generation inside a
generation, and the validator refuses one. Everywhere else it is what lets a
placement game say "when neither of us can play, count the board".
A filter picks tiles: region, owner, piece, territory, empty, and
v2 royal. Every field is optional and they combine, so
{ "owner": "opponent", "piece": "Rock" } is "enemy pieces of that kind" and
{ "territory": "neutral" } is "unclaimed ground".
Every side reference (owner, territory, share, home, effect targets) takes
mover, opponent, red, blue, neutral or any. mover and opponent are
relative to whoever just moved, which is what lets one rule serve both players.
The position carries a bounded history slice: a per-piece hasMoved bit, the
last move (from, to, the piece, whether it captured, who played it), and the move
number. That is enough for en-passant-shaped rules and for "this piece only does
this once" — and for half of a castle. The other half, "the Rook has never
moved", is a question about a square the mover is not on, which is why castling
is a movement kind (above) rather than a condition.
{ "lastMove": { "piece": "Pawn", "by": "opponent", "distance": 2 } }| field | asks |
|---|---|
exists |
whether there was a previous move at all |
piece |
what kind moved |
captured |
whether it took something |
by |
whose move it was |
from / to |
whether its squares are in a region |
distance |
how far it travelled, in the board's own metric |
adjacentToDestination |
whether it ended next to this move's destination |
There is no move list in conditions. A rule that could look back arbitrarily far would make the cost of a position unbounded, which breaks founding rule two. The facts above are what fit.
A correctness note, because it is easy to get wrong: these bits enter the position hash. Two positions that differ only in whether a capture-in-passing is still available are different positions, and if the hash could not tell them apart the threefold-repetition draw would fire on positions that are not repetitions.
A region is a set of squares, and exactly one of:
{ "rows": [0] }, { "columns": [4] }, { "squares": [[4, 4]] },
{ "rect": { "x": 3, "y": 3, "width": 3, "height": 3 } },
{ "home": "opponent" }, { "corners": true }, { "edge": true },
{ "all": true }, { "destination": true }, { "origin": true }
and, added in v2:
| region | is |
|---|---|
{ "lastTo": true } |
the square the previous move landed on |
{ "lastFrom": true } |
the square it came from |
{ "ring": { "n": 2, "of": "destination" } } |
every tile at exactly that distance from an anchor |
{ "distance": { "n": 2 } } |
every tile within it |
{ "line": { … } } |
see below |
{ "sandwich": { … } } |
see below |
{ "surrounded": { … } } |
see below |
An anchor is destination (the default), origin, center, or subject — the
tile an enclosing any/all is currently asking about. subject is the only way
the language can say something about a member of a set rather than about the
set, and it is also what { "in": ["subject", …] } refers to.
home is the rank a side starts behind — mover, opponent, red, blue — so
"reach the far side" is one region rather than two rules with a board size
hard-coded in them. Prefer { "home": "opponent" } to { "rows": [0] }: the
first is right on any board and for either side.
The thing v1 could not say was "the tiles between two squares". Regions could name rows, columns, rectangles, corners, edges and homes, but never a relationship — so Othello flips, tafl sandwiches and custodian capture were all out of reach.
The fix is one new primitive, and the other two are sugar over it.
{ "line": { "from": "to", "dir": "all8",
"while": { "owner": "opponent" },
"until": { "owner": "mover" } } }Walk outward from from in each direction of dir. Collect tiles for as long as
they match while; stop when one matches until, and only then do the
collected tiles join the region. Running off the board, or meeting a tile that
matches neither, discards that direction's walk — which is exactly what makes a
sandwich a sandwich rather than a row of pieces with a gap in it. max bounds
the walk (default: the board's longest side) and includeEnd puts the closing
tile in the region too.
from is to (the default), from, subject, lastTo or lastFrom. The last
two are what let a rule name the ground a piece passed over, which is how an
en-passant-shaped capture finds its square:
{ "line": { "from": "lastTo", "dir": "forward",
"until": { "region": { "lastFrom": true } }, "max": 1 } }Two shapes are common enough to name:
{ "sandwich": { "piece": …, "max": 1 } }— a line of enemy pieces closed off by one of yours. Custodian capture, and tafl's whole rule.{ "surrounded": { "tiles": <filter>, "by": "mover", "dirs": … } }— tiles matching the filter whose every on-board neighbour holds abypiece.dirsdecides what "neighbour" means and defaults to the tiles sharing an edge: four on square, six on hex. That is the reading every game this exists for uses — a stone in Go is captured when its four liberties are gone, not its eight.
These compose with the effects v1 already had, which is founding rule three doing
its job: the new capability is a region, not twelve new effects. Othello's flip
is a convert whose filter is a line; tafl's capture is a remove whose filter
is a sandwich. Othello also needs the flip to decide where you may play, and
that is onlyIfEffective rather than a
second copy of the region.
Cap: 16 line regions in one spec. Each one is a board walk, and a spec that
wants more is expressing something else badly.
An effect is something a move does to the board beyond moving the piece. This is usually where a mode's character lives — territory is the whole of what makes Total War a different game from Infiltration.
"effects": [
{ "on": "move", "do": [{ "claimTerritory": "mover" }] },
{ "on": "capture", "when": { "moved": "Rock" }, "do": [{ "extraTurn": true }] }
]on is move (every move), capture (only when something was taken), or
turnEnd. when narrows it further, and lastMove inside it means the move
before this one — the same as everywhere else in the language.
| effect | does |
|---|---|
{ "claimTerritory": "mover" } |
claims the square just landed on, if nobody owns it yet |
{ "setTerritory": { "tiles": <filter>, "to": "mover" } } |
sets ownership outright — this is how you take ground somebody holds |
{ "promote": { "to": "Queen" } } |
turns the piece that moved into another kind |
{ "remove": { "tiles": <filter> } } |
takes pieces off the board |
{ "spawn": { "piece": "Rock", "owner": "mover", "at": <region> } } |
puts a new piece on the first empty square of the region, in board order |
{ "convert": { "tiles": <filter>, "to": "mover" } } v2 |
changes pieces' side without moving them |
{ "extraTurn": true } |
the mover goes again instead of passing the turn |
win is checked in order after every move, and the first condition that holds
ends the game. Order is the tie-break, and it matters: Total War checks
annihilation before territory, so a move that takes the last enemy piece and
fills the last square is a win, not a count.
{ "id": "centre", "when": { "in": ["to", { "squares": [[4, 4]] }] },
"result": "mover", "reason": "game_rule" }result is mover, opponent, draw, or a comparison:
"result": { "moreOf": { "red": { "count": { "territory": "red" } },
"blue": { "count": { "territory": "blue" } } } }moreOf hands the game to whichever side's number is larger, and calls it a draw
when they are level. Any "most X wins" rule is written with it, so majority
conditions need no special case.
id is optional and worth setting: the playtester reports which win conditions
never fired across a run of games, and it reports them by id. reason is what
a stored record says the game ended by, and shows up in the game list.
"turn": { "movesPerTurn": 1, "mayPass": false }movesPerTurn above 1 gives a side several moves before the turn passes.
mayPass means a side with no legal move passes the turn instead of drawing,
and the game ends only when neither side can move. That is what a placement game
needs; combined with { "stalled": … } it is how Reversi says "when neither of us
can play, count the discs".
"reserve": { "start": { "Block": 3 } },
"movement": [{ "kind": "place", "piece": "Block", "fromReserve": true }],
"capture": { "mode": "always", "toReserve": "mover" }A hand each side holds pieces in, off the board. Three fields, and they are
three views of one fact — which is why the block exists rather than the counts
living on the pieces. Declaring reserve is what gives a mode hands at all; a
spec without it has none and behaves exactly as it always did.
| field | does |
|---|---|
reserve.start |
what each side begins holding, by kind. Both sides start the same: a reserve is a rule of the mode, not an asymmetry between the seats — a mode that wants to give one side three walls says so in its starting position. |
place.fromReserve |
the piece comes out of the hand rather than out of thin air. Legal only where the mover holds one, and playing it spends one. With no piece, it means any kind you hold — which is the whole of a shogi drop in one line, and why piece is optional here. |
capture.toReserve |
where a taken piece goes instead of out of the game. "mover" hands it to whoever took it (shogi, crazyhouse); "owner" gives it back to the side that lost it. |
Four things it means precisely:
- A hand is part of the position. It enters the position hash, so two boards
that differ only in what somebody is holding are different positions and
threefold repetition stays correct. A mode with no
reservehashes to the string it always did. - A hand is never hidden, even under fog — the same rule territory follows, and for the same reason. A hand is spent by a drop the opponent watches land, so its size is derivable from the move list anyway, and a number a player can compute but not see is worse than one drawn honestly.
- It is capped at 64 of a kind. A mode that hands a piece back on every capture and never spends one would otherwise grow a number without bound, and "the cost of a position is bounded before anybody plays it" is one of the three rules this format is built on.
removedoes not feed a hand. Only a capture does. A piece an effect takes off the board — an atomic explosion, a plague — has left the game.
Each of the three is refused where it has nothing to act on, rather than read and
ignored: fromReserve and toReserve without a reserve block are errors,
by name. A reserve nothing draws from, or one nothing ever fills, is a
warning — it is the "opening with no legal move" case, and the Lab writes a
document one rule at a time.
specs/mark-and-block.json is the smallest mode that uses it: tic-tac-toe with a
second thing you can put down, three of them, and no way to get more.
"visibility": {
"mode": "fog",
"sight": [
{ "piece": "Scout", "distance": 3 },
{ "piece": "Scout", "distance": 5, "reveal": "presence" }
],
"spectators": "true-board"
}Default is "mode": "open" — everything visible, exactly as v1, which is what
every existing spec means.
Each of your pieces lights the tiles within distance of it, in the board's own
metric. reveal is kind (the default) or presence, which shows that
something is there without saying what — the ring without the glyph. Your own
pieces are always fully visible. Territory is never hidden: it is ground
rather than a piece, and hiding it would leak the same information back through
the share counts a win condition compares.
What it costs, stated plainly, because it is the one feature that costs an architectural property rather than just code:
- In an open game the client is a second authoritative reader — the whole spec travels inside every game state, so the browser generates its own legal moves. Under fog it is not.
- The server sends each player a filtered position and is the sole authority
on legality. This is a different message shape, not a thinned version of the
open one: no
hasMovedbits, no move list, no repetition table. A client must not be able to infer a hidden piece from the shape of what it received. - The client interpreter runs over what it can see and offers moves it believes legal. A move refused by the server is an ordinary outcome rather than a bug, and the UI says so.
- Spectators get the true board or one side's fog, declared per mode.
- The archive stores the true record and replays with full information once the game is over. A fog game you cannot review afterwards teaches nobody anything.
- The conformance corpus records the filtered view per side, so a disagreement about what a player can see is a failing test in two languages.
At most 8 sight rules: visibility is recomputed per side per move.
The caps are the same in the browser and on the server, so a spec the Lab accepts is a spec that can be published.
| at most | |
|---|---|
| board | 26 a side, 361 tiles, and at least 5 left after the outline v2 |
| pieces | 12 kinds |
beats pairs |
64 |
movement rules |
24 |
effects rules |
24 |
win conditions |
16 |
| condition nesting | 12 deep |
| offsets in one rule | 32 |
line regions in one spec |
16 v2 |
sight rules |
8 v2 |
| tiles cut out by hand | 128 v2 |
| royal kinds a side | 2 v2 |
| name / description / objective | 400 characters each |
a piece's description |
140 characters |
| the whole document | 16 KiB of JSON |
Artwork costs bytes rather than kilobytes, so 16 KiB is a bigger budget in v2 than it was in v1.
Worth knowing before you design around them.
- No randomness. No dice, no shuffles. A position's legal moves are a function of the position.
- No hidden rules. Fog hides the position, never the document. Everybody can always read what game they are playing.
- No more than two sides. Player One and Player Two, written
redandblue. - No uploaded pictures. A glyph, a shape, or a letter.
- No move-list history. Only the bounded slice above.
- No non-grid topologies beyond square and hex. A board can be cut to a shape and have holes in it, but the tiles it keeps are squares or hexes on a grid, and their neighbours are the ones they always were.
- No unknown fields. A key this format does not have is an error, and so is a
key spelled with the wrong case.
"mustcapture": truewould be a compulsory capture in one reader and no rule at all in the other, which is the worst kind of disagreement — so both refuse it. Seefrontend/src/engine/fields.tsandbackend/internal/game/spec/fields.go, which are one list written twice and checked against each other by a test.
specs/— twenty-six published modes, every one of them a worked example. Between them they use every capability listed here.conformance/corpus.json— what both readers must agree about.frontend/src/engine/andbackend/internal/game/spec/— the two readers.
{ "spec": 2, "name": "Total War", "shortCode": "V5", "description": "Pieces and territory.", "objective": "Annihilate the enemy or control most territory when the board is filled.", "board": { "width": 9, "height": 9, "palette": "slate" }, "pieces": [ { "id": "Rock", "symbol": "R", "shape": "circle", "fill": "solid" }, { "id": "Paper", "symbol": "P", "shape": "square", "fill": "hollow" }, { "id": "Scissors", "symbol": "S", "shape": "triangle", "fill": "half" } ], "beats": [["Rock", "Scissors"], ["Scissors", "Paper"], ["Paper", "Rock"]], "startingPosition": { "rows": [ "...SSS...", "...PPP...", "...RRR...", ".........", ".........", ".........", "...rrr...", "...ppp...", "...sss..." ]}, "movement": [{ "kind": "step", "dirs": "all8", "distance": 1 }], "capture": { "mode": "beats" }, "effects": [{ "on": "move", "do": [{ "claimTerritory": "mover" }] }], "win": [ { "id": "annihilation", "when": { "eq": [{ "count": { "owner": "opponent" } }, 0] }, "result": "mover", "reason": "annihilation" }, { "id": "territory", "when": { "eq": [{ "count": { "territory": "neutral" } }, 0] }, "result": { "moreOf": { "red": { "count": { "territory": "red" } }, "blue": { "count": { "territory": "blue" } } } }, "reason": "territory" } ], "draw": { "moveLimit": 300 } }