Write the rules.
Cardz deals.

Reference for Cardz .cardz game files: cards, board layout, rules, deals, and goals.

Game files

A .cardz file is JSON. Double-click it, or use Import… in Your games, to add it to Cardz. It holds either the game object itself or the export wrapper { "schemaVersion": 1, "setup": { … } }.

This complete four-column Klondike variant uses most of the vocabulary; each part is explained below.

{
  "name": "Pocket Patience",
  "description": "Build each suit up from Ace on the foundations. Columns build down in alternating colours, and only a King fills an empty column.",
  "depotOnly": true,
  "rules": {
    "foundation": { "seed": "Ace", "build": { "direction": "Up", "step": 1 }, "suit": "Same" },
    "column": { "seed": "King", "build": { "direction": "Down", "step": 1 }, "suit": "AlternateColor" }
  },
  "depots": [
    { "name": "stock", "type": "Stock", "col": 0, "row": 0,
      "draw": { "to": "waste", "count": 1, "recycle": true },
      "landFace": "Down", "ejectRule": "locked" },
    { "name": "waste", "type": "Waste", "col": 1, "row": 0,
      "acceptRule": "none", "ejectRule": "topOnly" },
    { "name": "foundation", "type": "Foundation", "col": 3, "row": 0, "repeat": 4,
      "acceptRule": "$foundation", "ejectRule": "locked" },
    { "name": "column", "type": "Tableau", "col": 0, "row": 1, "repeat": 4, "autoFlipTop": true,
      "acceptRule": "$column", "ejectRule": "faceUp" }
  ],
  "dealRules": [
    { "kind": "dealGroup", "to": "column", "faceDown": 2, "faceUp": 1 }
  ],
  "winCondition": { "kind": "allCardsIn", "depots": "Foundation" }
}

JSON format

• Property names are camelCase; enum values are capitalized and spelled out ("Tableau", "AlternateColor", "King"). Both are read case-insensitively, but Cardz writes these forms.
• Deal steps and win/loss conditions name their variant in kind (both explained below).
• Omitted properties take the defaults listed below.
• Some fields accept a short form, noted with the field. Cardz exports the full form.

Top-level properties

Players can switch a game's rules off: every depot then accepts and releases cards freely, depotOnly stops applying, and the table modes return.

Deck composition

decks is a list of packs. Cardz expands each pack, combines them, then shuffles.

A pack holds (suits × ranks + jokers) × count cards; a game holds at most 208.

• Standard: leave decks out, or write [ {} ] → 52. Two decks: [ { "count": 2 } ] → 104.
• Spider 1-suit: [ { "suits": ["Spades"], "count": 8 } ] → 104 spades.
• Spider 2-suit: [ { "suits": ["Spades","Hearts"], "count": 4 } ].
• Stripped 32-card (7–Ace): "ranks": ["Seven","Eight","Nine","Ten","Jack","Queen","King","Ace"].
• A separated deck: [ { "ranks": ["Jack","Queen","King"], "to": "monsters", "back": 1 }, { "ranks": ["Ace", … ,"Ten"], "back": 1 } ] puts the court cards on the monsters depot and the rest in the stock, each shuffled.

Copies alternate between two card backs. A pack that sets back shows that back on every copy.

Depots

depots is a list of depot objects: the places that hold cards.

Depot patterns

Some fields name a set of depots: acceptFrom, autoSend, autoRefill, and the depots of win/loss conditions (all below). A pattern is either { "ofType": "Foundation" } (every depot of that type) or { "names": ["reserve"] } (the named depots); set exactly one. Either may be written bare: "Foundation" or ["reserve"].

Depot rules

Besides its layout, a depot says how it handles cards, what may land on it (acceptRule), what may leave it (ejectRule), what a tap does (draw) and what moves by itself (autoSend, autoRefill). An acceptRule or ejectRule may be written "$name" to use a rule from the top-level rules.

Card handling

acceptRule — what may land

acceptRule is "any" or omitted (no restriction), "none" (reject all drops), "emptyOnly" (only into an empty depot), or an object with the fields below, all of which must pass. Fields shown without a type are true/false.

Build and suit rules

build and suit compare a card with the one it lands on. acceptRule uses them, and so does an eject Run unit (below).

• build: direction is Up, Down or Either. step is 0–12, default 1 (0 matches equal ranks). wrap builds through King↔Ace. Cards that pair by a total, as in Pyramid, use an expression instead (see "Rule expressions").
• suit: Any (default), Same, AlternateColor or SameColor.

ejectRule — what may leave

ejectRule decides what the player may pick up from this depot. It has two parts:

