Matchmaking reference

Game config

FieldDefault
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.ttlSeconds900
roomCodes.maxUses9
queue.initialBandSkill width at enqueue
queue.widenPerSecondGrowth per second waited
queue.maxWaitSecondsAfter which the band is unbounded
queue.sweepSeconds5The 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/roomsOpen 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/presenceWebSocket. 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.

RouteScope
GET /matchmaking/admin/gamesmatchmaking:queues:readEvery 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/queuematchmaking:queues:readEach waiting player’s region, skill, current band and wait, read from the game’s queue object
GET /matchmaking/admin/games/:game/roomsmatchmaking:queues:readOpen rooms: code, host, occupancy, uses left, and age. A page can hold fewer than asked; read on while nextCursor is set
GET /matchmaking/admin/invitesmatchmaking:queues:readEvery pending invite, newest first, paged, optionally for one game
POST /matchmaking/admin/invites/:id/cancelmatchmaking:queues:moderateCancel a pending invite. Both players are told
POST /matchmaking/admin/games/:game/queue/:userId/dropmatchmaking:queues:moderateDrop 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

BindingKind
DBD1
MATCHMAKINGKVYou paste the namespace id
QUEUEDurable ObjectMatchmakingQueue
PRESENCEDurable ObjectMatchmakingPresence
SESSIONSDurable ObjectMultiplayer’s, not declared here

Both classes are exported from their own modules, never the package entry point.

Storage

pithy_matchmaking_invitesIndexed by invitee, carrying the session id once accepted, and the cancel’s idempotency key once canceled
pithy_matchmaking_friendsOne 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_foundAlso 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_foundA screen name matching zero users, or several
matchmaking/not_queuedAlso a drop naming a player who is not waiting

Seams

AbsentResult
AuthEvery route denies
RatingRegion-only bucketing
MultiplayerPairing runs; no session can be minted
ESC