2026-10-29 15:21:05 +01:00
2026-10-29 15:21:05 +01:00
2026-10-29 15:21:05 +01:00
2026-10-27 12:42:57 +01:00
2026-10-27 12:42:57 +01:00
2026-10-29 15:21:05 +01:00
2026-10-27 12:42:57 +01:00
2026-10-27 12:42:57 +01:00
2026-10-29 15:21:05 +01:00

Commander

Online multiplayer Magic: The Gathering (Commander) emulator.

This repository holds a Nuxt frontend, a Fastify API, and a working Magic rules engine that executes the compiled card effects. You can build or import a Commander deck in the browser and play a 2–4 player match against other clients.

Stack

  • frontend/ — Nuxt 4, Vue 3, TypeScript, server-side rendering
  • backend/ — Node 24, Fastify 5, TypeScript, Mongoose
  • MongoDB — accounts, saved decks, playmat and card-back preferences
  • Docker Compose — hot-reloading development stack and standalone production images

Requirements

  • Docker with Compose v2
  • Node 24 + npm only if you want to run the apps outside Docker
  • MongoDB reachable on localhost:27017 (the Compose backend uses host networking to reach it)

Development

Start both services with hot reload:

cp .env.example .env   # optional: adjust public URLs and ports
docker compose -f docker-compose.dev.yml up --build
Service URL
Frontend http://localhost:3000
API http://localhost:4000
Health http://localhost:4000/health
MongoDB mongodb://localhost:27017

Source directories are bind-mounted, so edits reload automatically. Dependencies live in named volumes and are synced on container start. If the volumes get into a bad state, reset them with:

docker compose -f docker-compose.dev.yml down -v

Stop the stack with docker compose -f docker-compose.dev.yml down.

Without Docker

# terminal 1
cd backend && npm install && npm run dev

# terminal 2
cd frontend && npm install && npm run dev

The backend listens on port 4000 and the frontend on 3000 by default. It connects to MongoDB at mongodb://localhost:27017/commander; start a local MongoDB or set MONGODB_URI to point somewhere else.

Card data

Cards come from Scryfall's Oracle Cards bulk export — one card per Oracle ID, filtered to cards legal in Commander.

cd backend
npm run import:cards

This downloads the bulk file and writes backend/data/cards.json (about 21 MB, not committed). It stores each card's rarity and the formats it is legal in, so re-run it after pulling changes to the importer. Re-run it whenever you want a fresh card pool.

In the dev stack the file is visible through the bind mount. For production, run the import before docker compose build so the API image includes the data. If the file is missing, the card endpoints return 503 with a reminder to run it.

Card art is not bundled. The first time a card's art is requested, the API downloads its image from Scryfall and stores it in backend/data/images/. The production Compose stack keeps that directory in the card_images named volume, so the cache survives restarts. Delete the directory to reclaim the space; images are downloaded again when needed.

Card effects

Oracle text is compiled into a machine-readable effect AST for the game engine. The compiler is conservative: a line it cannot parse is marked unsupported with its original text, never guessed.

cd backend
npm run compile:cards   # data/card-effects.json + data/card-effects.js
npm test

data/card-effects.js is the human-readable card source. The source is also an input format: the frontend editor saves one override file per card under backend/data/card-overrides/, and npm run compile:cards validates those files and uses them instead of generated output. Card source looks like JavaScript but is evaluated by a safe interpreter with a fixed builder API, never by eval. See backend/docs/card-effects.md for the DSL, current coverage, and how to add support for more cards.

The /cards page has an Editor view and a Guide view that summarizes the source syntax. Draft with AI sends the selected card's oracle text to an OpenRouter model and loads the returned source into the editor without saving it. The model is instructed to answer with card source only — no explanations, Markdown or code fences — and the answer must parse before the API returns it. Set OPENROUTER_API_KEY on the backend to enable the button; OPENROUTER_MODEL defaults to google/gemini-2.5-flash-lite.

Game engine

backend/src/game/ is a synchronous rules engine built on that AST. It covers zones, turns, priority, the stack, mana and costs, triggered/activated/static abilities, combat, state-based actions, and effect resolution.

import { Game } from './src/game/game.js'
import { deckFromOracleIds } from './src/game/catalog.js'

