Argentum Engine

Before the oil. Before the corruption. There was only perfection.

An unofficial Magic: The Gathering rules engine and online play platform. Not affiliated with, endorsed, sponsored, or specifically approved by Wizards of the Coast LLC.

Play now at magic.wingedsheep.com · Join our Discord

Want to help? Missing a card from your deck? Run just contribute and let Claude Code or Codex build it — see Contributing.

---

Overview

Argentum Engine is a modular MTG implementation composed of:

• Rules Engine — A deterministic Kotlin library implementing MTG comprehensive rules
• Game Server — Spring Boot backend for online multiplayer
• Web Client — Browser-based UI
• Gym — An RL/MCTS environment wrapper around the rules engine, with an HTTP transport for Python training loops
• Argentum Assay — A bidirectional Oracle-text parser that measures, card by card, how much of Magic the card SDK can express

Implementation Progress

Live set completion tracker → magic.wingedsheep.com/set-completion — per-set coverage, and every card in a set marked implemented, missing, or not planned. Missing cards that Argentum Assay already reads end to end are flagged ⚡ Assay-ready: they need no new engine vocabulary, so they're the cheapest ones to pick up. The same page carries the Assay explorer as a second tab.

Distinct implemented cards, day by day since the project began. Regenerated daily by the Refresh card progress workflow, which runs scripts/card-progress-graph (an interactive version lives at card-implementation-progress.html).

Getting Started

Prerequisites

• JDK 21+
• Node.js 18+
• Docker (optional, for Redis)
• just command runner

Quick Start

# Initialize environment
just init

# Start Redis (optional, for session persistence)
just docker-up

# Start the game server
just server

# In another terminal, start the web client
just client

The client runs at http://localhost:5173 and connects to the server at http://localhost:8080.

Available Commands

Build & Test

Command	Description
just build	Build the entire project
just test	Run all tests
just test-rules	Run rules-engine tests only
just test-server	Run game-server tests only
just test-gym	Run gym tests only
just test-gym-server	Run gym-server HTTP tests only
just test-gym-trainer	Run gym-trainer (MCTS + self-play) tests only
just clean	Clean build artifacts

Development

Command	Description
just server	Start the game server (port 8080)
just gym-server	Start the gym HTTP server (port 8081) — for RL/MCTS training
just client	Start the web client dev server
just client-install	Install web client dependencies

Environment

Command	Description
just init	Create .env from .env.example
just docker-up	Start local Docker services (Redis)
just docker-down	Stop local Docker services
just docker-logs	View Docker logs

Environment Variables

Copy .env.example to .env to configure:

Variable	Default	Description
CACHE_REDIS_ENABLED	false	Enable Redis for session persistence
REDIS_HOST	localhost	Redis host
REDIS_PORT	6379	Redis port
GAME_AI_ENABLED	true	Enable AI opponent
GAME_AI_MODE	engine	AI mode: engine (built-in), llm (requires API key), jev (local profile), or the mode of a registered AiControllerProvider. An unrecognised value fails startup.
OPENROUTER_API_KEY		Shared OpenRouter API key for llm and jev modes
GAME_AI_MODEL	google/gemini-3.1-flash-lite-preview	LLM model (only for llm mode)

Tech Stack

• Kotlin 2.2
• Spring Boot 4.x
• React / TypeScript (frontend)
• Redis (optional session persistence)
• Keycloak (OAuth/authentication)

Features

Drafting

Host booster drafts with up to 8 players. Create a draft lobby, invite friends, and build your deck from freshly opened packs.

Play

Play Magic against friends with fully implemented MTG rules. The engine automatically handles the stack, priority, combat, triggers, and state-based actions—so you can focus on the game.

Free-for-All Multiplayer

Play multiplayer Free-for-All games for 2–6 players (CR 806). From a lobby, switch the mode toggle from Tournament to Free-for-All to seat every player in a single shared game instead of a 2-player bracket — any pool-building format (sealed, draft, custom decks) composes with it.

Eliminated players are removed from the table while the remaining seats play on: conceding (or losing) takes you out, your opponents' boards keep going, and the opponent rail shows a live tombstone for anyone knocked out. Standings follow elimination order, and a "Play Again" ready loop lets the pod rematch without rebuilding the lobby.

AI Opponent

Play against an AI opponent using the built-in engine, a chat model, or Jev (local development).

Engine AI (default)

The built-in rules-engine AI runs locally with no external dependencies. It uses multi-ply game tree search with alpha-beta pruning, a composite board evaluator, and a specialized combat advisor.

