Skip to content

Draft events

gorge can run a complete limited event: four seats open three packs, draft them, build 40-card decks and play a round robin. Any seat can be a person or a bot, and bots take part in every phase. This page shows how to host events with gorged, how to run them headless with draftsim, and how to compose your own workflows with labdemo and the draftlab library.

The commands and output below are from 2026-11-08.

Host events with gorged -events

Draft events are part of the public gorged binary and are off by default. Turn them on with -events:

make fetch-cards   # once: the pinned card corpus, into .cards/
make web           # once, before gorged is built: the browser client
go run ./cmd/gorged -addr 127.0.0.1:8080 -dir /tmp/gorge-draft -events
gorged: 4 tables of 4 on 127.0.0.1:8080 (dir /tmp/gorge-draft)
gorged: draft events on (/api/events, dir /tmp/gorge-draft/events)

Open http://127.0.0.1:8080/ and use Draft a 4-player pod in the lobby. That entry appears only on a server that serves events, and goes to /events/new. A gorged built before make web still serves the whole API, but pages answer 503 web build missing.

With -events, the startup art fill also covers every card in every draftable set as well as the deck files, so a first start spends a while fetching from Scryfall at a limited rate. Play is not affected. Add -prewarm=false to skip the fill, and cards are then fetched as packs first show them; -art-dir keeps the cache across a wiped -dir.

A server without -events behaves as if events did not exist: GET /api/capabilities says {"events":false}, every /api/events path is a 404, and <dir>/events is never created.

Use a fresh -dir for each server. Two servers sharing one directory corrupt each other (Play in the browser).

How an event runs

flowchart LR
  L[LOBBY<br/>humans join] --> D[DRAFT<br/>3 packs, pick one]
  D --> B[BUILD<br/>40-card decks]
  B --> R1[ROUND1] --> R2[ROUND2] --> R3[ROUND3] --> C[COMPLETE<br/>standings, reveal]
  L -. nobody joined in time .-> X[CANCELLED]
  • Lobby. The creator chooses a set, a series format and each seat. Each human seat gets a private invite link, shown once. With one human, the client sends you straight to your own link. The event starts when every human has joined.
  • Draft. You pick one card and pass the rest: left in packs 1 and 3, right in pack 2. A seat picks whenever a pack is waiting for it, and bots pick immediately. An FDN or TRK pod is 42 picks per seat; a BLB pod is 39.
  • Build. A deck is at least 40 cards: any cards from your own pool, plus free basic lands in any number. The client offers the bot builder's suggestion and an automatic land split. You save a deck, then ready it.
  • Rounds. Three rounds of 1v1 series, seat 0 against 3 and 1 against 2, then 0 against 2 and 1 against 3, then 0 against 1 and 2 against 3. Each game is an ordinary table that you can watch or replay.
  • Complete. Standings follow the Magic Tournament Rules: match points (win 3, draw 1), then opponents' match-win percentage, game-win percentage and opponents' game-win percentage, then seat index.

Other seats' picks and decks stay hidden until the event is COMPLETE. Until then a seat sees counts only, and GET /api/events/{id}/log is redacted for it.

What you can choose

Format. A hosted event takes a format: draft (the default, three booster packs per seat drafted in turn), sealed (six Play Boosters per seat, opened at once) or prerelease (the same six Play Boosters plus one rare or mythic promo card per seat). A sealed or prerelease event has no picks and no pick timer: it goes from the lobby straight to deck building once every human has joined. Decks are 40 cards with any number of basic lands (MTR 7.1-7.2). A prerelease defaults to best of 3; an explicit best_of of 1 is honoured.

