Playing a CIG2 game from an automated client
This is a game-agnostic guide for a program, such as an LLM playtest agent, a
bot or a load test, that plays a CIG2 game over the host HTTP surface. It
does not need to know the game’s rules up front. Everything it needs is in the
snapshot it reads.
Everything here is opt-in on the server. The worked example uses
cmd/cig2-demo, started in agent mode:
go run ./cmd/cig2-demo -addr 127.0.0.1:8080 -sync-actions
B=http://127.0.0.1:8080In Go, that is host.Server{SyncActions: true}; seat tokens are on by default
(a server started with -insecure-seats / InsecureSeats has none). Every
host.Run server also refuses POSTs a browser marks as cross-site; an agent
sends no Origin or Sec-Fetch-Site header, so it is unaffected.
Behind -password-env, add -u any:$PASSWORD to every curl. Basic Auth with
the app password is the outer gate.
The loop
discover → claim a seat → read state → (act | answer) → read state → … → over0. Learn the game and the API
Two routes let you learn the server without reading its source:
curl -s $B/describe # the game's rules, seat range, and JSON Schema for each action's data
curl -s $B/schema # every wire type as JSON Schema; $B/openapi.json is the whole API/describe answers 404 for a game that doesn’t implement
cig2.GameDescriber. Then legal hints (below) are your only guide, and
they are enough.
Signing in: lobby and matchmaking
A server with an identity layer (host.Config.Identity) gives you a
principal instead of seat tokens. An agent signs in with an API key that an
operator issues (POST /auth/keys, or Identity.IssueAPIKey):
H="Authorization: Bearer cig2_…"
curl -s -H "$H" $B/auth/me # who you are
curl -s -H "$H" -X POST $B/match/tickets -d '{"game":"high-card-duel"}'
curl -s -H "$H" $B/match/tickets/<id> # until "status":"matched": your table and seat
curl -s -H "$H" $B/lobby/tables/<table>/state # then play: state, action, events
curl -s -H "$H" -X POST $B/lobby/tables/<table>/action -d '{"action":"reveal","id":"a1"}'
curl -s -H "$H" $B/auth/me/results # your match historyA seat bound to your identity needs no token, so steps 2 to 6 below apply
with /lobby/tables/<table>/… routes and the Authorization header in
place of ?player=&token=. Lobby actions are always synchronous (200, 422
or 409, as with -sync-actions). GET /lobby/tables and
POST /lobby/tables are the self-serve alternative to matchmaking: join a
table, then POST …/ready.
1. Discover
curl -s $B/tables
# {"game":"high-card-duel","tables":[{"id":"default","seats":["p1","p2"]}]}Routes without a prefix (/state, /action, …) address the table
default. Any other table uses /t/<id>/…. A server may run in explicit
mode (Registry.SetExplicit). There, an unknown table is 404 until someone
creates it:
curl -s -X POST $B/t/game7/create -d '{"config": {"faction": "red"}}'
# {"status":"created","table":"game7"} (409 if it exists)The config body reaches the game’s Setup as raw JSON. Its meaning is up to
the game: house rules, factions, a bias spec. A game that decodes it with
cig2.DecodeConfig rejects unknown keys and bad values with a 400 naming
the problem (nothing is created; a rejected reset keeps the current game).
To make a game reproducible, add "seed": <integer> to a create or reset
body. The same seed, game and actions deal the same cards. The seed applies to
that one game, and a plain reset deals a fresh one. If the server runs with
ExposeSeeds, every create and reset response (and /tables) reports the
seed actually used, so you can record any game and replay it with
{"seed": n}. Seeds reveal every hidden card, so never hand one to a player
agent while its game runs. A replay deals the same cards but not the same
card uuids — those are random every game — so compare replays by what the
cards are and where they sit, never by uuid.
2. Claim a seat
curl -s -X POST "$B/claim?player=p1"
# {"seat":"p1","table":"default","token":"2743a867e72d0144fbb94766d5adde10"}Send that token on every later request for the seat — preferably as the
X-CIG2-Seat-Token header, since a ?token= in the URL lands in access and
proxy logs (use &token= only for the event stream, if your client cannot set
headers). Without it you get 403. The claim also completes the session’s
join handshake for your seat, so never send an "ack" action yourself. A seat already claimed
by someone else is 409. Tokens survive reset. To give a seat up, call
POST /release?player=p1&token=…. (Seat tokens are on by default; only a server
started with -insecure-seats has none, and its /claim is 404.)
3. Read state
curl -s "$B/state?player=p1&token=$T1"This returns your full current snapshot. It is the same JSON the event stream would push, filtered for your seat. The fields an agent needs:
| field | meaning |
|---|---|
you | your seat |
root | the board: a tree of zones. Each has count (always true). cards holds only what you may see. A card without payload is face-down to you |
legal | if present, the actions the game says you may take now, each {"action","data","label"}. [] means nothing is legal for you right now (wait). If the field is missing, the game gives no hints |
decisions | pending server questions. An entry with ask is yours to answer (see 5). Without ask, someone else is deciding |
turn, phase, round | turn and phase, if the game uses them |
game_state | game-specific extra state, shaped by the game |
ack_id | the id of your latest accepted action |
over, result | the game has ended, and who won |
Use polling or streaming, whichever suits you. To stream, GET /events?player=p1&token=… is Server-Sent Events, with one data: snapshot
per change. When the server ends a stream on purpose, its last frame is
event: close with data: {"reason": …}: "reset" (reconnect now for the
new game), "displaced" (another client claimed your seat — don’t fight it
in a loop), "shutdown", "deleted" (the table is gone; stop), or "failed"
(a bug in the game stopped the table; it answers 500 until someone resets
it — report it, don’t retry in a loop). A stream that ends with no farewell
was a network drop.
4. Act
Send one of the legal entries back exactly as you got it. Add an id of
your own so you can match the answer:
curl -s -X POST "$B/action?player=p1&token=$T1" -d '{"action":"reveal","id":"a1"}'
# {"ok":true,"id":"a1"} 200
curl -s -X POST "$B/action?player=p1&token=$T1" -d '{"action":"reveal","id":"a2"}'
# {"ok":false,"id":"a2","error":"highcardduel: p1 has already revealed"} 422With -sync-actions (SyncActions), the response is the outcome:
| status | meaning | what to do |
|---|---|---|
200 | accepted, applied, settled | read state |
422 | the game rejected it; error says why | read state, pick again |
409 | the game is over | stop |
400 | your JSON was malformed | fix the envelope |
403/404 | wrong token or unknown seat/table | re-claim / re-discover |
500 | a game bug: a settle runaway, or a panic ("internal error"). If the table failed, every request answers 500 until a reset | report it; POST reset to start over |
Without sync mode, POST /action always returns 202 right away. A rejection
then arrives on the event stream as {"type":"error","message":…,"id":"a2"}.
id names your action, and once an action is accepted it shows up as
ack_id in your next snapshot.
legal is a hint, not the rule. The game’s own validation is the only judge,
so a stale hint just gets a 422.
Action names starting with cig2. belong to the framework: anything but
cig2.answer is a 422. Actions the game runs on timers (a turn timeout, an
AI move) can’t be sent by a client: the game sees your copy as a player action
and rejects it.
5. Answer a decision
When a snapshot’s decisions holds an entry with ask, the server is waiting
for you:
"decisions": [{"id": "d-91…", "seat": "p1", "deadline": "2026-10-07T12:00:30Z",
"ask": {"kind": "keep-one", "prompt": {…}, "choices": ["u1", "u2", "u3"], "min": 1, "max": 1}}]Answer by picking between min and max distinct choices:
curl -s -X POST "$B/action?player=p1&token=$T1" \
-d '{"action":"cig2.answer","id":"a5","data":{"id":"d-91…","choices":["u2"]}}'The same status codes apply. After deadline, the game answers for you with
its default, so a slow agent never hangs the table. Decisions are not repeated
in legal.
6. Detect the end
curl -s "$B/state?player=p1&token=$T1"
# … "over":true, "result":{"winners":["p2"],"reason":"highest card"}, "legal":[] …Once over is true, every further action is 409. For another game, call
POST /reset (or /t/<id>/reset, optionally with {"config": …} and/or
{"seed": …}).
Your seat token remains valid.
A server with AllowDelete also takes POST /t/<id>/delete (200, 404 if
unknown). It ends the table for good — streams get the "deleted" farewell,
seat tokens go with it — and the ID can be created again.
Rules of thumb for agents
- Re-read state after every action. Don’t track the board in your head: snapshots are complete, never diffs.
- Act only from
legal, answer only questions that haveask, and treatlegal: []as “wait”, not “stuck”. - Tag every action with an
id. It’s the only way to tie an asynchronous error to the action that caused it. - What you can’t see doesn’t exist for you. Missing
payloads and counts without card entries are deliberate. The server never sends what your seat may not know.