Skip to content

User guide

This guide is for people who want to use gorge rather than change it: to play Magic against its bots (or friends) in a browser, or to run bot-vs-bot games that compare bot strategies. It walks from a fresh clone to a running game, explains what each tool is for, and collects the failures you are likely to hit. If you want to change the engine itself, start at Contributing; if you want to connect a bot written in another language, see External bots.

From clone to playing in five commands

git clone https://github.com/adams-shaun/gorge && cd gorge
make fetch-cards   # pinned Forge card scripts into .cards/
make web           # the browser client (needs Node 20+)
go run ./cmd/gorged -addr 127.0.0.1:8090 -dir /tmp/gorge-play \
  -feedback /tmp/gorge-play-feedback -vsbot
# open http://127.0.0.1:8090/ and press "Start game"

You need Go (1.25.8 or newer), git and make; Node only for make web. Install and build explains each step and what to do when one fails. For bot games instead, the first command after make fetch-cards is make sim, which plays 20 verified bot games in a few seconds.

What runs where

When you play, one gorged process does everything except draw the board. The browser holds no rules: it shows what the server sends and posts back the option you picked. Bots are not separate programs; they are Go code running inside the same process, answering their seats' decisions directly.

Your browser seat 0 + its token A friend's browser seat 1 + its token Spectator no token: watch only HTTP JSON + SSE stream gorged (one Go process) HTTP API (server/host/httpapi) /api/tables /api/games …/intent /api/stream host registry (server/host) tables, matches, seat tokens, one view per seat rules engine, one per match (engine/) every change is a logged event; seeded, replayable Human seat waits for your answer Bot seat a policy, in-process the engine asks a seat for a decision; the seat answers with an intent Scryfall card art, cached -dir tables, event logs -feedback bug reports + snapshots .cards -decks corpus and decks, read at startup

One gorged process serves every browser. Human seats wait for a browser's answer; bot seats answer in-process.

Three properties follow from this design and come up again in the guide:

  • The server decides what each viewer sees. A seat's view is redacted on the server; a spectator gets either the public view or the omniscient one, as the operator chose. The client cannot ask for more.
  • Every game replays. The engine is deterministic: a match is its seed, its decks and the list of answers. That is what makes undo, the replay pages, bug-report snapshots and bot-match verification work.
  • Bots are cheap. A heuristic bot answers in well under a millisecond in-process: four cores played 1,320 two-seat bot games in 6.5 seconds (measured).

Where to go next

You want to Read
install Go tools, the corpus and the client Install and build
play against a bot, or against friends on a LAN Play in the browser
compare two bot strategies, or watch bots play Bot-vs-bot games
replay a game, or read why a bot made each choice Replays
connect a bot written in Python, Java or over HTTP External bots
fix something that went wrong Troubleshooting
look up a term Glossary