Skip to content

Using and plugging in bots

How to seat a bot, play one, and connect your own. For what each bot is and what it can see, see Bots and Each bot in detail. Bot cost is on Bot speed.

I want to Go to
play a bot in the browser Playing a game
pit bots against each other Bot-vs-bot games
answer a seat over HTTP from Python or Java Playing a seat over HTTP, examples
write a Go policy Writing a native Go bot
run a SpellBench v2 agent, or serve a gorge bot as one SpellBench v2 agents
evaluate a policy or get it adopted Training and adoption

The one contract every bot answers

Whatever the transport, a bot does one thing: the engine poses a decision listing every legal option, and the bot answers with an intent naming option indices (glossary). The engine validates the answer against what it offered, so a bot can choose badly but can't make an illegal move. The decision kinds are a closed set of thirteen (decision.Kinds in engine/decision/decision.go): priority, target, attackers, blockers, mulligan, modes, trigger_order, trigger_optional, commander_zone, choose, replacement, arrange and starting_player. Conceding is an option on a priority decision, not a kind. Playing a seat over HTTP explains how to answer each one.

A bot sees one seat's redacted view of the game: its own hand, the public board and counts for hidden zones, never the opponent's hand or the library order.

How to select one

Where How
gorged, play-vs-bot POST /api/games with "bot_policy": "<name>"; omit it to get the server's -bot-policy. -bot-policies a,b,… limits what the server offers
gorged, bot-only tables -bot-policy <name> seats that policy in every bot seat of the startup tables
mtgsim -policies a,b,… names one policy per seat (- keeps the plain heuristic); without it -a <name> is seat 0 and -b <name> seat 1
A Go program bots.New(name, bots.Options{Seed, AutoPayMana, Deps: bots.Deps{Cards: reg}}) after a blank import of bots/all; testkit/bench drives it
SpellBench v2 spellbench-gorge-agent -policy <name> serves it as a v2 agent (SpellBench v2 agents)

-bot-common-sense (default off) wraps bot, forge-heuristic and sb-tactical in the bots/sanity guard, which drops hostile removal that could only hit the bot's own permanents.

sb-tactical and az-redeal need a driver that supplies their honest roots and the card registry. gorged, mtgsim and testkit/bench.PlayGame with Hooks{EnvSeats: true, HonestRoot: true} do. A driver that only calls Seat.Decide gets az-redeal's wrapped heuristic bot, which never searches.

As the opponent for an HTTP bot, or the baseline for your own policy, use bot, with a bot-against-bot control on the same seeds. Start gorged with -bot-policy bot to make it the default.

Other policies at runtime

  • A SpellBench v2 agent registered with -sb-agent name=/path/to/agent becomes a policy like any other.
  • Network-backed search bots. A binary links a search bot that needs a trained network through gorged.RegisterNetBot (server/gorged/netbots.go), which gives it its -<policy>-* flags. gorge ships the inference code but no trained networks, so such a policy stays unregistered until its -<policy>-net names one.
  • Your own Go policy, linked into a binary of your own (Writing a native Go bot).

The ways to plug a bot in

one process: gorged, mtgsim or testkit/bench rules engine Decision → Intent match loop server/host or bench ① native Go seats bot, forge-heuristic, az-redeal, yours Decide(ctx, View, Decision) ② HumanSeat + httpapi parks the decision until an intent /pending /intent /view ③ SpellBench seat adapter server/spellbench/seat (-sb-agent) hello · game_start · choose process boundary HTTP client Python, Java, a browser… any machine that can reach it v2 agent process spawned per match, any language same machine only HTTP + JSON bearer token stdin/stdout NDJSON ① has nothing outside: the seat is a Go value in the same address space

The integration surfaces. Native seats are called directly; an HTTP client answers a parked HumanSeat across the network; a SpellBench v2 agent is a child process on the same machine.
  1. Native Go (guide). Implement seat.Seat, register it with bots.Register, link it into gorged or a bench. It is the fastest path and the only one that can search: a Go seat can clone the engine or ask the host for an honest redealt world.
  2. HTTP seat (guide, examples). A server started with -vsbot or -humans parks a seat's decision behind GET .../pending, and any program that speaks HTTP and JSON answers it with POST .../intent. The Python and Java examples use this.
  3. SpellBench v2 (guide). gorge speaks the SpellBench benchmark protocol in both directions over a child process's stdin and stdout: an external agent can take a gorge seat (-sb-agent), and any gorge bot can be served as a v2 agent. With -sbv2 a server also offers the same decisions over HTTP.
  4. gorge-agent/1 (reference). A batch protocol for drafters, builders and players in the draft tools.
Native Go seat HTTP seat SpellBench v2 agent seat
Language Go anything with HTTP and JSON anything that reads and writes lines on stdio
Transport a function call HTTP/1.1 and JSON; SSE for push stdin and stdout, one JSON object per line
Where the bot runs inside the host process anywhere that can reach the server a child process the host spawns, one per match
Hidden information the seat is handed a redacted view; the code is trusted, since it runs in the server enforced by the server: the bearer token names the one seat it may read and act for the host sends an engine-neutral observation for the agent's seat only
Can it search or clone the engine? yes: Engine.Clone, CloneHypothetical, or an honest root via bots.EnvSeat no engine access; bring your own simulator no, unless the agent embeds one
Determinism a pure function of the seed the server records every intent, so a finished game replays; the bot's own randomness is yours to seed the host passes an agent_seed
Many games at once goroutines (testkit/bench.RunPairs) one token per seat, up to -max-on-demand-tables one process per seat per match
On a timeout hosted search seats fall back to their heuristic after 2 s none: gorged waits, and the seat's caretaker bot answers only when the table shuts down forfeit: the seat concedes at its next priority, with the default bot answering until then

Per-decision costs: about 30 µs for a two-seat game step in process (examples/bots/go/cmd/duel, on Writing a native Go bot), a few tenths of a millisecond over HTTP on loopback (Latency), and about the same over stdio (SpellBench latency).