Works out of the box — no API key or configuration needed:

# AI is enabled by default in engine mode
GAME_AI_ENABLED=true
GAME_AI_MODE=engine

Start the server and client, then click "Play vs AI" on the main menu.

LLM AI (optional)

Alternatively, you can use an LLM-powered AI that sends game state to an OpenAI-compatible API for decisions.

Setup:

1. Get an API key from openrouter.ai (or any OpenAI-compatible provider)
2. Add to your .env file:

GAME_AI_ENABLED=true
GAME_AI_MODE=llm
OPENROUTER_API_KEY=sk-or-v1-your-key-here
# GAME_AI_MODEL=google/gemini-3.1-flash-lite-preview  # optional, change model

The LLM AI receives the same masked game state as a human player and responds through the standard game protocol. When the LLM fails to respond or returns an unparseable answer, it falls back to heuristic play.

Jev (local development)

Jev makes structured choices through OpenRouter's Decisions API. Add these to your .env, then run just dev (which activates the local Spring profile):

GAME_AI_ENABLED=true
GAME_AI_MODE=jev
OPENROUTER_API_KEY=your-openrouter-key

Choose Just me, pick a deck source, and start playing (or use Add AI in a lobby); the opponent's name ends in (Jev). No Ollama or TypeSafe account is needed. The default model is typesafe/jev-1.13. Jev shares OPENROUTER_API_KEY with OpenRouter chat models and has its own endpoint, so local Ollama defaults cannot redirect its requests. Do not put Jev in GAME_AI_MODEL: that setting uses the chat-completions protocol.

Jev chooses plays, targets, X, modes, attackers, blockers, damage assignments, card selections, ordering, piles, additional/alternative payments, mulligans, bottom cards, and draft picks. Ordinary mana payment can use the engine solver when Jev selects auto-pay. Sealed deck construction uses the existing heuristic builder. All gameplay choices use typed options from server metadata; the engine previews the completed action and supplies validation feedback for one correction. The engine AI is used only after a failed request, exhausted budget, or invalid corrected move; server logs explicitly report fallback. Jev receives the player's masked view, permitted decision metadata and known decklist. The provider rebuilds a masked view even when local debug mode reveals both hands on screen; debug event logs are excluded from requests.

Variable	Default	Description
GAME_AI_JEV_MODEL	typesafe/jev-1.13	Decisions model
GAME_AI_JEV_ENDPOINT	https://openrouter.ai/api/alpha/decisions	Decisions endpoint (also useful for a local mock)
GAME_AI_JEV_TIMEOUT_MS	30000	Total budget per decision, including follow-up choices and correction; max 120000

The adapter caps each decision at 64 API calls and each request at 28 KB to stay conservatively within the model context window. Choices with more than 255 options use hierarchical selection; they are not silently truncated. Very large positions can hit the budget and fall back. This is an experimental opponent, not a claim of competitive playing strength. Calls are billed by OpenRouter. The jev provider is registered only under the local profile; other profiles reject that mode.

Configuration reference

Variable	Default	Description
GAME_AI_ENABLED	true	Enable the AI opponent feature
GAME_AI_MODE	engine	engine — built-in AI (no API key needed); llm — LLM-powered AI; jev — local Jev opponent; or the mode of an AiControllerProvider bean supplied by another build. An unrecognised value fails startup.
GAME_AI_BASE_URL	https://openrouter.ai/api/v1	LLM API endpoint (LLM mode only)
GAME_AI_API_KEY		API key for LLM provider (LLM mode only)
GAME_AI_MODEL	google/gemini-3.1-flash-lite-preview	LLM model name (LLM mode only)
GAME_AI_DECKBUILDING_MODEL		Separate model for AI deckbuilding; falls back to GAME_AI_MODEL if not set (LLM mode only)

Architecture

argentum-engine/
├── mtg-sdk/              # Shared contract — DSLs, data models, primitives
├── mtg-sets/             # Aggregator — re-exports the whole card corpus, plus the set catalog
│   ├── core/             # CardDiscovery, token art, cards belonging to no set
│   └── <era>/            # Card definitions, one module per release-year range (`just where <SET>`)
│       └── tests/        # That era's card scenario tests
├── rules-engine/         # Core MTG rules engine (no server dependencies)
├── gym/           # RL/MCTS environment wrapper (GameEnvironment, MultiEnvService)
├── gym-server/    # Spring Boot HTTP transport for gym (Python trainers)
├── gym-trainer/   # JVM-side MCTS + self-play SPI for AlphaZero-style projects
├── game-server/          # Spring Boot game server & matchmaking
├── web-client/           # React/TypeScript browser UI
└── e2e-scenarios/        # Playwright end-to-end tests