Deck changes between rounds. A sealed or prerelease event rebuilds between rounds (MTR 7.3, continuous construction): before game 1 of every series from round 2 on, the event opens a rebuild window and no game starts until both sides have locked a deck for it. A human seat keeps or replaces its deck in the window with the usual sideboard panel (POST /api/events/{id}/sideboard with game: 1: keep: true locks the deck it played last, a deck saves and locks a new revision), and a seat idle past the idle window keeps its deck automatically; bots keep the deck they last played. A draft event plays straight through with no window. The create body's rebuild overrides the format's default — true for sealed and prerelease, false for draft — and the event state reports the resolved value as rebuild. The window reuses the between-games panel: a series in it shows state: "between" with game: 1 and the seats still to lock.

Sets. Packs follow the MTGJSON booster configurations. A hosted event uses the Arena collation (play-arena); draftsim and labdemo can also cut paper Play Boosters (play).

Code Set Pack size Bot pick ratings
FDN Foundations 14 17Lands games-in-hand win rate
BLB Bloomburrow 13 a heuristic from card facts
TRK Star Trek 14 simulated card strength (Research: card strength)

TRK packs follow a booster this repository authors itself: MTGJSON publishes no Star Trek configuration yet, so a pack is seven commons, three uncommons, a rare or mythic, a basic land, a wildcard and a foil, the same on both collations. It is replaced by the published one when there is one. A card the corpus has no script for yet is never offered as a bot pick and a bot's deck leaves it out, so a bot drafts and builds a deck that plays; the list of such cards only shrinks as scripts land.

Bot seats have a game policy, a drafter and a builder. GET /api/events/personas lists the drafter and builder names: rating-colour (the default) and best23, which name the same pair — the rating-colour drafter, which scores a card by its rating plus how well it fits the colours picked so far, and the best23 builder, which plays the colour pair with the best 23 cards and adds 17 basics — and balanced, a drafter that commits to two colours by pick 10 and drafts toward the deck's missing card types and mana values, and a builder that plays a curve, 14 to 18 creatures and two of each spell type the pool offers, splashes up to three one-pip cards on three sources when its pair runs short, plays up to four on-colour duals and plays 18 lands rather than an uncastable card. A fourth persona, champion, is tuned for FDN only and is not the default; see the champion draft persona.

The game policy is any hosted policy that does not read opponents' decklists: bot, lethal-pressure, forge-heuristic and forge-heuristic-hold in a plain build. Asking for one that does is refused:

{"code":"bad_request","message":"eventhost: policy \"sb-tactical\" reads every seat's real decklist (Env); draft events refuse Env policies"}

Series format. Best of 1 (the default) or best of 3. In best of 3 the loser of a game chooses who plays first in the next one (MTR 2.2), and a human can sideboard between games. A bot keeps its deck.

Pick timer. Only a pod with two or more humans has one. A single human drafts at their own pace. An expired pick is taken by the seat's own drafter and logged as automatic. Nothing about a deadline is saved, so a restart re-arms each timer at its full length.

pick_timer Limit per pick
standard (the default with two or more humans) 75 s for a 15-card pack, falling to 7 s for the last card
relaxed the standard limit × 1.5
off none

Limits.

Limit Value What happens
Seats exactly 4; up to 4 may be human anything else is a 400
Events not yet COMPLETE 4 (-max-events) a further create is a 409 capacity
Lobby 15 minutes with an unjoined human seat with at least one human joined, bots fill the empty seats and the event starts; with none, it is cancelled
A human who stops acting 2 hours the server acts for them: auto-pick, auto-submit or concede

Restarts

An event resumes from its own log. Everything needed is under <dir>/events/<id>/: event.json, log.jsonl and decks/. A game that was in progress is aborted and played again from the start on a new table with a new seed, and the log records both facts. A table's name carries its attempt number. After stopping a server in round 1 and starting it on the same -dir, the event's two live series read, with the other fields left out:

{"table":"e1-r1-s03-g1-a2","state":"live","attempt":2}
{"table":"e1-r1-s12-g1-a2","state":"live","attempt":2}

Run an event over HTTP

The browser client uses the same API as any other program. The full route table is in HTTP API: Draft events. Four bots need no one to join, so the event runs straight through the draft and the build:

curl -s -X POST http://127.0.0.1:8080/api/events -H 'content-type: application/json' -d '{
  "set": "FDN",
  "seats": [{"kind":"bot"}, {"kind":"bot","policy":"lethal-pressure"},
            {"kind":"bot","policy":"forge-heuristic"}, {"kind":"bot"}]}'
{"event":"e1","invites":null,"state":{"event":"e1","set":"FDN","phase":"ROUND1","round":1,"best_of":1,"pick_timer":"off", ...

A human seat works through its invite token, sent as Authorization: Bearer:

Step Request Real reply, shortened
Create POST /api/events with {"kind":"human"} in a seat {"event":"e4","invites":[{"seat":0,"token":"…","join":"/e/e4?seat=0&token=…"}], …}
Join POST /api/events/e4/join {"name":"Ann"} phase DRAFT, you 0
See the pack GET /api/events/e4/pack {"round":1,"pick_no":1,"pack":[{"id":"c1","name":"Strix Lookout", …}, …]}
Pick POST /api/events/e4/pick {"round":1,"pick_no":1,"id":"c1"} the next pack; after 42 picks, waiting is true and the phase is BUILD
See the pool GET /api/events/e4/pool pool plus suggestion, the bot builder's deck
Check a deck POST /api/events/e4/deck/check {"main":[…],"basics":[4,4,3,3,3]} {"valid":true,"total":40,"auto_lands":[2,4,3,3,5]}
Save it POST /api/events/e4/deck with the same body the same, plus "rev":1
Ready POST /api/events/e4/ready {"rev":1} phase ROUND1

Each live series for your seat then carries a join link to its table:

{"round":1,"a":0,"b":3,"best_of":1,"state":"live","table":"e4-r1-s03-g1-a1","attempt":1,"score":[0,0],"winner":null,"join":"/t/e4-r1-s03-g1-a1?seat=0&token=…&event=e4"}

The seat then plays through the ordinary decision loop. The event sends its own frames (event_state, draft_pack, pod_progress, series_update) to a stream session after POST /api/events/{id}/subscribe (Wire protocol).

Run events headless with draftsim

draftsim needs no server and no browser. make draftsim builds it and plays two FDN events, replaying each one from its own log and each game from its chain:

$ make draftsim
go build -trimpath -o bin/draftsim ./cmd/draftsim
bin/draftsim -set FDN -seed 1 -events 2 -verify
event 1: seed 1, set FDN (play-arena), drafter rating-colour, builder best23
  round 1 seat 0 (lethal-pressure) vs seat 3 (lethal-pressure): winner seat 3 turns 11 head 14b4ac72c8b56212 replay OK
  round 1 seat 1 (bot) vs seat 2 (forge-heuristic): winner seat 1 turns 19 head e0746408c549bda1 replay OK
  round 2 seat 0 (lethal-pressure) vs seat 2 (forge-heuristic): winner seat 2 turns 22 head 8bafa8445208abc6 replay OK
  round 2 seat 1 (bot) vs seat 3 (lethal-pressure): winner seat 3 turns 27 head 839ba06d6272dbe2 replay OK
  round 3 seat 0 (lethal-pressure) vs seat 1 (bot): winner seat 0 turns 41 head 022b40d05194e9bd replay OK
  round 3 seat 2 (forge-heuristic) vs seat 3 (lethal-pressure): winner seat 3 turns 49 head 731186ee78a39216 replay OK
event 1: replay OK (208 log entries, 6 games)
  standings: seat persona                pts    MW    OMW    GW    OGW
    3 FDN/rating-colour/lethal-pressure   9  1.000  0.333  1.000  0.333
    0 FDN/rating-colour/lethal-pressure   3  0.333  0.556  0.333  0.556
    1 FDN/rating-colour/bot      3  0.333  0.556  0.333  0.556
    2 FDN/rating-colour/forge-heuristic   3  0.333  0.556  0.333  0.556
event 2: seed 2, set FDN (play-arena), drafter rating-colour, builder best23
  ...
event 2: replay OK (208 log entries, 6 games)

Both events finished in under 2 seconds in total. The event seed drives the packs, the picks and the game seeds, so the same flags give the same log byte for byte.

Flag Default Meaning
-set FDN FDN or BLB
-collation play-arena play-arena or play
-seed, -events 1, 1 the first event's seed, and how many events; each later event adds one to the seed
-seats 4 pod size, 4 or 8
-mode draft draft, sealed (6 packs per seat, unpicked), or prerelease (sealed plus one rare or mythic promo per seat)
-structure round robin at 4 seats, Swiss at 8 roundrobin, swiss, or none to stop after building
-rounds the structure's own how many rounds to play
-players lethal-pressure,bot,forge-heuristic,lethal-pressure one policy for every seat, or exactly one per seat. A policy that reads decklists is refused
-drafter, -builder rating-colour, best23 the pick and build logic: a persona name (rating-colour, best23, balanced, or champion for FDN), or knobs:path.json for a pickbot.Tuning knob file (knobs:path.json@<hash> checks the file's hash), which drafts with Knobbed and builds with Best23
-verify off replay events and games, and exit non-zero on the first mismatch
-draftlog none append every pick to a CSV in 17Lands' draft_data shape
-v off print each seat's policy and deck summary

draftsim plays best of 1 only. Two more shapes it can run:

go run ./cmd/draftsim -seats 8 -players bot -seed 3 -verify
go run ./cmd/draftsim -mode sealed -structure none -seed 3 -v
go run ./cmd/draftsim -mode prerelease -seats 8 -seed 3 -v

Hosted and headless differ

Eight seats and Swiss are available in draftsim and draftlab. A hosted event is a 4-seat draft, sealed or prerelease pod played as a round robin.

Compose a workflow with labdemo

cmd/labdemo is a worked example of the draftlab Go library. It plays some random-deck games, fixes a player policy, builds decks from sealed pools, drafts an 8-seat Swiss pod and plays the built decks against a benchmark catalog of opponents:

$ go run ./cmd/labdemo -seed 1 -out /tmp/labdemo
frozen player bot@1
labdemo seed 1: set FDN, collation "", player bot@1
step 1 random-deck games: 4 played, 4 finished
step 3 sealed builds: 8 decks
step 4 pods: 1 pod(s) of 8 seats, 12 games (12 finished)
step 5 gauntlet: 16 hero(es), 320 games (320 finished)
hero sealed 1 / bot@1: 16-4-0 0.800 ci95 [0.584, 0.919]
...
hero p7 FDN draft / bot@1: 8-12-0 0.400 ci95 [0.219, 0.613]
artifacts: /tmp/labdemo

That run took about 3 seconds. Its figures come from one small seeded run and say nothing about bot strength. -out writes:

File What
draft_data.csv one row per pick, in 17Lands' draft_data shape
game_data.csv one row per player per game, in 17Lands' game_data shape
decks.json the built decks and where they came from
manifests.json what each step ran: agents with versions, seeds, limits, results
events/pod1.log.jsonl the pod's replayable event log

The whole run is a pure function of its flags, so two runs with the same flags write identical files. -player, -drafter and -builder also accept an external program in any language; see gorge-agent/1. To use the same pieces from Go, start from draft/draftlab and read cmd/labdemo/workflow.go.

Data sources

The FDN pick ratings come from 17Lands public datasets, licensed under CC BY 4.0. They are per-card games-in-hand win rates from FDN Premier Draft games, and the file draft/limited/pickbot/ratings/FDN.json records its source and attribution. The client shows the credit on any page those ratings shape. The set and booster data is trimmed from MTGJSON (MIT). Both are credited in NOTICE.

The champion persona's value table is derived from simulated games on decks drafted with 17Lands ratings, so it carries the same CC BY 4.0 credit; see the champion draft persona.

Where next