Game config
| Field | Default | |
|---|---|---|
key | — | A URL path segment |
players | — | How many form a match |
skillPool | — | A rating pool to bucket on. Omit for region only |
snapshot | — | The multiplayer session a formed match is minted into |
roomCodes.ttlSeconds | 900 | |
roomCodes.maxUses | 9 | |
queue.initialBand | Skill width at enqueue | |
queue.widenPerSecond | Growth per second waited | |
queue.maxWaitSeconds | After which the band is unbounded | |
queue.sweepSeconds | 5 | The cost dial |
Top level: friends (default on), basePath (default /matchmaking). The queue block is the waiting queue’s dial set; the rest configures the other three ways in.
Routes
Shaped like every route in the kit, and refusing with an ordinary error code.
Every player route is user — bearer or session. The management routes are control-plane, below.
| Route | |
|---|---|
POST /matchmaking/games/:game/rooms | Open a room |
POST /matchmaking/rooms/:code/join | |
POST /matchmaking/games/:game/invites | |
GET /matchmaking/invites | |
POST /matchmaking/invites/:id/accept | |
POST /matchmaking/invites/:id/decline | |
GET /matchmaking/friends | |
POST /matchmaking/friends/:userId/request | |
POST /matchmaking/friends/:userId/accept | |
POST /matchmaking/friends/:userId/decline | |
DELETE /matchmaking/friends/:userId | |
POST /matchmaking/games/:game/queue | |
GET /matchmaking/games/:game/queue | |
DELETE /matchmaking/games/:game/queue | |
GET /matchmaking/presence | WebSocket. Offer pithy.presence.v1 |
There is no public surface. Every player route binds to the authenticated user id, never to a client-supplied one. The friend routes mount only when friends is on.
Management
With the control plane composed, a management client sees who is waiting and acts on it. Every path sits under admin/, so none can collide with a player route.
| Route | Scope | |
|---|---|---|
GET /matchmaking/admin/games | matchmaking:queues:read | Every configured game, in config order: its key, which is what each :game below takes, players, skillPool or null, whether room codes and the queue are enabled, and maxWaitSeconds. Read from config, so it answers the same against an empty database |
GET /matchmaking/admin/games/:game/queue | matchmaking:queues:read | Each waiting player’s region, skill, current band and wait, read from the game’s queue object |
GET /matchmaking/admin/games/:game/rooms | matchmaking:queues:read | Open rooms: code, host, occupancy, uses left, and age. A page can hold fewer than asked; read on while nextCursor is set |
GET /matchmaking/admin/invites | matchmaking:queues:read | Every pending invite, newest first, paged, optionally for one game |
POST /matchmaking/admin/invites/:id/cancel | matchmaking:queues:moderate | Cancel a pending invite. Both players are told |
POST /matchmaking/admin/games/:game/queue/:userId/drop | matchmaking:queues:moderate | Drop a waiting player. The player is told why |
Each act takes an idempotencyKey and a required reason, and nothing else. A retry with the same key changes nothing, tells nobody, emits nothing and answers replayed: true. A drop’s key is remembered for a day, in that game’s queue. A key already spent canceling another invite, or dropping another player from the same queue, is core/conflict.
The reason a drop carries goes to the player, on the queue_dropped frame, so write it for them. Each first act writes one audit event, matchmaking/invite_canceled or matchmaking/queue_player_dropped, carrying the connection, the game, the target and the reason.
The read is all GETs, so pithy dashboard connect grants it by default; the acts are POSTs and never are. No route reads or writes the friend graph: friend edges are the players’ own.
Room codes
WXYZ-1234 — four letters, four digits.
Alphabets exclude I, O, 0 and 1. Join tolerates lowercase, whitespace and a missing dash.
Presence events
{ type: "init"; pendingInvites: InviteView[]; onlineFriends: string[] }
{ type: "match_found"; sessionId: string; gameKey: string }
{ type: "invite"; inviteId: string; gameKey: string; from: string }
{ type: "friend_request"; from: string }
{ type: "invite_canceled"; inviteId: string; gameKey: string }
{ type: "queue_dropped"; gameKey: string; reason: string }
{ type: "error"; error: { code, status, message } }init arrives once, on connect: pending invites, and which friends are online. invite_canceled reaches both players when a management client cancels an invite, which can then no longer be accepted; queue_dropped reaches a player dropped from a queue, in the operator’s words. error answers a frame the socket cannot accept, on pithy.presence.v1 only. The keepalive is plain text: ping, answered with pong. Subprotocols and how a frame may change are the socket contract.
Identity is a server-set header, stashed with serializeAttachment so it survives eviction.
Soft ceiling around 1,000 requests per second — one shared object. A throughput ceiling, not a bill.
Bindings
| Binding | Kind | |
|---|---|---|
DB | D1 | |
MATCHMAKING | KV | You paste the namespace id |
QUEUE | Durable Object | MatchmakingQueue |
PRESENCE | Durable Object | MatchmakingPresence |
SESSIONS | Durable Object | Multiplayer’s, not declared here |
Both classes are exported from their own modules, never the package entry point.
Storage
pithy_matchmaking_invites | Indexed by invitee, carrying the session id once accepted, and the cancel’s idempotency key once canceled |
pithy_matchmaking_friends | One row per pair, indexed both ways |
KV matchmaking:<code> | Room codes |
Queue state is the queue object’s own storage. Presence is the live socket set. Neither is a row you keep.
Error codes
| Code | |
|---|---|
matchmaking/room_not_found | |
matchmaking/room_full | |
matchmaking/invalid_code | |
matchmaking/invite_not_found | Also an invite no longer pending — accepted, declined or canceled. Nothing is minted for one |
matchmaking/invite_forbidden | |
matchmaking/already_friends | |
matchmaking/friend_request_not_found | |
matchmaking/user_not_found | A screen name matching zero users, or several |
matchmaking/not_queued | Also a drop naming a player who is not waiting |
Seams
| Absent | Result |
|---|---|
| Auth | Every route denies |
| Rating | Region-only bucketing |
| Multiplayer | Pairing runs; no session can be minted |