Rules, primitives & actions

Why this file exists

The earlier documents were written before anyone had authored a real game. Doing that surfaced two things: the model is sound, but the action layer is both under-specified and over-enumerated. This file records what we settled on, so the engine gets built against decisions rather than guesses.

D1 · Three layers, and only one of them is code

The composite layer earns its place even though it adds nothing the primitives can't express: players and designers think in verbs (“buy”), cost and legality attach to a whole transaction rather than to each primitive, simulation reports read in the designer's vocabulary, and the AI needs a small named set to generate cards against.

This also resolves the muddle in mechanics-core.json / mechanics-effect.json / mechanics-system.json, which currently list primitives (move_card), composites (draw_cards), a legality rule (check_target_validity) and a trigger (combo_trigger) side by side as if they were peers. Those three files get re-sorted into the layers above; legality and triggers move out of “mechanics” entirely.

D2 · The seven primitives

Closed set. Everything else composes from these.

A card's effects are themselves composites of these, so “fire the card's effects” is recursion, not another primitive.

D3 · Today's nine actions, decomposed

Five of the nine catalog entries are the same primitive with different parameters. This is what makes the composite layer data rather than code.

Acquisition needs no further actions: buying, drawing, tutoring, stealing and recruiting are all “move a card into a zone I control” with a different from-zone.

D4 · Actions are enabled and bound, together

Enabling an action must bind its parameters to this game's zones and trackers, chosen from dropdowns and pre-filled from the preset. Not doing this is a live bug:

Gating stays, but as a consequence of binding rather than a separate rule: if no zone can satisfy a shape's from-parameter, the preset can't be configured and is offered greyed, with the reason. Phases keep referencing actions by id, which already works.

D5 · Currency is a binding, never a tracker property

