GitHub ↗
🐟

MtG Goldfish Simulator

A solitaire (“goldfish”) Magic: the Gathering simulator with a web interface. Give it a deck and a few properties in plain English — it exhaustively explores every line of play and measures how often those properties can be satisfied.

Not a “good pilot”

It doesn’t try to play well. It is a search engine over the decision tree of a solo game: it tries every legal sequence of plays and counts the ones that reach your target.

Real rules engine

Turn structure, the stack, mana payment, commander tax, fetchlands, activated and triggered abilities, tokens, combat against a phantom opponent — with per-card behaviour, one file per card.

English → code

Properties are written in plain English and compiled to Python by an LLM — always reviewable before you run.

From deck URL to statistics

You import a deck, describe what you want to observe, and the engine answers with a success rate and replayable winning lines. The data flows one way:

Deck URLMoxfield / MTGTop8 Scryfallcard data + images Sessiondeck + properties Engineexhaustive search Stats +winning lines English properties Card behaviours LLM compiles to code cards/ registry (one file per card)
The web layer is a thin FastAPI shell; the engine has no web dependency and can be driven from a script or tests.

A run plays N independent, seeded games; each game is searched exhaustively. A game is a success if some single line of play satisfies all your properties at their trigger moments. That’s the whole idea — the rest is detail.

Where to go next

Install & run →

One free tool, no programming needed. macOS / Windows / Linux, updating, and troubleshooting.

The search →

How a run explores the decision tree, what branches, how lines are pruned, and the search strategies.

Properties & states →

Anatomy of a property, timing semantics, what a “state” is, and the English-to-code compiler.

Examples →

Worked examples: reading the runs table, replaying a winning line, and writing useful properties.

Architecture →

The code map: packages, the game state, the stack, card behaviour, and the mana planner.