• gate: which card may be picked up. Any (default): any card. FaceUp: any face-up card. TopOnly: only the top card. Locked: nothing. A rule that is only a gate may be written as its name: "any", "faceUp", "topOnly", "locked".
• unit: which cards leave with it.
  • Omitted: the picked card and every card above it. The receiving depot's acceptRule checks the whole group, each card against the one beneath it.
  • Single: only the picked card; the cards above it stay.
  • Any: the picked card and every card above it, in any order.
  • Run: the picked card and every card above it, if they follow the unit's own build and, optionally, suit.
  • Pile: the whole pile, whichever card is picked, as in Accordion.

Write it { "kind": "Run", "build": …, "suit": … }. "single", "any" and "pile" may be written bare, and {} means Any.

A declared unit vouches for the group, so the receiving depot's acceptRule checks only the group's bottom card. A foundation fed by an Any unit should therefore set single: true, or it will take an unordered pile.

draw — tapping a stock

draw makes a depot a stock the player taps. Drawn cards skip the target's acceptRule. A depot with draw takes no drops; make its eject "locked" so cards leave only by tapping.

• to: the depot drawn cards land on, face-up.
• count: cards per tap, default 1; a short stock draws what is left.
• recycle: tapping the empty stock brings the whole to pile back, reversed and face-down.
• maxRecycles: how many recycles are allowed; omitted means unlimited, 0 none.

autoSend and autoRefill — automatic moves

Both take a depot pattern. An automatic move is one you could make by hand: the source's ejectRule decides what lifts, the target's acceptRule what lands.

• autoSend: move this depot's largest legal top group to the first matching depot that accepts it.
• autoRefill: while this depot is empty, move one card into it from the first matching depot that releases one.

They run whenever cards land, including draws and redeals (below), and cascade until the board settles; one undo takes back the lot. The opening deal does not trigger them.

Give the target a strict rule: autoSend onto a depot that accepts anything empties its source, and two depots refilling from each other loop until the cascade limit.

Deal steps

dealRules is the opening deal: a list of steps run in order. Without it, every card starts in the stock. redealRules is a second list the player runs during play by tapping the stock it deals from; each run deals from what is left there.

A dealGroup or a gather may add when, a rule expression (see Rule expressions below) that keeps only the depots it holds for: the deal skips the other to depots, and the gather leaves the other from depots where they are. In the expression, depot names each one in turn, and every depot is judged before the step moves a card. Gaps deals the Aces out with one, then takes them away with { "kind": "gather", "from": ["cell"], "to": "aces", "when": "top(depot).rank == Ace" }.

redealWhen is a condition that must hold for a redeal to run, written like winCondition (see Win & loss conditions below).

maxRedeals caps the redeals after the opening deal: omitted means unlimited, 0 none. Every run counts once, even a short one, and all the stocks a redeal deals from share the cap.

Win & loss conditions

winCondition and lossCondition describe the board that ends the game. Cardz checks them after each move and declares a win or a loss as soon as one holds. Both are optional: leave one out and the game never ends that way.

Fields named depots take a depot pattern.

winCondition:

• allCardsIn (depots): every card is on a matching depot.
• allCardsFaceUp: every card is face-up.
• depotsEmpty (depots): every matching depot is empty.
• depotsNonEmpty (depots): every matching depot has a card; mostly for redealWhen.
• allOf / anyOf (of): all / any of the listed conditions.
• expr (when): the rule expression holds; see Rule expressions below.

lossCondition:

• noLegalMoves: no card can move and no tap does anything. Needs depotOnly. A landUnder move counts only if it reveals a card. Suits games that really run out of moves; with unlimited recycles or easy shuttling it rarely fires.
• expr (when): the game is lost as soon as the rule expression holds. Unlike noLegalMoves it doesn't need depotOnly.

Rule expressions

A rule expression is a condition written as text, which Cardz checks against the board. It can only read the board, never change it, and it always gives an answer.

This game uses some of them:

