10 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 pseudocode, and a matching parser reads that pseudocode
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 + pseudocode rendering
data/card-overrides/<oracle_id>.pseudo.txt
-> pseudocode parser
-> 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 .pseudo.txt
npm test # compiler, pseudocode parser, and engine tests
npm run dev # API for the frontend editor
Current output over the imported Commander pool (32,116 cards):
Cards: 14,141 supported, 10,119 partial, 7,856 unsupported
Ability lines: 37,983/60,470 parsed (62.8%)
- 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.pseudo.txt |
The same cards rendered as pseudocode |
data/card-overrides/<oracle_id>.pseudo.txt |
Human-authored implementations, one file per card |
The two generated files are git-ignored. Overrides are ordinary source files and should be committed.
Pseudocode
# Soul Warden [supported]
on enters(each other creature):
gain_life(you, 1)
# Llanowar Elves [supported]
activate {T}:
add_mana(you, {G})
# Krenko, Mob Boss [supported]
activate {T}:
create_token(you, count(creature goblin you control), 1/1 red goblin creature)
Pseudocode is a two-way format. formatCard writes it, parsePseudoCard reads
it back into the same AST the compiler produces. Blocks are indented two spaces.
A leading # Card [status] line is ignored, and ## Face Name [status] starts a
new section for a multi-face card. Use (no abilities) when a face has none.
Manual implementations
The frontend at /cards lists cards and filters to needs-work by default. Select a
card, edit its pseudocode, and save. The editor toggles between the text view and a
node canvas where sockets are wired to define effect order and nested bodies; both
edit the same source. 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 pseudocode 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 pseudocode, 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 syntax reference and a strict output contract: pseudocode only, no explanations, Markdown, code fences or card header, and no invented operations. Output is capped at 700 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",
"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. |
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 |
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 |
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 |
proliferate |
no payload |
Targets, values, costs
- Targets are
self,trigger_subject,any,player,spell,ability, orobjectwith anObjectSelectorand modetarget/each/choose. - Selectors carry types, subtypes, controller, colors, zone, tapped/attacking
state,
other,attached: equipped|enchanted, andincludeSelf. - Values are
number,x,count(selector),source_power,source_toughness,cards_in_hand, orevent_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, turn ownership, tapped source, life totals, and graveyard size.
- 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
- Reminder text in parentheses is removed. Card names and "this creature" /
"this permanent" become
this. - Pure keyword lines are recognized from Scryfall's keyword list plus the parameterized keyword table.
- Trigger prefixes (
When this enters,Whenever this attacks,At the beginning of your upkeep, ...) become aTriggerEvent. - A colon splits an activated ability into costs and effects.
- A leading duration (
Until end of turn, ...) moves to the end of the effect, where the duration parser expects it. - Otherwise a static effect is attempted.
- Instant/sorcery lines fall back to a one-shot effect (
kind: "spell"). - 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 pseudocode, and save; no compiler change is needed. For a whole class of cards:
- Run
npm run compile:cardsand pick a frequent unsupported pattern. - Add a regex + AST builder in
src/effects/compile.ts(or a target/value parser insrc/effects/parse.ts). - Add a focused test in
test/effects.test.ts. - Run
npm testandnpm 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.