8.2 KiB
Game engine
backend/src/game/ is a small but real Magic rules engine. It consumes the compiled
effect AST from backend/src/effects/types.ts directly — there is no second card
language. Card definitions are immutable input; a GameObject is the per-game
instance that moves between zones.
Quick start
Run the data imports first (see the root README), then:
import { Game } from './src/game/game.js'
import { deckFromOracleIds } from './src/game/catalog.js'
const game = new Game({
seed: 1,
startingLife: 40,
startingHandSize: 7,
commander: true,
players: [
{ id: 'p1', deck: deckFromOracleIds(decklist1), commander: commanderCard1 },
{ id: 'p2', deck: deckFromOracleIds(decklist2), commander: commanderCard2 },
],
})
game.start()
commander: true creates each supplied commander in that player's command zone. The
deck should contain the other 99 cards; validateCommanderDeck(commander, cards)
in commander.ts checks size, singleton, color identity, and the commander type.
catalog.ts merges Scryfall card data with data/card-effects.json. It also adds
intrinsic mana abilities for basic lands, because Scryfall's oracle text only has
reminder text for them and the compiler produces no ability.
For tests or hand-authored cards, build a CardDefinition yourself:
const bolt: CardDefinition = {
oracleId: 'lightning-bolt',
name: 'Lightning Bolt',
typeLine: 'Instant',
manaCost: '{R}',
manaValue: 1,
abilities: [{
kind: 'spell',
optional: false,
text: 'Lightning Bolt deals 3 damage to any target.',
effects: [{ op: 'damage', target: { kind: 'any' }, amount: { kind: 'number', value: 3 } }],
}],
}
Actions
| Method | Purpose |
|---|---|
start() |
Shuffles libraries, draws opening hands, begins turn 1. |
playLand(playerId, cardId) |
Plays a land from hand; once per turn, main phase, empty stack. |
castSpell(playerId, cardId, { targets, x, mode }) |
Puts a spell on the stack and pays its mana cost. Accepts a commander in the command zone and adds commander tax. |
activateAbility(playerId, sourceId, abilityIndex, { targets, x, mode }) |
Activates an ability on a permanent. Mana abilities resolve immediately. |
movePermanent(playerId, cardId, x, y) |
Cosmetic board layout for a permanent you control; coordinates are 0..1 within the battlefield. |
declareAttackers(playerId, [{ attackerId, defenderId }]) |
Starts combat from the precombat main if needed. |
declareBlockers(playerId, [{ blockerId, attackerId }]) |
Declares blocks for one defending player. In multiplayer, combat damage waits until every defending player has declared or passed. |
resolveCombatDamage() |
Deals combat damage manually; passing priority also does this. |
pass(playerId?) |
Passes priority; when everyone passes, resolves the top of the stack or advances the phase. |
chooseSearchCard(playerId, cardId) |
Finishes one pick of a paused library search. |
resolveStack() |
Convenience for tests/scripts: passes priority until the stack is empty. Does not advance phases. |
endTurn(playerId) |
Ends the active player's turn, skipping remaining phases. Requires an empty stack. |
canPlayCard(playerId, cardId) |
Whether a hand or command-zone card can legally be played now, including timing, mana, and targets. |
autoAdvance() |
Passes priority for players with nothing meaningful to do; stops when someone can act or the turn ends. |
getPower, getToughness, hasKeyword |
Current characteristics after static and continuous effects. |
addCard, moveToZone |
Setup helpers for placing cards directly into zones. |
Actions that use the stack move priority to the next living player. Non-instant,
non-flash spells can only be cast in the active player's main phase with an empty
stack. Targets may be supplied explicitly; if omitted, the first legal target is
chosen automatically, which keeps scripted games short. A search effect that matches
several cards pauses instead: other actions are refused until its controller calls
chooseSearchCard (the match API uses the choose_search action).
Turn structure
untap -> upkeep -> draw -> precombat main -> begin combat -> declare attackers
-> declare blockers -> combat damage -> end combat -> postcombat main
-> end step -> cleanup -> next player's turn
The starting player skips their first draw. Cleanup discards down to seven cards,
clears damage, expires until_end_of_turn and until_end_of_your_next_turn
effects, and empties mana pools. The engine advances phases when every living
player passes in turn; it does not stop at every rules-defined priority window.
The match manager calls autoAdvance() after each action, so priority is only
shown to players who can actually do something.
Supported
- Zones: library, hand, battlefield, graveyard, exile, stack, and command zone. Tokens cease to exist when they leave the battlefield.
- Commander: command-zone casting,
{2}tax per previous cast from the command zone, return to the command zone instead of graveyard/exile/hand/library, and a loss at 21 combat damage from one commander. Deck construction is validated byvalidateCommanderDeck. - Mana: colored, generic, hybrid, Phyrexian,
{X}, and{S}costs; manual mana abilities plus automatic tapping of untapped mana sources when paying. - Costs: tap, untap, tap another permanent, pay life, discard, sacrifice, exile, putting/removing counters, mill, energy, and choice costs.
- Abilities: spell effects, activated abilities, triggered abilities (enters, leaves, dies, attacks, blocks, cast, draw, life, upkeep, end step, combat), static effects, and basic replacement effects for entering tapped/with counters.
- Effects: damage, draw, discard, mill, life, pump/set P/T, grant keyword, counters, proliferate, tokens, destroy, exile, sacrifice, counter spell/ability, zone returns, tap/untap, search/shuffle, add mana, fight, regenerate, energy, attach, restrictions, conditional and modal effects, dig, and divided damage.
- Combat keywords: flying, reach, first strike, double strike, trample, deathtouch, lifelink, vigilance, haste, indestructible. Regeneration shields replace destruction.
- State-based actions: life at or below zero, ten poison counters, 21 commander damage from one commander, lethal or deathtouch damage, zero toughness, and drawing from an empty library.
Known limitations
- Some effect nodes are accepted but intentionally do nothing yet:
prevent_damage,gain_control,emblem,transform,schedule,level_up,put_from_among,look_top,scry,surveil, andkeyword_action. Unsupported oracle lines are already marked by the compiler and never reach here. - Commander support covers single commanders. Partner, backgrounds, companions, and "choose a commander" variants are not modelled. The engine always takes the command-zone replacement instead of asking.
- The legend rule, planeswalker loyalty abilities, attacking planeswalkers, and protection/menace/defender are not implemented unless expressed as a compiled restriction.
- Modal spells choose a mode by index (
options.mode); optional "you may" choices are not modelled. An optionalpayis simply not paid when unaffordable. Search effects with several matching cards do pause for the player's pick. - Opening hands are kept automatically; there is no mulligan flow.
- Replacement/prevention effects, layers, and dependency ordering are simplified. Continuous effects apply in creation order rather than in full rules order.
- The engine is synchronous and exposes full state.
rooms.tsowns the in-memory multiplayer matches, validates decks, and sends each player a personalized view (own hand only, libraries as counts) over SSE. - There is no persistence, account system, or reconnect grace period; a server restart drops all matches.
Tests
cd backend
npx tsx --test test/game.test.ts test/commander.test.ts
The tests cover turn flow, priority, spell resolution, triggers, mana and summoning sickness, static and temporary pumps, combat, counterspells, tokens, searching, entering tapped/with counters, decking, lethal damage, commander tax and damage, decklist import, and multi-defender combat.