const game = new Game({
  seed: 1,
  players: [
    { id: 'p1', deck: deckFromOracleIds(decklist1) },
    { id: 'p2', deck: deckFromOracleIds(decklist2) },
  ],
})
game.start()
game.playLand('p1', cardId)
game.castSpell('p1', spellId, { targets: [{ kind: 'player', id: 'p2' }] })
game.resolveStack()

Commander is a first-class format: the commander starts in the command zone, pays {2} more for each previous cast from that zone, returns to the command zone instead of the graveyard or exile, and loses the game at 21 combat damage from a single commander. Deck construction checks 100 cards, singleton, color identity, and a legendary-creature commander.

See backend/docs/game-engine.md for the action API, turn and combat flow, supported mechanics, and known limitations. The engine tests live in backend/test/game.test.ts and backend/test/commander.test.ts:

cd backend
npx tsx --test test/game.test.ts test/commander.test.ts

Playing online

The frontend has five pages:

  • /account — create an account or sign in. The API stores only a username, a salted password hash, and the player's saved data in MongoDB.
  • / — create a 2–4 player game, join an open lobby, and pick your playmat.
  • /decks — build a deck, import a Moxfield/Archidekt/Arena text export, and export it again. Decks are stored with your account.
  • /cards — the existing card implementation editor and source guide.
  • /games/:id — lobby and game board. The page can also be used as an invite link; a player with no seat gets a join form.

Matches live in the API process and are lost on restart. Each player only receives their own hand and libraries as counts; the server sends personalized state over server-sent events (SSE), and actions come back over POST. The browser keeps the login token and a random per-seat game token in localStorage/sessionStorage; accounts and saved decks, playmat choices, and each deck's card back live in MongoDB. Each player can pick card art or upload a JPEG as their own playmat; the choice is shown to everyone in the match and remembered in the account for new games you host or join. Card backs are chosen per deck in the deck editor and used for that deck's library pile.

Production

Build and run the optimized images:

cp .env.example .env   # optional: adjust public URLs and ports
docker compose up -d --build
Service Default URL
Frontend http://localhost:3000
API http://localhost:4000
docker compose ps          # status and health
docker compose logs -f     # follow logs
docker compose down        # stop

The production frontend image runs the built Nuxt output directly. The backend image builds TypeScript and installs production dependencies only.

Configuration

Variable Default Used by Description
NUXT_PUBLIC_API_BASE http://localhost:4000 frontend Public, browser-facing URL of the API
CORS_ORIGIN http://localhost:3000 backend Allowed browser origin(s), comma separated
MONGODB_URI mongodb://localhost:27017/commander backend MongoDB connection string
FRONTEND_PORT 3000 production Host port for the frontend
BACKEND_PORT 4000 production Host port for the API
PORT 4000 backend Port the API listens on inside the container
CARD_OVERRIDES_DIR backend/data/card-overrides backend Where manual implementations are stored
OPENROUTER_API_KEY — backend Enables the editor's AI card-source draft
OPENROUTER_MODEL google/gemini-2.5-flash-lite backend OpenRouter model used for translation

When deploying to a real host, set NUXT_PUBLIC_API_BASE and CORS_ORIGIN to your public URLs. Both values are applied at runtime in the production image.

Project layout