Rules Engine

The rules engine is a standalone library with no server dependencies. It models the complete game state immutably and exposes a pure functional API:

• Full turn structure (phases, steps, priority)
• Stack and spell resolution
• Combat (attackers, blockers, damage assignment)
• Triggered, activated, and static abilities
• Keywords (flying, trample, deathtouch, morph, cycling, and more)
• State-based actions
• Targeting and legality checks
• Rule 613 layer system for continuous effects
• Replacement effects

Cards are defined as pure data using a Kotlin DSL — no card-specific logic in the engine.

Gameplay Platform

Server

• Create games with invite links
• Booster draft with up to 8 players
• Sealed deck tournaments
• Free-for-All multiplayer games (2–6 players, CR 806)

Client

• Real-time game state sync via WebSocket
• Targeting, combat, and decision UIs

Gym — RL & MCTS Environment

For agent research and reinforcement-learning training, the engine also ships as a Gymnasium-style environment. A trainer drives many games in parallel against a stable JSON contract, without touching the game server or the browser UI.

Library — gym

A transport-agnostic Kotlin library that wraps the rules engine in a stateful reset / step / observe / legalActions API with MCTS-friendly affordances:

• Immutable state + O(1) fork — GameEnvironment.fork() returns a sibling env pointing at the same GameState. Because state is never mutated in place, tree expansion is free.
• Snapshot / restore — MultiEnvService.snapshot() returns an opaque handle; restore() swaps the env back to that state in O(1). Designed to grow a byte-blob variant for cross-process MCTS workers.
• Batch stepping — MultiEnvService.stepBatch() fans out per-env steps across a work-stealing pool, so vectorised rollouts run in parallel.
• Decision-aware — pauses on PendingDecisions (scry, targets, search, distribute…); simple decisions fold into the numeric action-ID space, complex ones expose a structured response channel.
• Stable observation schema — TrainingObservation has a schemaHash so Python clients fail fast on contract drift; every observation carries a stateDigest usable as an MCTS transposition-table key.
• Information hiding — opponent hand and libraries are masked by default; revealAll is available for debug scripts.

HTTP transport — gym-server

A thin Spring Boot shell that exposes MultiEnvService over HTTP so a Python agent can drive the engine without a JVM embedding:

Method & path	Maps to
POST /envs	MultiEnvService.create
GET /envs	listEnvs
DELETE /envs	dispose
GET /envs/{id}	observe
POST /envs/{id}/reset	reset
POST /envs/{id}/step	step
POST /envs/step-batch	stepBatch
POST /envs/{id}/decision	submitDecision (structured DecisionResponse)
POST /envs/{id}/fork?count=N	fork
POST /envs/{id}/snapshot	snapshot
POST /envs/{id}/restore	restore
GET /schema-hash	observation-schema version (fail-fast on drift)
GET /health	liveness probe

JSON is handled end-to-end by kotlinx.serialization — sealed hierarchies (DeckSpec, DecisionResponse) round-trip via @SerialName discriminators without extra adapter code.

