Skip to content

gorge

A Magic: The Gathering rules engine in pure Go. Every game is a deterministic, hash-chained event log you can replay byte for byte.

  • zone moves
  • the stack
  • mana
  • combat and life
  • turn structure and decisions
One golden two-player game: 2,558 events, the pregame at the bottom and 15 turns above it. Chain head 9a22e5122a3d436a.

How the engine works Play in the browser Write a bot

gorge is a deterministic, event-sourced Magic: The Gathering rules engine written in pure Go. It does not hand-code cards: it compiles Forge's card scripts into an intermediate representation (IR), and the engine implements the primitives that IR references (effects, triggers, keywords, static abilities, value expressions). Around the engine sit a reference server with a browser client, baseline and hosted bots, and tools to replay, benchmark and audit games.

Every state change goes through one function, events.Apply, into a SHA-256 hash-chained event log. A game is therefore a pure function of its configuration and the players' answers, so replay, resume after a restart, undo, search clones and bug reproduction are all one mechanism.

Status

gorge plays full two- to eight-player games, including Commander, serves bot tables and play-against-a-bot games to a browser, and replays every game byte for byte. It is not yet at rules parity with mature engines and is not ready for production use.

Who this site is for

You are… You want… Start at
a Go developer who wants to fix a card or a rule to set up, find the code, and land a change Contributing
an engine user running the demo or bot matches to run a server, play, watch, replay User's guide
a bot author (Python, Java or Go) to wire a strategy to the engine's decisions Bots
curious how it works the design and its trade-offs Architecture

At a glance

94.6% of Forge's 34,074 card scripts are playable in gorge at the pinned corpus commit (make report, 2026-10-21, 513a2a0c3). Every Standard set is certified against XMage at Level A or better. dirty-dirac, the second kernel, lowers 47% of the corpus and is lockstep-verified against gorge on Foundations and Bloomburrow. Card support has the figures by engine and by set, regenerated at every docs build, and Performance has engine speed. Golden bot games at 2, 4, 6 and 8 seats replay byte-identically, and the root go.mod has no dependencies and no cgo.

Three repositories at a glance

gorge public · Apache-2.0 · this site rules engine (engine/) Forge-script compiler reference server gorged browser client (web/) baseline and hosted bots replay, bench, audit tools imports nothing but the stdlib gorge-compliance public · Apache-2.0 checks gorge, card by card, against XMage, Forge and hand-written Oracle-text scenarios certification ratchet four-yay private research and draft events, research bots, the dirty-dirac kernel, demo deployment not needed to use gorge pins gorge by commit GORGE_PIN + go.mod pins gorge by commit GORGE_PIN + go.mod arrows: importer → imported gorge never imports either companion
gorge is self-contained. The two companions build on it at a pinned commit; see The three repositories.

Where to go next

  • Repos

    What lives in gorge, gorge-compliance and four-yay, which way the imports run, licensing, pinning and the branch flow.

  • Architecture: the gorge kernel

    The event log, the rules engine, the card pipeline, views and the server, and the invariants that hold them together.

  • Architecture: the dirty-dirac kernel

    A fixed-size, much faster second kernel, growing toward a full engine and checked decision by decision against gorge.

  • Contributing

    Set up, run the tests inside the budget, read the ratchets, and land your first card fix.

  • User's guide

    Run a local server, play against a bot, watch tables, replay a game.

  • Bots

    The decision contract a bot answers, the built-in bots, and how to connect your own.

  • Performance

    How engine speed is measured and the current numbers.

  • Card support

    Card coverage by engine and by set: gorge playable and certified, dirty-dirac lowered and lockstep-verified.

Licensing

gorge is Apache-2.0. Forge's card scripts are GPL-3.0, so gorge ships a compiler for the script format and never the scripts themselves: they are fetched into a gitignored .cards/ directory at a pinned commit, and a test (TestNoForgeScriptsTracked) fails the build if one is ever tracked. Details are on The three repositories.