Files
commander/AGENTS.md
2026-10-29 15:21:05 +01:00

2.3 KiB

AGENTS.md

Online multiplayer Magic: The Gathering (Commander) emulator: Nuxt frontend + Fastify API with a synchronous rules engine that executes compiled card effects.

Layout

  • backend/ — Node 24, Fastify 5, TypeScript (ESM, NodeNext). src/effects/ is the oracle-text compiler/card-source DSL, src/game/ the rules engine and in-memory match manager.
  • frontend/ — Nuxt 4 / Vue 3, sources under app/.
  • backend/docs/card-effects.md and backend/docs/game-engine.md are the detailed references for those subsystems; README.md has the full API and config tables.

Commands

docker compose -f docker-compose.dev.yml up --build   # full dev stack (:3000, :4000)
cd backend && npm install && npm run dev              # API only
cd frontend && npm install && npm run dev             # UI only
cd backend && npm test                                # all backend tests
cd backend && npm run import:cards                    # Scryfall bulk data -> data/cards.json
cd backend && npm run compile:cards                   # oracle text -> data/card-effects.json + card-effects.js

Things to know

  • Backend imports need .js extensions (NodeNext) even though sources are .ts.
  • backend/data/cards.json (~21 MB) and card-effects.json are generated, not committed; run the import/compile scripts after changing the importer or compiler. Missing card data makes /cards return 503.
  • Manual card implementations live in backend/data/card-overrides/ (one file per card, card-source DSL) and take precedence over generated output when compiling.
  • Asked to implement a specific card: write that card's override JS, then implement whatever the effect needs in the game engine (backend/src/game/) so the card actually works in a game — an override alone is not a finished card.
  • The effect compiler is conservative: unparseable oracle lines become unsupported with original text — never guess or silently drop them.
  • Matches are in memory and lost on restart; accounts, saved decks, playmat preferences, and per-deck card backs are in MongoDB through backend/src/accounts.ts. Game seats still use a per-seat token in the frontend's sessionStorage; the account login token is in a cookie so the server can gate pages.
  • Keep style of surrounding code: 2-space indent, single quotes. No linter or formatter is configured.