Finding a game

// Matchmaking is a socket message — there is no REST queue endpoint.
client.queue({ variant: "standard", timeControl: "blitz_3_2", rated: true });

// The client NEVER sends a rating. At enqueue the engine pulls user detail + all
// rating categories from the platform (GET <platform>/users/{userId}) and selects
// the one matching this pool; if the platform is unreachable the enqueue is
// rejected (error code platform_unavailable) — there is no client-supplied fallback.

// Casual / unrated — separate pool, FIFO pairing, no rating change, no rating pull:
client.queue({ variant: "standard", timeControl: "blitz_3_2", rated: false });

// Opt out of the ~30s bot fallback and wait for a human until the queue TTL (~90s):
client.queue({ variant: "standard", timeControl: "blitz_3_2", rated: true, autoBot: false });

// Leave the pool:
client.queueCancel();
// Disconnecting also leaves the queue immediately — the engine sees presence
// directly and holds no seat. After a network blip, re-enqueue on reconnect.

// On pairing the engine pushes match_found — BEFORE that room's first game_state —
// so the client routes to the board on it. Seat ratings are match-time snapshots,
// display info only, never authoritative:
{
  "type": "match_found",
  "matchId": "match_abc",              // the room id — route to the board
  "variant": "standard",
  "timeControl": "blitz_3_2",
  "players": [
    { "userId": "user_123", "username": "alice", "color": "white", "rating": 1512 },
    { "userId": "user_456", "username": "bob",   "color": "black", "rating": 1498 }
  ]
}

// The autoBot fallback pushes the same event — the isBot seat is how the client
// knows the opponent is a computer (a bot seat carries no username):
{
  "type": "match_found",
  "matchId": "match_def",
  "variant": "standard",
  "timeControl": "blitz_3_2",
  "players": [
    { "userId": "user_123", "username": "alice", "color": "white" },
    { "userId": "stockfish", "color": "black", "isBot": true, "botLevel": 4 }
  ]
}

client.on("matchFound", (m) => {
  const opp = m.players.find((p) => p.userId !== myUserId);
  enterGame(m.matchId, { vsBot: !!opp?.isBot, oppName: opp?.username, oppRating: opp?.rating });
});

// Nothing here needs to be persisted: every game_state repeats the same
// identity (variant, timeControl, players) — a client that reconnects after a
// page reload renders the opponent from the snapshot alone.

// The clock does NOT start at room creation — a presence gate holds it.
// game_state tells you everything about the gate:
{
  "type": "game_state", "room": "match_abc",
  "status": "active",           // the game EXISTS — but…
  "started": false,             // …the clock is NOT running yet
  "gate": "ready_check",        // ready_check | grace_period | none
  "youAccepted": false,         // THIS recipient hasn't confirmed yet
  "gateEndsAt": 1719828030000,  // unix ms no-show deadline (only while !started)
  "serverNow": 1719828000000,
  /* …fen, turn, you, moves, whiteMs, blackMs as usual… */
}

client.accept();   // ready_check: confirm presence; every accept re-broadcasts
                   // state to both seats, so the waiting player sees "opponent ready"

// Until started flips to true, a move is refused with error code not_started.
// Not both accepted by gateEndsAt (~30s) → no-show:
//   game_over { result: "aborted", reason: "no_show" } on the socket
//   match_aborted callback to the platform — and the player who DID show up
//   is requeued automatically.

// Playing a bot is a socket message — no REST endpoint, no queue, no gate.
client.playBot({ level: 6, color: "white", timeControl: "blitz_3_2" });

// Resolves immediately: match_found (its stockfish seat has isBot + botLevel)
// followed by game_state — the client routes to the board the same way as a
// human pair. The game is ALWAYS unrated, and no platform callback fires for
// starting it (the game_result at the end fires as usual, without ratings).
// level clamps to 1..8, color defaults to "white".
// No Stockfish available → error code bots_unavailable.

// Distinct from the autoBot fallback: a seeker unpaired after ~30s (autoBot on)
// is dropped to an unrated bot game and that one DOES emit the match_found
// callback, with a single player.