Files
commander/backend/docs/card-effects.md
2026-10-29 20:30:29 +01:00

18 KiB

Card effect compiler

The card database from Scryfall is English prose. The game engine cannot execute prose, so backend/src/effects/ compiles every oracle-text line into a small JSON AST. The AST is the canonical form for the engine. A pretty-printer renders the same AST as readable card source, and a matching interpreter reads that source back, so a human can replace the generated implementation of a card without touching JSON.

This is deliberately not a rules engine. It answers "what does the card say?" in machine-readable form. "What happens when it resolves?" belongs to the engine that consumes these nodes.

Pipeline

Scryfall oracle text
  -> normalize (card name, "this creature", contractions, reminder text)
  -> classify (keyword / triggered / activated / static / spell effect)
  -> parse targets, values, costs, conditions, durations
  -> JSON AST  +  card-source rendering

data/card-overrides/<oracle_id>.js
  -> safe source interpreter
  -> JSON AST used instead of the generated one

Every line is parsed as a whole. If any part of a line is not understood, the line becomes { "kind": "unsupported", "reason": ..., "text": ... } instead of a guessed effect. A wrong effect is worse than a missing one.

Commands

From backend/:

npm run compile:cards   # writes data/card-effects.json and data/card-effects.js
npm test                # compiler, source interpreter, and engine tests
npm run dev             # API for the frontend editor

Current output over the imported Commander pool (32,116 cards):

Cards: 14,239 supported, 10,088 partial, 7,789 unsupported
Ability lines: 38,132/60,470 parsed (63.1%)
  • supported — every ability line parsed.
  • partial — at least one line parsed, at least one unsupported.
  • unsupported — no line parsed.

The unsupported lines are the work queue. Re-running the compiler after adding patterns updates the numbers.

Output files

File Contents
data/card-effects.json Array of CompiledCard ASTs, one per oracle card
data/card-effects.js The same cards rendered as card source
data/card-overrides/<oracle_id>.js Human-authored implementations, one file per card

The two generated files are git-ignored. Overrides are ordinary source files and should be committed.

Compiled cards carry the Scryfall typeLine, and the game catalog uses it. An override can declare its own type line with card(...); that value wins when the card is loaded into a game.

Card source

Card source looks like a JavaScript module, but it is not executed as JavaScript. src/effects/source.ts tokenizes and evaluates a deliberately small expression subset against a fixed builder API. There is no eval, no new Function, no imports, no property writes and no access to globals: an unrecognized name or method is a parse error. This matters because PUT /cards/:oracleId/implementation is unauthenticated.

A card exports its type line and an array of abilities:

export default card('Creature — Human Cleric', [
  keywords('Flying', 'Ward {2}'),
  triggered(when.enters(each(permanents.other().withType('creature'))), [
    gainLife(you, 1),
  ]),
  activated([tapCost()], [
    addMana(you, mana('{G}')),
  ]),
])

Plain export default [...] is still accepted and uses the Scryfall type line. Multi-face cards export faces(face('Name', 'Type line', [...]), ...) in card order:

export default faces(
  face('Front', 'Instant', [spell([draw(you, 2)])]),
  face('Back', 'Creature — Human', [keyword('Flying')]),
)

Every effect list also accepts a callback. A single expression is one effect; a block is several effects, separated by newlines, ; or ,:

export default card('Creature — Human Cleric', [
  triggered(when.enters(self), () => draw(you, 1)),
  activated([tapCost()], () => {
    gainLife(you, 1)
    draw(you, 1)
  }),
])

Arrays stay valid and are still used for costs, modal modes, ability lists, card, faces and face. The formatter emits callbacks for effect lists and card(typeLine, abilities) at the top level.

The formatter writes the same shape, so a generated implementation can be copied, edited and saved as an override. formatCard and parseCardSource round-trip: comments are ignored, a leading // Card [status] line is optional, and const declarations are allowed for reuse:

const dragons = permanents.withType('creature').withSubtype('dragon').youControl()

export default card('Creature — Human Cleric', [
  staticAbility([staticPump(each(dragons), 1, 1)]),
])