We will not hardcode which trackers may be spent. Paying life to buy or to act is a published mechanic (Magic's Phyrexian mana; “pay 7 life, draw 7”), and a model that forbids it is already too narrow.

Spendability is a property of the transaction, not the tracker — Combat is not un-spendable, it is spent on attacking. So the cost tracker is one of the parameters bound in D4:

buy_card:   { from: trade_row, to: discard, cost: { source: card.cost, currency: trade } }
attack:     { cost: { tracker: combat }, applies_to: { tracker: authority, of: opponent } }

A game where cards are bought with life sets currency: authority. Nothing in the engine objects. Multi-currency costs (“2 wood + 1 brick”) are expressible because a binding may name several allowed denominations.

An optional tracker hint — spendable, defaulting true for role: resource and false for role: score — may exist to pre-filter dropdowns and to warn (“nothing can ever spend this tracker”). It is advisory only and must never block a binding.

The data for this partly exists already: the catalog declares default_cost_tracker: "trade" for buying and "combat" for attacking. A grep for those keys across the whole codebase returns zero consumers — which is exactly why the generator priced a card at {trade: 3, combat: 2}.

D6 · The card model — three axes, content, metadata rewritten 2026-08-03 — to be curated

Re-evaluated from scratch, grounded in the five consumers of card data: the engine (legality + resolution), other cards' rules (group references), the AI generator (constraints + steering), the renderer (template + fields), and balancing (copies, distribution, reports). The rule: every axis must answer a question no other axis answers, and each consumer gets exactly one place to look.

The three classification axes

Subtype: a shortcut, not an axis

A subtype is a pre-configured instance of a type — a shortcut that, when chosen, sets values on the real axes: its parent type, some forced behaviours (forces_behaviours), stat tendencies, and AI hints (“glass cannon”). The engine never reads it; by the time the engine looks, the subtype has already become type + behaviours + fields. It is stored on the card (subtype: "unit__stealth") as provenance and for re-generation consistency. The catalog's own _meta already says most of this; the correction is that a subtype can force behaviours, so “the engine ignores it” is true only because its effects are materialised at authoring time.

MTG's creature types (“other Elves get +1”) look like subtypes but are mechanically families — addressable groups. That is why the router below asks the family question before the subtype question.

The router — where does a new idea go?

1. Does it change what fields the card has, or where it can be? → Type
2. Is it a yes/no keyword that changes engine handling? → Behaviour
3. Do rules need to reference the group during play? → Family
4. Does it only steer generation? → Subtype (a preset)

The card definition, final shape

{
  "name":        "Salvage Vanguard",
  "type":        "unit",                        // axis 1 — exactly one, root id
  "behaviours":  ["Permanent", "Blitz"],        // axis 2
  "families":    ["scrapper_guild"],            // axis 3 — array; v1 uses max 1
  "subtype":     "unit__stealth",               // preset used; provenance only
  "cost":        { "trade": 3 },                // content — denominated per D5
  "attributes":  { "attack": 2, "health": 3 },  // content — shaped by type+behaviours
  "effects":     [ { "effect_key": "…", "trigger": "on_play", "parameters": {} } ],
  "description": "…",
  "gen":         { "img_prompt": "…", "strength": "medium" }   // engine-invisible
}

Normalisation on save (same pattern as the 3.4 trigger work): the AI keeps emitting one label (unit__stealth); the save path splits it into type root + subtype, fills the so-far-unused card_type/card_subtype columns, and coerces families to an array. meta_tags dissolves later (its type → axis 1, strength → gen, family → axis 3) — the distribution queries still read it, so that is a separate curated step, not part of this change.

Decisions taken rather than reopened: family membership is max one per card in v1 (Star Realms model) with the schema already array-shaped per D9, so multi-guild is an enable, not a migration; the schema term stays family — “Guilds” is what a given game may name its families.

D7 · A Rules step, placed after Decks

Phases, actions and setup reference zones, trackers, card types and decks. Today they live on Anatomy, which runs before Decks, so the deck→zone mapping asks for deck ids that will not exist for two more steps — the UI admits it: “Decks not authored yet show as a free-text field.”

New order, so every reference resolves at the moment it is asked for:

1. Briefing
2. Skeleton      trackers · zones · win conditions · effects vocabulary
3. Card types    the shapes cards come in
4. Decks         containers + frequency distribution (needs card types)
5. RULES         phases · actions (enable-and-bind) · setup   ← everything it references exists
6. Cards         generated knowing the rules
7. Layout

Card types move ahead of Decks because the frequency distribution already slices by type. Cards move after Rules, which also makes generation better informed.

D8 · Design is iterative; the tooling must assume it

A game is authored, simulated, found wanting, and revised — several times. Two consequences:

• Suggestions become proactive. The machinery already exists: effects and actions grey out when prerequisites are missing and un-grey live when the piece is added. The change is direction — from “this stays grey until you add a life tracker” to “you added Authority; deal_damage and attack_opponent just became possible, enable them?”
• Referential integrity becomes load-bearing. v2 means renaming a tracker and deleting a zone that other things point at. SchemaStore.findReferencesTo() stops being a nicety.

And the reason the simulator comes before polish: a design can't be validated statically. You run it.

D9 · Wire everything; ship a subset. What an “ability” actually is

We are not building a deck-builder tool. The primitives must be able to express the whole 95% band — deck-builders, set-collection, drafting, trick-taking — even while only a small subset is switched on for testing. Anything left out now is left out as a disabled feature, never as a missing wire.

“Ability” is three different things

The capability registry

Every primitive, composite and feature is declared in one registry with an honest status, and an admin page lists them so support is switched on step by step.

This fixes a trap we have already hit: the action catalog contains activate_ability, described as “Card defines the ability's cost and effect” while no such field exists anywhere — and the authoring UI happily shows it ✓ ready. Declared-but-not-implemented becomes a visible state instead of a lie.

Where the ceiling honestly sits (from the six-game analysis in the model doc): the resolution stack with priority windows, dynamic-scope continuous effects, per-instance rewriting of a card's text, and simultaneous-play phases. Those separate “a card game engine” from “Magic”, and stay ceiling until something forces them.

What this changes in the engine plan

Everything already built stays: the Game object, the flat zone map, the seeded RNG, the JSON Logic evaluator, unified trackers, effect triggers. This only reshapes apply()'s interior and the action data feeding it.

Evidence — what authoring a real game proved

Starforge Rivals (eb362133ac184632000ad893d754d6e4) was authored end to end through the UI on 2026-08-03. All earlier games in the database are testing scratchpads and prove nothing about the authoring model.

The four questions — answered 2026-08-03

The original wording of each question is kept below for context.

Q1 · Should a card be able to do something while it sits on the table?

In Star Realms a Base stays in play and you may use it on your turn — “tap this for 2 Trade.” Today a card can act when it is played, automatically at the start or end of a turn, or when it is destroyed. What it cannot do is sit there offering the player a choice. Nowhere in the card schema is there a place to write such an ability down.

Recommendation: skip for v1. Nothing in the app can store it today, and the deck-builders we're targeting play fine without it. Add it the first time a design actually needs it.

Q2 · When an action has a huge number of possible choices, do we list them all?

“Deal 2 damage to a target” with thirty cards on the table is thirty different versions of the same action. The simulator works by laying out every complete option so a bot can pick one — and on a big board that list can get very long, which makes each simulated turn slower.

Recommendation: cap at 50 and log whenever the cap is actually hit, so we find out whether it ever matters instead of guessing.

Q3 · Do we support rules that can't be expressed by filling in a form?

Most rules are settings: which zone, how many cards, what it costs. Some are not. In a trick-taking game, “you must play the suit that was led, if you have one” is a condition, and no amount of dropdowns expresses it.

Recommendation: leave the UI unbuilt until you want a trick-taker. The underlying mechanism already exists, so this stays cheap to add later.

Q4 · Do we ship ready-made example games to start from?

Starting from a blank game stays fully supported either way — that is settled. The question is only whether we also ship a couple of complete, pre-filled games (a deck-builder, a trick-taker) that a designer can open and edit instead of building from nothing.

Recommendation: yes, but later — and the first one is free, since Starforge Rivals can simply be saved as one.

(A fifth question — what happens to already-saved games when the steps are reordered — answered itself: step order is only navigation, the stored data is identical either way.)

Pending — the simulator arc written 2026-08-03, after 3.1–3.13 shipped

The full loop exists and runs: author → skeleton cards for free → simulate (random + greedy, web batches of 10 or CLI/cron) → report (win balance, end reasons, length, demand, dead cards) → replay any seed decision by decision. What follows is what is honestly not done, in priority order. This section is the working TODO for the engine; strike items as they land.

Findings — the Dominion probe 2026-08-03

Dominion was authored as a definition file (game-defs/dominion.json) and imported deliberately including everything we suspected DeckCraft cannot express. The import report and two simulated games recorded fourteen concrete gaps. Headline: the game ended on turn 1 with zero actions taken — the supply piles never filled, so “Province pile empty” was true at setup, and the unimplemented winner rule crowned p0 by fallthrough. Each row names the missing feature.

Reading of the probe: the model held — trackers, zones, phases, types and cards all expressed Dominion's structure without contortion. What failed is concentrated in three places: setup's deck→zone plumbing (G5/G6), ending resolutions (G7/G8), and the binding parameters the Rules step was always going to own (G9–G11). Nothing new was wrong with the axes.

Findings — the Ascension probe 2026-08-03

Ascension (game-defs/ascension.json): center-row deck-builder with dual currencies, defeat-to-void, and a shared honor pool. Much of it worked on arrival — three market zones bound (center row + both always-available piles), the row refilled to 6 from its feeder, Runes-and-Power dual costs priced correctly via the currency fallback, and Permanent constructs generated per-turn income. Seed 1: p1 ended with 88 honor to p0's 53 — and the game was declared a draw. The gaps:

Reading: G5/G6/G1 already paid off — the market machinery, setup fills and draw effects carried a second genre with zero new authoring gaps. Ascension's genuinely new asks are the defeat transaction (A1/A2) and shared-pool effects (A3); everything else is polish on known items.

Next — highest value per effort

Soon — unblocks depth

Later / when it hurts