.
├── backend/
│   ├── scripts/import-cards.ts  # Scryfall bulk importer
│   ├── scripts/compile-cards.ts # oracle text -> effect AST + card source
│   ├── src/cards.ts         # card store, lookup, and search
│   ├── src/images.ts        # on-disk cache for Scryfall card art
│   ├── src/effects/         # effect DSL, compiler, formatter, source interpreter
│   ├── src/effects/translate.ts # natural language -> card source through OpenRouter
│   ├── src/game/            # rules engine, commander rules, match manager
│   ├── src/accounts.ts      # Mongo models, auth, decks, and preferences
│   ├── src/server.ts        # Fastify entry point and game/deck routes
│   ├── test/                # compiler, source, engine, and commander tests
│   ├── docs/card-effects.md # DSL reference and coverage
│   ├── docs/game-engine.md  # engine API, rules coverage, limitations
│   ├── data/cards.json      # generated by npm run import:cards
│   ├── data/card-overrides/ # human-authored implementations, one file per card
│   ├── Dockerfile           # dev, build, and production stages
│   └── package.json
├── frontend/
│   ├── app/app.vue          # app shell and navigation
│   ├── app/assets/main.css  # shared theme and layout
│   ├── app/pages/index.vue  # create/join a game
│   ├── app/pages/account.vue # sign in, register, and sign out
│   ├── app/pages/decks.vue  # deck builder and decklist import/export
│   ├── app/pages/games/[id].vue # lobby, board, and live match client
│   ├── app/pages/cards.vue  # card implementation editor and guide
│   ├── app/middleware/auth.ts # redirect signed-out visitors to /account
│   ├── app/utils/auth.ts    # login token storage and headers
│   ├── app/utils/decks.ts   # account deck API and validation
│   ├── app/components/SourceGuide.vue # card source guide view
│   ├── nuxt.config.ts       # runtime config (API base URL)
│   ├── Dockerfile           # dev, build, and production stages
│   └── package.json
├── docker-compose.dev.yml   # hot-reload development stack
├── docker-compose.yml       # production stack
├── .env.example
└── README.md

API

/auth/me and every /me/* route require the Authorization: Bearer <token> header returned by /auth/register or /auth/login.

Method Path Response
GET /health { "status": "ok", "service": "commander-api" }
GET /cards?q=atraxa { total, cards } name search, limit capped at 200
GET /cards/:oracleId One card object, or 404
GET /cards/:oracleId/image Card face as JPEG; downloaded from Scryfall once and cached on disk
GET /cards/:oracleId/art Wide card art crop used for playmats, cached on disk
GET /cards?status=needs-work Filter by supported, partial, unsupported, needs-work, manual, all
GET /cards?format=modern&color=U&type=creature&rarity=rare&cmcMin=1&cmcMax=3 Format legality, color identity (WUBRG includes that color, C colorless, M multicolor), card type, rarity, and mana value filters
GET /cards/:oracleId/implementation Card, compiled AST, card source, manual flag
PUT /cards/:oracleId/implementation Validate { "source": "..." } and save the override
DELETE /cards/:oracleId/implementation Delete the override and restore generated output
POST /cards/:oracleId/translate Ask OpenRouter for card source from the card's oracle text
GET /cards/:oracleId/override Raw override source, or 404
GET /stats Supported, partial, unsupported, and manual counts
POST /auth/register Create an account with { username, password }, returns { token, username }
POST /auth/login Sign in with { username, password }, returns { token, username }
POST /auth/logout Invalidate the current bearer token
GET /auth/me Current account, requires Authorization: Bearer <token>
GET /me/decks The account's saved decks
PUT /me/decks/:id Create or replace a saved deck
DELETE /me/decks/:id Delete a saved deck
POST /me/decks/:id/share Create (or reuse) a share link token for a saved deck
GET /decks/share/:token Public read of a shared deck, used to import a copy
GET /me/preferences Saved playmat and card back
PUT /me/preferences Update { playmat?, cardBack? }
POST /decks/import Parse a text decklist into { commander, cards, errors }
POST /cards/resolve Resolve exact card names: { names: string[] }
GET /games Open and active matches
POST /games Create a match from { name, deck, maxPlayers, playmat? }
POST /games/:id/join Join a lobby with { name, deck, playmat? }
POST /games/:id/leave Leave a lobby or forfeit an active game with { token }
POST /games/:id/deck Change your lobby deck with { token, deck }
POST /games/:id/start Host starts the match with { token }
POST /games/:id/playmat Set your playmat with { token, playmat: { kind: "card", oracleId } | { kind: "upload", data } | { kind: "none" } }
GET /playmats/:id Uploaded playmat image
POST /games/:id/actions Submit { token, action }
GET /games/:id/state Personalized state, requires ?token=
GET /games/:id/events Personalized SSE stream, requires ?token=

Next steps

  • More compiled effects and rules coverage (prevention, control changes, planeswalkers)
  • WebSocket transport if SSE backpressure becomes a problem
  • Persistence for live games and match history
  • Matchmaking, spectators, and reconnect/afk handling
  • Partner commanders, companion, and the rest of the Commander variants
Description
No description provided
Readme 1.1 MiB
Languages
TypeScript 77.3%
Vue 21.9%
CSS 0.6%
Dockerfile 0.1%