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.
  • 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 are host.HostOnly.
  • Guest: opens …/join?invite=CODE. This page is public, and opening it spends nothing. “Take the seat” sends POST …/join/redeem, which returns a grant cookie, the seat token stored for SSETransport, 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 in host.HostOnly.
  • Board page: tablePaths() from /cig2/invite.js gives 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 by Identity.IssueAPIKey or POST /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/games lists the games and their seat ranges. Seat ranges come from the game’s cig2.SeatPolicy, or GameDescriber’s seats, or two.
  • Table lifecycle: POST /lobby/tables creates a table. Then join, ready (the game starts when every seat is taken and ready, or when the host calls start), 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/results after each finished game.

Matchmaking

  • Queueing: POST /match/tickets {"game", "queue"}, then poll GET /match/tickets/{id} until it is matched. The ticket then names your table and seat.
  • Matching: FIFOMatcher fills 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 after BotWait. RandomBots plays any game that gives legal hints.
  • From the command line: with host.Flags, -lobby turns the lobby on (with guest sign-in, in memory, unless the program set Config.Identity), and -bot-wait 5s adds RandomBots after that wait.

An agent’s loop

  1. Authenticate with its API key.
  2. Join a table, or enqueue a ticket.
  3. Read /state, act from legal, answer decisions that carry ask.
  4. Stop when over is true.

cig context agent-play covers the play loop in detail.