Files
commander/backend/docs/game-engine.md
2026-10-27 19:14:33 +01:00

10 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, overload }) Puts a spell on the stack and pays its mana cost. Accepts a commander in the command zone, adds commander tax, and can pay the overload cost instead.
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.
chooseCreatureType(playerId, type) Answers an "as this enters, choose a creature type" prompt.
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). The match API also sends the chooser the full searched pool (searchPool) so the UI can show and filter the library; only searchCandidates are legal picks. A permanent with "as this enters, choose a creature type" also pauses play: pendingChoice records the controller and the permanent, and the match API refuses other priority actions until chooseCreatureType (the choose_type action) receives one of the creature types in CREATURE_TYPES. The chosen type is stored on the object and cleared when it leaves the battlefield.

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, free alternative costs while you control a commander, 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. Static cost reductions and increases apply while their source is on the battlefield.
  • Abilities: spell effects, overload, 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 and exiling cards instead of putting them into graveyards.
  • Effects: damage, draw, discard, mill, life, pump/set P/T, grant keyword, counters, proliferate, tokens, destroy, exile, exile all graveyards, sacrifice, counter spell/ability, zone returns, tap/untap, search/shuffle, add mana, fight, regenerate, energy, attach, restrictions, conditional and modal effects, dig, divided damage, hideaway, and playing a card exiled with hideaway.
  • Restrictions and conditions: activated abilities can be disabled, opponents can be limited to the top N cards when searching, cards can begin the game on the battlefield from the opening hand, and conditions can count commander control or distinct permanent names.
  • 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.
  • "As this enters, choose a creature type" pauses for a pick and stores the type on the permanent, but no effect reads the chosen type yet. The other choose kinds (color, card name, player, opponent, number) are accepted and ignored. Cavern of Souls' mana is not restricted to the chosen type and does not make the spell uncounterable.
  • Hideaway automatically exiles the top card and does not track cards as face down. play_exiled only supports the free "without paying its mana cost" case.
  • Overload widens only top-level effect targets; a nested modal or conditional target keeps its printed target. Free alternative costs are modelled only for controlling a commander, and search restrictions cap the searching player's own library.
  • 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.