{
  "name": "Climb to Ten",
  "description": "Draw three cards at a time, and play them all before drawing again. A tower takes a higher card than its top, or a card that makes ten with it. Discard what you can't play. Five discards lose; play out the deck with fewer to win.",
  "depotOnly": true,
  "decks": [ { "ranks": ["Ace","Two","Three","Four","Five","Six","Seven","Eight","Nine","Ten"] } ],
  "depots": [
    { "name": "stock", "type": "Stock", "col": 0, "row": 0,
      "draw": { "to": "hand", "count": 3, "when": "empty(hand)" },
      "landFace": "Down", "acceptRule": "none", "ejectRule": "locked" },
    { "name": "hand", "type": "Waste", "col": 1, "row": 0, "fanDirection": "Right", "looseOrder": true,
      "acceptRule": "none", "ejectRule": { "gate": "Any", "unit": "Single" } },
    { "name": "tower", "type": "Foundation", "col": 0, "row": 1, "repeat": 3,
      "acceptRule": { "single": true, "acceptFrom": ["hand"],
        "when": "empty(depot) || card.value > top.value || card.value + top.value == 10",
        "reason": "Climb higher, or make ten with the top card" },
      "ejectRule": "locked" },
    { "name": "discard", "type": "Reserve", "col": 4, "row": 0, "fanDirection": "Down",
      "acceptRule": { "single": true, "acceptFrom": ["hand"] }, "ejectRule": "locked" }
  ],
  "winCondition": { "kind": "expr", "when": "empty(stock) && empty(hand) && count(discard) < 5" },
  "lossCondition": { "kind": "expr", "when": "count(discard) >= 5" }
}

Values

Every part of an expression resolves to a value: a literal number, a word like Hearts, a depot's name, or what a function returns. Each value is of one kind: numbers can be added, cards have properties, lists can be counted. The kinds are:

• Numbers (7), conditions (true, false), cards, lists of cards, depots and lists of depots.
• Ranks (Ace … King), suits (Clubs … Spades) and colours (Red, Black), written capitalised.
• A depot type (Tableau) means every depot of that type. The name of a repeated depot (tower for tower-1 … tower-3) means all its copies.
• A depot name means that depot. Names can't contain -, so a depot can also be written depot("tower-2").
• Wherever cards are wanted, a depot stands for the cards on it, bottom first, and a list of depots stands for all their cards.

Operators

Operators join values into a larger expression, much as in a spreadsheet formula: arithmetic for numbers, comparisons for conditions, and &&, || and ! combine conditions. The whole expression must end up as a condition, except where a number is expected, as in a move's count or a game's scoring.

|| (or), && (and), ! (not), ==, !=, <, <=, >, >=, +, -, *, %, and parentheses. && binds tighter than ||, and % binds like *. % is the remainder, never negative for a positive divisor, so (top.value - card.value) % 13 counts round the corner from King to Ace; anything % 0 is 0. Only numbers and ranks can be ordered, and comparisons don't chain. let name = …; rest names a part so the rest can use it: let monster = base(depot); monster.value >= 11.

Card properties and functions

