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/agentbecomes 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>-netnames one. - Your own Go policy, linked into a binary of your own (Writing a native Go bot).
The ways to plug a bot in¶
- Native Go (guide). Implement
seat.Seat, register it withbots.Register, link it intogorgedor 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. - HTTP seat (guide, examples). A server started with
-vsbotor-humansparks a seat's decision behindGET .../pending, and any program that speaks HTTP and JSON answers it withPOST .../intent. The Python and Java examples use this. - 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-sbv2a server also offers the same decisions over HTTP. - 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).