Skip to content

Latest commit

 

History

History
1034 lines (832 loc) · 50.5 KB

rulespec.md

File metadata and controls

1034 lines (832 loc) · 50.5 KB

RuleSpec: a game mode as data

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:

  1. 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.
  2. 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.
  3. 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, and what it added

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.

Naming a placement

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.

A whole mode

This is Total War, the mode this project shipped first, written out completely. Nothing in it is optional except the comments.

{
  "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 }
}

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.

What you get for free

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.

The board

"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.

What the pieces are painted v2

"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.

Hexagonal boards v2

"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:

  • all6 replaces all8. orthogonal means the six neighbours. diagonal and all8 do 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: all6 on a square board is an error.
  • The mover-relative names survive, because "away from your own home" is still well defined. forward is the two neighbours that advance a rank, backward the two that retreat one, sideways the two that advance none, and forwardDiagonal the 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.

Boards that are not rectangles v2

"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:

  • edge is a tile with a missing neighbour and corners is 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.
  • share is 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.
  • center is nudged onto the board when the middle of the rectangle was cut out, so ring and distance never measure from nowhere.
  • startingPosition.rows is 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 and captures

"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.

Artwork

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:

  1. figure — a drawing this site ships, named rather than uploaded:

    group names
    the court king queen rook bishop knight pawn
    classic sets rock paper scissors lizard spock checker checker-king bee wasp queen-bee drone
    tokens meeple stone die domino tablet
    cards card spade heart club
    war sword shield spear bow cannon banner axe helmet bomb flag ship
    ground wall gate anchor tower house tent
    weather and stone flame drop bolt snowflake leaf tree mountain sun moon wave
    the quest key chest potion scroll torch gem coin
    far away rocket alien robot ghost
    marks crown eye chevron skull target gear hourglass bell lock compass scales

    The 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.

  2. glyph — a single emoji. Still the answer for a goose, and for anything that wants colour.

  3. shape — circle, square, triangle, diamond, star or hex, with a fill of solid, hollow, half or dotted. What abstract games actually want: a checkers piece is a disc, not a drawing.

  4. the letter — symbol on 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.

Royal pieces v2

"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

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 is targets: "empty".
  • when: a condition, asked before the move with both from and to known. 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.) stalled may 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.

castle: two pieces on one turn v2

{ "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-g1 on 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 from e1 to g1.
  • with is why the kind exists. "That Rook has never moved" is a question about a square the mover is not standing on, and hasMoved only asks about from and to. No when can reach it.
  • Both moved bits 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.

The safety rules

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] }] } }

onlyIfEffective: a placement that has to do something v2

"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 promote on arrival, or a remove that takes the new piece straight back off, is acting.
  • extraTurn is 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 stalled inside 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.

Conditions

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.

History-aware conditions v2

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.

Regions

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.

Relational regions v2

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 a by piece. dirs decides 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.

Effects

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

Winning

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.

Turns

"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".

The reserve v2

"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 reserve hashes 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.
  • remove does 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.

Fog of war v2

"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 hasMoved bits, 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.

Limits

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.

What a spec cannot do

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 red and blue.
  • 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": true would 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. See frontend/src/engine/fields.ts and backend/internal/game/spec/fields.go, which are one list written twice and checked against each other by a test.

Where to look next

  • 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/ and backend/internal/game/spec/ — the two readers.