Abilities

Call Meaning
keyword(name, value) One keyword, optionally parameterized
keywords(...names) Several keywords from one oracle line
triggered(event, effects, options) When/Whenever/At ability
activated(costs, effects, options) Cost : effect, including loyalty
staticAbility(effects, options) Continuous effect or restriction
spell(effects, options) Effect line of an instant or sorcery
additionalCost(costs, options) Additional cost
alternativeCost(costs, options) Alternative cast, possibly free
overload(cost) Overload alternate cost
chapter(chapters, effects, options) Saga chapter ability
levelBand(min, max, power, toughness) Level band
levelPt(power, toughness) Level P/T line
unsupported(reason, text) Preserved text plus a reason

options accepts condition and optional; activated abilities also accept timing: 'sorcery' and activationsPerTurn.

Selectors and targets

Selectors start from permanents, cards or creatures and chain filters:

permanents.withType('creature').withSubtype('dragon').withColor('red')
  .other().tapped().youControl().powerAtLeast(4)

Available filters include withType, withSubtype, withSupertype, withColor, withoutColor, withKeyword, withoutKeyword, withoutType, other, tapped, untapped, attacking, token, nontoken, equipped, enchanted, youControl, opponentControls, controlledBy, ownedBy, named, inZone, withCounter, powerAtLeast/powerAtMost, toughnessAtLeast/toughnessAtMost, manaValueAtLeast/manaValueAtMost and matchingAny.

Targets wrap a selector or player:

target(permanents.withType('creature'))
each(creatures.withColor('red'))
pick(cards.withType('land'), { upTo: 2 })
divided(3, creatures.attacking())
targetSpell(permanents.withType('instant'))
targetAbility()

Fixed targets are self, triggerSubject, previousTarget, anyTarget and targetPlayerOrPlaneswalker. Players are you, opponent, eachOpponent, eachPlayer, targetPlayer, thatPlayer, itsController and itsOwner.

Values are numbers, X, itsPower, itsToughness, count(selector), cardsInHand(player), maxCardsInHand(), maxOpponentCount(selector), totalManaValue(selector), totalPower(selector), anyNumber() and eventAmount().

Effects, costs and statics

Effects are camelCase builders, one array entry or callback statement each:

damage(target(permanents.withType('creature')), 3)
draw(you, 2)
gainLife(you, 1)
createToken(you, 1, token({ types: ['creature'], subtypes: ['goblin'], colors: ['red'], power: 1, toughness: 1 }))
createToken(you, 1, token({ name: 'Monster', types: ['enchantment'], subtypes: ['aura', 'role'] }), { attachTo: target(permanents.withType('creature')) })
putCounters(target(permanents.withType('creature')), '+1/+1', 2)
destroy(target(permanents.withType('creature')))
addMana(you, mana('{G}{G}'))
search(you, cards.withType('creature'), 1, { destination: 'battlefield', shuffle: true })
pump(each(creatures.youControl()), 1, 1, untilEndOfTurn)

Costs are distinct from effects: manaCost('{2}{U}'), tapCost(), untapCost(), sacrificeSelf(), payLife(3), discardCost(1), removeCountersCost('+1/+1', 1), exileSelf(), choice([...]) and the rest of the cost builders in source.ts.

Static effects are also distinct, so their AST shape is unambiguous: staticPump, staticGrant, staticRestrict, staticSetPt, grantAbility, entersTapped, entersWithCounters, control, choose, replace, costReduction, costIncrease, searchRestriction, exileInsteadOfGraveyard and tokenMultiplier (with optional who: 'each_player' or creatureOnly: true). entersTapped takes an optional unlessCost builder for "you may pay N life; if you don't, it enters tapped": entersTapped(self, { unlessCost: payLife(2) }).

Durations are permanent (default), untilEndOfTurn, untilYourNextTurn, untilEndOfYourNextTurn, untilEndOfCombat, untilControllersNextUntapStep and whileSourceOnBattlefield.

