Files
commander/backend/docs/game-engine.md
2026-10-27 12:42:57 +01:00

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 by validateCommanderDeck.
  • 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, and keyword_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 optional pay is 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.ts owns 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.