Start the server with just gym-server (port 8081, so it doesn't collide with the game server on 8080). Running it does not require the web client or Redis.

Deliberately out of scope for the current scaffold: authentication, env-lifetime TTLs, byte-based snapshots, metrics. Bind to localhost until you add auth.

JVM-side trainer — gym-trainer

For AlphaZero-shaped projects that want tree search in the JVM and only use Python as a stateless NN inference server (MageZero-style): a small SPI + a PUCT MCTS + a self-play loop.

• Four plug-in traits: StateFeaturizer<T>, ActionFeaturizer (multi-head first-class), Evaluator<T>, SelfPlaySink<T>.
• Built-in AlphaZeroSearch with PUCT, optional Dirichlet root noise, using GameEnvironment.fork() for O(1) tree expansion.
• Built-in SelfPlayLoop with temperature schedule that labels training rows with the final outcome before flushing.
• Batteries-included defaults so a training loop runs end-to-end with zero NN setup: a heuristic evaluator wrapping the engine's BoardEvaluator, a structural featurizer, a hash-bucket action featurizer, a JSONL sink, and a random structured-decision resolver.
• Wire format kept minimal — RemoteHttpEvaluator POSTs features + legal slots and parses {priors, value}. Swap codec by subclassing.

See gym-trainer/README.md for the full design write-up and a 30-line hello-world.

Contributing

Contributions are very welcome, and I'm genuinely grateful for every PR. To keep the project healthy, there's one rule above all others:

No slop PRs. A reviewer's time is the scarcest resource here. Please open a PR only when it's been tested, it's faithful to the actual Magic rules (no shortcuts), and every change in it is there on purpose. Built with a frontier model through just contribute? Great — the gate and review it runs are exactly that check. A large unverified PR is still worth less than a small careful one.

Quick start: contribute cards with an AI agent

The fastest way to help is to make the cards you want to play work. One command walks you through it:

just contribute

It checks your setup, then asks three questions:

1. What to build — your deck or card list (paste any Moxfield / Archidekt / MTGA export, type card names, or drop the file into the terminal), or a whole set by code or name. It shows how many of the cards already work before anything starts.
2. Which agent and model — whichever of Claude Code and Codex you have installed, with a model of your choice.
3. How to deliver it —
   • Local branch, one PR at the end (the default, and the only option without push access). The agent works through the missing cards a batch at a time; each batch is tested (just loop-gate), reviewed by fresh-context subagents, and committed on one local branch. Nothing is pushed. When it's done, skim the commits, push the branch to your fork, and open one PR.
   • Pull requests (maintainers with push access). Each batch becomes a reviewed PR that merges once CI is green.

Cards that need new engine features aren't faked: the agent records them as gaps and builds each missing capability properly (with the add-feature skill) before the cards that need it.

You'll need: JDK 21+, just, git, jq, Python 3, and Claude Code or Codex. The GitHub CLI (gh) is optional — it lets the agent skip cards someone else's open PR already adds.

Before you start: main is the source of truth for what's implemented; open PRs are what's in flight. Check how much of a deck already works with:

just card-list-status my-deck.txt     # implemented vs missing, from your checkout

The wizard is a front end for three loops you can also run directly (each --helps):

Command	What it does
just card-loop <list-file> [model] [--local]	Implements every missing card of a list or decklist
just set-loop <set> [model]	Implements a whole set from its backlog, one PR at a time
just commander-loop [model] [top]	Makes EDHREC's top Commander decks playable, deck by deck

Models: opus, sonnet, astra (Codex gpt-6-astra), any claude-* ID, or codex:<model-id>. just loops shows what every running loop is doing; just loop-watch <name> opens a live dashboard.

Using AI to implement cards by hand

Using AI to implement cards is encouraged — most of the card catalog is data, and the project ships agent skills that automate the workflow correctly (Scryfall lookup, oracle errata, set registration, scenario tests, reprint handling). They live in .claude/skills/ (Claude Code) and .agents/skills/ (Codex):

• add-card <CARD_NAME> <SET_CODE> — implement a specific card.
• add-random-card <SET_CODE> — pick a random unimplemented card from a set and implement it.

If a card adds a new UI / UX element, test it manually before opening the PR — AI can build the flow, but a human needs to confirm it actually feels right in the client. Run the app (just server

• just client), set up the situation (the generate-scenario skill can inject a board state), and click through the decision yourself.

Argentum Assay — how much of Magic can the SDK say?

:oracle-assay is a first-party Oracle-text grammar: Scryfall JSON in, mtg-sdk models out. Its trick is that every rule is written in both directions — a rule that can parse a phrase must also print it — so the whole corpus checks the grammar without a human reading the output. If print(parse(text)) == text, the reading was right.

That makes it an auditor before it is a generator, and the thing it audits is us. A card Assay cannot read is a card whose meaning the SDK has no way to say, so the ranked list of declines is a continuously-updated report of what the card vocabulary is missing, ordered by how many cards each gap blocks. Coverage is the lagging indicator: 100% would mean mtg-sdk can express every card in Magic.

just assay parse "Serra Angel"      # the normalized lines, and the SDK model each one parses to
just assay explain "Wall of Omens"  # the same, with a caret on the token a decline died on
just assay-gate                     # the touchstone over all 34,882 cards; exits 1 on a bug
just assay-report --rank tail       # the SDK gap report, ranked by what each family would unlock
just assay-differential             # Assay's readings vs. the hand-written cards — the sharper gate
just assay-explore                  # all of it in a browser, against the grammar on your classpath
just assay-bake                     # re-bless the per-card verdict ledger the coverage page reads

Two gates keep it honest. The touchstone proves a reading round-trips; the differential compares Assay's reading of a card against the hand-written cardDef we already ship, which is the only thing that catches a parse that round-trips byte-perfectly while meaning something else. It has found real bugs in hand-written cards — the outcome worth the most.

It is deliberately not a card loader, and won't become one: a human-authored cardDef with a passing scenario test stays the only ground truth. The one carve-out is the Scenario Builder's dev-gated sandbox, where you can paste a custom card and play it if — and only if — Assay reads every line of it.

The explorer (just assay-explore, or the Assay Explorer tab on the set completion page) is the readable version of all of the above: the ranked declines with the cards behind each one, every card's reading beside its printed text, the wired grammar, the differential, and a box for text that was never printed. It runs against the grammar on the classpath rather than a snapshot, so a rule you just edited is one restart from being re-measured.

See oracle-assay/README.md for the design, the verdict table, and what the gates have found so far.

Assay replaced the earlier :mtgish-tooling pipeline, which mapped the mtgish oracle-IR corpus by i5jb onto our SDK. That project's clean IR got the first auto-drafts off the ground, and its explorer is what Assay's is modelled on — thank you. The module is deprecated and kept only for reference.

Implementing a whole set

When bringing up an entire set, this flow has proven much faster than implementing cards one at a time (it's how Invasion was done):

1. Gap analysis. Diff the set against the SDK/engine: which effects, triggers, conditions, keywords, costs, or mechanics are missing that you need before any card can be implemented cleanly? Produce the full list up front. (Invasion needed roughly 25 new features.)
2. Plan each missing feature for elegance and reuse. For every gap, design the implementation so it composes complex effects from small reusable atoms rather than a one-off type per card — think about the SDK as a whole and the next card, not just the one in front of you. Use the add-feature skill, which encodes these principles end to end.
3. Implement the features one by one, with care. This is the step that pays off later, so give it attention: write tests, and manually test the UX for anything that touches the client. Some features are deep — Invasion's banding required rewriting the whole combat system — so don't rush them.
4. Then fan out the cards. Once the building blocks exist, most cards need no engine changes. Add them in parallel — e.g. spawn a few agents, each using the add-card skill to implement a handful of cards, and have each open a PR when its batch is done.
5. Review engine changes. Cards will occasionally still need a small engine tweak. When a PR adds or changes engine/SDK code, run review-changes <PR_URL> on it — this checks for elegance and correctness and keeps the engine/SDK clean. (Card-only PRs with no engine changes don't need it.)
6. Check the set against Assay. Run just assay-differential --set <SET>: any DIVERGENT row means Assay's reading of a card and the hand-written cardDef disagree — classify it before calling the set done. New SDK vocabulary you added isn't taught to Assay in the same PR; name it in the PR body, and the assay-loop widens the grammar to read it as its own measured band.

A set can also finish with a card or two deliberately left out — Legends' Falling Star needs physical dexterity the Chaos Orb table-flip doesn't cover. Add those to coverage/card-exclusions.json with a reason (required) and re-run scripts/gen-set-totals: they drop out of the denominator and show as "not planned" on the set completion tracker, so completion means everything we intend to build is built. It's a policy list, not a backlog — a card that's merely hard, or waiting on a feature we do plan to build, stays a normal gap.

Guidelines

• Read AGENTS.md and docs/architecture-principles.md first — they describe the load-bearing rules (immutability, projected state, events-not-mutations, server-authoritative client) that PRs are reviewed against.
• Prefer composing existing primitives over adding new SDK types; when you do add a type, parameterize it and name the mechanic, not the card.
• Update docs/card-sdk-language-reference.md in the same change whenever you add or change anything in the SDK.
• Verify Comprehensive Rules numbers via the official WotC rules page https://magic.wizards.com/en/rules before citing them in code, comments, or commit messages. The linked plain-text .txt is too large to fetch into context — download it and grep locally.
• Run just loop-gate (it runs the tests your diff can break; CI runs the full suite) and confirm green before opening the PR. Card changes: just loop-gate --rebless and check only your cards moved.
• AI-built PRs are welcome — frontier models (current Claude and GPT models) implement cards well. Say which agent and model built it.

Questions or ideas? Join the Discord.

Why "Argentum"?

Argentum was a plane of mathematical perfection, created by the planeswalker Karn. Every angle intentional, every law absolute. It was governed by rules so elegant they seemed inevitable.

That's what a rules engine should be.