A card has the properties rank, suit, color, value (Ace 1 … King 13, a joker 0, unless the game's values change it), faceUp and joker.

There are also the following functions:

The functions that iterate over a list (count, all, any, first, min, max, sum) work out their second argument once for each item, calling the item it. That argument is an expression: a condition for count, all, any and first, a number for min, max and sum. So sum(column, top(it).value) adds up the columns' top cards. A repeated depot's name lists its copies in order, so first(cell, empty(it)) is the lowest-numbered empty cell. To ask about two lists at once, name the items instead: c in discard in place of the list. any(c in discard, count(d in discard, d.rank == c.rank) >= 4) is true once four cards of one rank are in the discard.

What an expression can't see

An expression always gives an answer. Where a value is missing or hidden, it reads as blank rather than causing an error. An empty pile or a face-down card never breaks a rule, but it may not give the answer you expect, so check for it with empty or faceUp where that matters:

• No card is an answer, not an error: top of an empty pile is no card. Its faceUp and joker are false, its value is 0, and it has no rank, suit or colour. A comparison with something it lacks is false, and != is true. So top.suit == Hearts on an empty depot is simply false.
• No depot is an answer too: neighbour past the end of a row, or a first that finds nothing. It holds no cards, so it is also empty.
• Face-down cards are counted but not read: they have no rank, suit or colour and are worth 0. A rule can't look at the stock's order.
• Nothing is remembered: an expression sees the board as it is now, not what happened earlier.

A game that uses expressions, triggers or actions offers no hints and can't be auto-played. The respective buttons are hidden on the UI.

Cardz checks every expression when a game is imported or played from the editor. A misspelt name, a property a card doesn't have, or a suit compared with a number are errors, and are indicated as such. An expression may be at most 2000 characters long.

Triggers and actions

Expressions decide whether something may happen. Triggers and actions make things happen. Both are a condition and a list of steps, declared on a depot:

• triggers: [{ "when": …, "do": [steps] }]. Whenever cards land anywhere, each trigger whose when holds runs its steps, until the board settles. Triggers rest while the rules are off, and don't fire during the opening deal or on undo.
• actions: [{ "name": …, "when": …, "do": [steps] }]. Tapping the depot performs the first action whose when holds (no when means always). While an action is available the depot works like a stock: pressing its cards acts instead of picking them up. A draw on the same depot comes first.

The steps are deal steps (see Deal steps above). In a step, @self names the depot the trigger or action is on. Conditions see that depot as depot. A step's depot may also be an expression, read when the step runs: neighbour(depot, 1) is the next copy along, and first(cell, empty(it)) the first empty cell. Two extra step fields that can be used:

• count on a move: how many top cards move together, keeping their order and faces. It is a number or an expression, read when the step runs.
• under on a move: the cards go beneath the target's cards instead of on top. A move from a depot to itself with under cycles it.

The following game is played entirely through one depot, the loop. Its two actions take turns: look turns the top card up, and travel uses that card's value as a count, cycling that many cards to the bottom with under. A trigger watches for an Ace on top and moves it to aces. Moving the Ace away also makes the trigger's when false, so it stops firing.

{
  "name": "Round the Loop",
  "description": "Tap the loop to turn its top card up, or to travel: a face-up card sends that many cards from the top of the loop to the bottom. An Ace that comes to the top is taken. Take all four.",
  "depotOnly": true,
  "decks": [ { "ranks": ["Ace","Two","Three","Four","Five"], "to": "loop" } ],
  "depots": [
    { "name": "loop", "type": "Reserve", "col": 0, "row": 0,
      "acceptRule": "none", "ejectRule": "locked",
      "actions": [
        { "name": "look", "when": "!empty(depot) && !top(depot).faceUp",
          "do": [ { "kind": "flipTop", "depot": "@self" } ] },
        { "name": "travel", "when": "!empty(depot) && top(depot).faceUp",
          "do": [ { "kind": "move", "from": "@self", "to": "@self", "count": "top(depot).value", "under": true } ] }
      ],
      "triggers": [
        { "when": "!empty(depot) && top(depot).faceUp && top(depot).rank == Ace",
          "do": [ { "kind": "move", "from": "@self", "to": "aces" } ] }
      ] },
    { "name": "aces", "type": "Foundation", "col": 2, "row": 0,
      "acceptRule": "none", "ejectRule": "locked" }
  ],
  "winCondition": { "kind": "expr", "when": "count(aces) == 4" }
}

Values and scoring

values determines what cards are worth, for when a game counts them differently from their pips: { "J": 10, "Q": 10, "K": 10, "joker": 10 }. A rank is written as in a deck (A, 2 … 10, J, Q, K) and joker is any joker. A rank left out keeps its pip value. Every expression in the game reads cards by these values: card.value, sum.

scoring gives a solitaire a score: { "value": …, "better": …, "keep": … }.

A score can also read four facts about the game:

So Spider's classic score is 500 - moves + 100 * count(Foundation, !empty(it)): 500 to start, one off for every move, and 100 for each completed run on the foundations.

The player sees the score as they play. Depending on keep, a deal keeps its score when it ends, unless rules were turned off at any time or automatic moves were made. A game with no winCondition keeps no scores.

The following game uses both. values makes court cards worth 10, so sum and card.value count them that way, both in the columns' accept rule and in the score. scoring leaves better and keep at their defaults: a higher total is better, and only a won deal keeps its score.

{
  "name": "Under Twenty-One",
  "description": "Tap the stock to turn up a card, then play it to a column or the discard. A column takes a card while its total stays at 21 or under. Court cards are worth 10 and an Ace 1. Play out the deck to win. Your score is the three columns' total, 63 at best.",
  "depotOnly": true,
  "depots": [
    { "name": "stock", "type": "Stock", "col": 0, "row": 0,
      "draw": { "to": "hand", "count": 1, "when": "empty(hand)" },
      "landFace": "Down", "acceptRule": "none", "ejectRule": "locked" },
    { "name": "hand", "type": "Waste", "col": 1, "row": 0,
      "acceptRule": "none", "ejectRule": { "gate": "Any", "unit": "Single" } },
    { "name": "column", "type": "Tableau", "col": 0, "row": 1, "repeat": 3,
      "acceptRule": { "single": true, "acceptFrom": ["hand"],
        "when": "sum(depot) + card.value <= 21", "reason": "A column holds 21 at most" },
      "ejectRule": "locked" },
    { "name": "discard", "type": "Reserve", "col": 4, "row": 0, "fanDirection": "Down",
      "acceptRule": { "single": true, "acceptFrom": ["hand"] }, "ejectRule": "locked" }
  ],
  "values": { "J": 10, "Q": 10, "K": 10 },
  "winCondition": { "kind": "expr", "when": "empty(stock) && empty(hand)" },
  "scoring": { "value": "sum(column)" }
}

Teaching Cardz to play

The Hint, Play best move and Play for me buttons need a player that understands the game. A game written in rule expressions, triggers or actions doesn't offer them unless it opts in:

"planner": true

With true, Cardz makes its usual choices: it sends cards to the foundations, completes pairs, and taps the stock when nothing else helps. Opt in when those choices play your game sensibly; Monte Carlo's win about a third of its deals.

"planner": false does the opposite: it takes the buttons away from any game, even one written without expressions, for a game where Cardz's usual choices would mislead. Leave planner out for the default: the buttons for a game written in fixed fields, none for one that uses expressions, triggers or actions.

A game can also say what it is aiming for:

"planner": { "value": "20 * count(clear) - 15 * count(damage)" }

value is a rule expression that gives a number, read on the whole board: higher for a board closer to a win. To choose a move, Cardz tries each legal move on a copy of the board and takes the one that leaves the highest value. A move that wins comes first, and one that loses comes last. If no move raises the value, Cardz falls back on its usual choices, such as tapping the stock.

The copy is the board as the player sees it: face-down cards stay hidden, so the planner can't see anything a player couldn't. Players never see the value, and it changes no rule. Changing it doesn't reset a game's statistics.

The planner looks only one move ahead. A value that rises only when a whole goal is reached can't tell the moves that build toward it apart, so reward progress along the way where a game has some.

Card aids

A card aid is a symbol or a sign that a deck may prints on a card. The game indicates aids that can help the player; a deck that draws an aid then shows it. Players can turn card aids off, and the switch appears only when the game and the deck share one.

Pyramid removes pairs that total 13, so it asks for "aids": { "pairSum": 13 }: a 10 shows a 3, and a King shows nothing.

Cards are counted by their pips default values (Ace 1 … King 13) or by the game's values if used.

Card aids change no rule, and changing them doesn't reset a game's statistics.

Conventions the rules leave to the player

Some setup rituals and courtesies have no rule field, such as La Belle Lucie's merci or sinking the Kings in Baker's Dozen. Describe them in description and leave the move to the player and the table modes.

Canonical encodings

Common patterns, with JSON quotes left out:

• Klondike: each tableau column accepts { seed: King, build: { direction: Down }, suit: AlternateColor }, ejects faceUp, and sets autoFlipTop: true.
• FreeCell: cells accept { emptyOnly: true, single: true }; compoundMoves: Staged; the stock is offTable.
• Spider: decks [{ suits: [Spades], count: 8 }]. Foundations accept { emptyOnly: true, seed: King, build: { direction: Down }, minCount: 13 }. The tableau ejects { gate: FaceUp, unit: { kind: Run, build: { direction: Down } } } with autoSend: Foundation. Four-suit Spider uses [{ count: 2 }] and adds suit: Same to the unit.
• Golf: the tableau accepts none and ejects topOnly; the foundation accepts { build: { direction: Either } }; the stock has draw: { to: foundation } without recycle; loss noLegalMoves.
• Pyramid: each slot ejects faceUp and is uncoveredBy the two cards covering it; it accepts { single: true, seed: none, when: "card.value + top.value == 13 && all(c in coveredBy(depot), c != source && empty(c))" }, and a trigger moves both cards to the discard once it holds two. The stock's face-up top takes a partner the same way; the discard accepts { single: true, rankIs: K } with landFace: down; the waste accepts { single: true, when: "source == stock || (!empty(depot) && card.value + top.value == 13)" }, so a stock card is set aside and a pyramid card pairs with its top, and a trigger moves the two to the discard when its top card came from a pyramid slot (cameFrom). The redeal gathers the waste back into the spent stock and turns up its top, maxRedeals: 2; loss noLegalMoves; scoring { value: "28 - count(d in Tableau, !empty(d))", keep: Over }.
• Crazy Quilt: cells accept none, eject faceUp, and are uncoveredBy both short-end neighbours with uncoveredByAny: true; foundations accept { seed: Ace, build: { direction: Up }, suit: Same } or { seed: King, build: { direction: Down }, suit: Same }, over two decks; the stock draws with recycle: true, maxRecycles: 1.
• Clock: each hour pile accepts { rankIs: <its hour> } and sets landUnder: true; win allCardsFaceUp, loss noLegalMoves.
• Yukon: the tableau ejects { gate: FaceUp, unit: any }; foundations add single: true.
• Flower Garden: the bouquet accepts none, ejects { unit: single }, and sets looseOrder: true.
• Canfield: foundations accept { seedFromDeal: true, build: { direction: Up, wrap: true }, suit: Same } and eject locked; the tableau sets autoRefill: [reserve].