Triggers live under when: when.enters, when.dies, when.attacks, when.blocks, when.attacksOrBlocks, when.entersOrAttacks, when.entersOrDies, when.leavesBattlefield, when.dealsDamage, when.upkeep, when.endStep, when.beginCombat, when.firstMainPhase, when.postcombatMainPhase, when.cast, when.becomesLevel, when.draw, when.counterPlaced, when.becomesTarget, when.lifeGained and when.lifeLost.

Conditions are top-level calls such as yourTurn(), youControl(selector, n), opponentControls(selector), lifeAtLeast(player, n), wasKicked(), ifYouDo(), ifYouDont() and otherwise(). The full list is the set of condition builders in source.ts.

Nested structures are effect lists (array or callback) or ifThen/modal:

triggered(when.upkeep(you), [
  ifThen(youControl(permanents.withType('artifact'), 3), [draw(you, 1)]),
])

spell([
  modal(1, 1, [[draw(you, 2)], [gainLife(you, 3)]]),
])

Manual implementations

The frontend at /cards lists cards and filters to needs-work by default. Select a card, edit its source, and save. The API validates the source before writing it, so a typo never replaces a working file. Overrides take precedence during npm run compile:cards; invalid override files stop the compile with the line number.

Method Path Purpose
GET /cards/:oracleId/implementation Card, compiled AST, source, manual flag
PUT /cards/:oracleId/implementation Validate and save { "source": "..." }
DELETE /cards/:oracleId/implementation Delete the override, restore generated output
POST /cards/:oracleId/translate Ask OpenRouter for card source from the card's oracle text
GET /cards/:oracleId/override Raw saved source, 404 when absent
GET /stats Supported, partial, unsupported, and manual counts

CARD_OVERRIDES_DIR changes the storage directory (useful for tests).

AI drafts

The editor's Draft with AI button calls POST /cards/:oracleId/translate. The backend sends the card's oracle text to an OpenRouter model and returns card source, without saving it. The response is parsed before it reaches the browser, so prose or a non-parseable guess is reported as an error instead of replacing the editor.

Set OPENROUTER_API_KEY on the backend to enable the route. OPENROUTER_MODEL defaults to google/gemini-2.5-flash-lite.

The system prompt contains the source reference and a strict output contract: card source only, no explanations, Markdown, code fences or card header, and no invented operations. Output is capped at 1,200 tokens. A fenced answer is unwrapped defensively, but an invalid answer is not retried (that would spend more tokens). The translator uses the default model only; there is no per-request model picker.

AST

The types live in src/effects/types.ts. A card contains one or more abilities:

{
  "oracle_id": "...",
  "name": "Soul Warden",
  "typeLine": "Creature — Human Cleric",
  "status": "supported",
  "abilities": [
    {
      "kind": "triggered",
      "event": {
        "kind": "enters",
        "subject": {
          "kind": "object",
          "selector": { "other": true, "types": ["creature"] },
          "mode": "each"
        }
      },
      "effects": [
        { "op": "life", "player": "you", "amount": { "kind": "number", "value": 1 }, "mode": "gain" }
      ],
      "optional": false,
      "text": "Whenever another creature enters, you gain 1 life."
    }
  ]
}

Ability kinds

Kind Meaning Example
keyword One parameterless or parameterized keyword Flying, Ward {2}, Crew 3
keywords Several keywords on one oracle line Flying, vigilance
triggered When/Whenever/At ability When this enters, draw a card.
activated Cost : effect, including loyalty {T}: Add {G}.
static Continuous effect or restriction Creatures you control get +1/+1.
spell Effect line of an instant or sorcery Draw two cards.
alternative_cost Alternative cast with a condition, possibly free If you control a commander, you may cast this without paying its mana cost.
overload Overload alternate cost; the engine widens the spell's targets Overload {6}{U}
unsupported Preserved text plus a reason Choose one —

Effects

