Identity, lobby and matchmaking
There are two lobbies. Pick one:
- Invite links (
-invites, below) suit a game for friends behind the app password. The host signs in and sends one-time seat links. - The identity lobby (
-lobby) suits accounts, matchmaking and bots. People sign in as guests or with keys, then join, ready up and queue.
Invite links (host.Server.Invites, -invites)
- Host: signs in with the app password and goes to
/cig2/lobby;/redirects there until the game serves a page. There the host starts a game, opens their own seat, and makes a link per other seat (POST [/t/{id}]/invite?player=). Invite routes arehost.HostOnly. - Guest: opens
…/join?invite=CODE. This page is public, and opening it spends nothing. “Take the seat” sendsPOST …/join/redeem, which returns a grant cookie, the seat token stored forSSETransport, and a redirect to/?table=ID&player=SEAT. - Seat reservation: a link reserves its seat. A link for a seat that is already taken is a recovery link: it moves the seat to the new browser.
- Code:
Table.Invite/Redeem/RevokeInvite/InviteFor/SeatInfo/ReissueSeat. - Guests are not hosts: a grant passes the gate, but
host.IsHost(r)is false. Wrap your own lobby routes inhost.HostOnly. - Board page:
tablePaths()from/cig2/invite.jsgives the table’s endpoints, and<cig2-invite table=…>is the host’s panel.
Identity (host.Identity)
Principals are people or agents, with roles player, host and admin. They come from:
- API keys (
Authorization: Bearer cig2_…): stored as hashes, issued byIdentity.IssueAPIKeyorPOST /auth/keys(admins). This is the way an agent signs in. - A trusted reverse proxy’s headers (oauth2-proxy, Cloudflare Access, Tailscale): honoured only from the proxy’s addresses.
- Guests (
POST /auth/guest {"name"}): a signed cookie.
CIG2 never stores passwords. Bad credentials get a 401; they are never treated as anonymous.
Lobby (host.Lobby, host.Config.Lobby)
GET /lobby/gameslists the games and their seat ranges. Seat ranges come from the game’scig2.SeatPolicy, orGameDescriber’s seats, or two.- Table lifecycle:
POST /lobby/tablescreates a table. Thenjoin,ready(the game starts when every seat is taken and ready, or when the host callsstart), play,rematch. - Playing:
/lobby/tables/{id}/events|action|state. Your identity is the seat’s credential; no token is needed. - Spectating:
/lobby/tables/{id}/spectate, public information only, on tables opened to spectators. - Results:
GET /auth/me/resultsafter each finished game.
Matchmaking
- Queueing:
POST /match/tickets {"game", "queue"}, then pollGET /match/tickets/{id}until it is matched. The ticket then names your table and seat. - Matching:
FIFOMatcherfills full tables at once, and smaller ones (down to the game’s minimum) after its widening delay. - Bot fill: with
Lobby.Bots, a lonely ticket gets bots afterBotWait.RandomBotsplays any game that gives legal hints. - From the command line: with
host.Flags,-lobbyturns the lobby on (with guest sign-in, in memory, unless the program setConfig.Identity), and-bot-wait 5saddsRandomBotsafter that wait.
An agent’s loop
- Authenticate with its API key.
- Join a table, or enqueue a ticket.
- Read
/state, act fromlegal, answer decisions that carryask. - Stop when
overis true.
cig context agent-play covers the play loop in detail.