op Payload
damage target, amount, optional source
draw, discard, mill player, amount
life player, amount, mode: gain | lose
pump target, power, toughness, duration
grant target, keyword, optional value, duration
put_counters, remove_counters target, counter, amount
create_token player, amount, token, optional attachTo target
destroy, exile, tap, untap, regenerate target
sacrifice player, target, optional unless cost
counter what, target, optional unless cost
return_to_hand, return_to_battlefield, put_on_top target
search, shuffle player, selector, destination, optional split destination
add_mana player, mana (symbols or any_color)
scry, surveil player, amount
fight two targets
energy player, amount
attach target to attach this/trigger object to
restriction target, rule, duration
keyword_action action, optional amount, detail, target; the engine implements explore, incubate, and impulse
proliferate no payload
hideaway amount; looks at that many cards and pauses for the controller to exile one face down, linking it to the source
play_exiled player, optional free; plays a card linked with hideaway
exile_graveyards no payload; exiles all cards from every graveyard
transform target; swaps the object's front and back faces

A created token whose name or subtype matches one of the predefined tokens in comprehensive rules 111.10 gets that token's full characteristics and abilities from src/game/tokens.ts. The compiled token spec only needs enough information to identify it, for example token({ subtypes: ['treasure'] }) or token({ name: 'Monster', subtypes: ['aura', 'role'] }) for a Role.

Targets, values, costs

  • Targets are self, trigger_subject, any, player, spell, ability, or object with an ObjectSelector and mode target / each / choose.
  • Selectors carry types, subtypes, controller, colors, zone, tapped/attacking state, other, attached: equipped|enchanted, and includeSelf.
  • Values are number, x, count(selector), source_power, source_toughness, cards_in_hand, or event_amount.
  • Costs are mana symbols, tap/untap, tapping another permanent, energy, loyalty, life, discard, sacrifice, self-exile, mill, and removing counters.
  • Conditions cover controlling permanents, commander control, turn ownership, tapped source, life totals, graveyard/hand/library size, total power, distinct permanent names, and this-turn attacks and damage.
  • Static effects include pumps, keyword grants, restrictions, enters tapped/with counters, control, choices, replacements, cost reduction/increase, search restriction, and exiling cards instead of putting them into graveyards.
  • Durations cover permanent, end of turn, your next turn, the end of your next turn, end of combat, controller's next untap step, and while the source remains.

How a line is parsed

  1. Reminder text in parentheses is removed. Card names and "this creature" / "this permanent" become this.
  2. Pure keyword lines are recognized from Scryfall's keyword list plus the parameterized keyword table.
  3. Trigger prefixes (When this enters, Whenever this attacks, At the beginning of your upkeep, ...) become a TriggerEvent.
  4. A colon splits an activated ability into costs and effects.
  5. A leading duration (Until end of turn, ...) moves to the end of the effect, where the duration parser expects it.
  6. Otherwise a static effect is attempted.
  7. Instant/sorcery lines fall back to a one-shot effect (kind: "spell").
  8. Anything left over is unsupported.

Effects are split on sentences, , then, and and only when both sides parse. When you do, ... becomes a reflexive if you do condition. it becomes the trigger subject only when no explicit target/that appears in the same effect; ambiguous pronouns stay unsupported.

Adding support

For a single card, open the frontend editor, edit the source, and save; no compiler change is needed. For a whole class of cards:

  1. Run npm run compile:cards and pick a frequent unsupported pattern.
  2. Add a regex + AST builder in src/effects/compile.ts (or a target/value parser in src/effects/parse.ts).
  3. Add a focused test in test/effects.test.ts.
  4. Run npm test and npm run compile:cards.

Prefer narrow, anchored patterns. A broad pattern that misreads one card is a game bug that is hard to find later.

Known gaps

The remaining unsupported lines are mostly:

  • modal abilities (Choose one — and bullets)
  • replacement effects (If ... instead, As ... enters, ...)
  • continuous-effect layers and dependency rules
  • copy, control-change, and type-change effects
  • alternative/additional costs and cost modifiers
  • level/class/saga structures and chapter abilities
  • quoted token abilities and copying tokens
  • complex pronoun/context resolution and "for each" scaling beyond simple counts
  • dice, stickers, attractions, dungeons, and other supplemental mechanics

None of these are blocked by the AST; each needs a parser pattern and an engine implementation.