Matchmaking overview

multiplayer gives you an authoritative session once players are in it. This is how they get there — and there are four ways, because the four are genuinely different situations rather than one feature with options.

A room code. Short, shareable, short-lived, limited-use. For playing with somebody who is already beside you, or in the same chat window.

A direct invite, by email or screen name, pending until the invitee accepts. For playing with somebody specific who is not here right now.

A friend graph, symmetric and formed by mutual accept. For playing with somebody you play with often.

An open queue. For playing with a stranger, right now, who is roughly your level.

Every one of them ends at a session id.

The queue is the interesting one

One Durable Object per game pairs waiting players, bucketed two ways:

By region, from Cloudflare’s own edge geolocation — which is free, accurate, and does not require a latency probe.

By skill, read from rating when it is composed — widening each player’s band the longer they wait, until any opponent qualifies.

That widening is the whole answer to the tradeoff every queue has: a tight band gives fair matches and long waits, a loose one gives fast matches and unfair ones. Widening over time gives fair matches when the pool is deep and fast ones when it is not, without you choosing which.

Without rating composed, the queue buckets by region alone. It works, and it will match a strong player against a beginner as readily as anybody else.

Presence is a WebSocket, and it hibernates

A second Durable Object holds every online player’s connection and pushes what happens in real time: match found, invite received, friend request — and, when an operator acts, an invite canceled or a drop from the queue.

It uses Cloudflare’s Hibernation API, which is the detail that makes it affordable — a connection waiting on nothing bills no duration. A thousand players sitting in a lobby is not a thousand running objects.

Every frame on it is a Zod schema, and its version is negotiated at the upgrade. A client offers pithy.presence.v1, and the Worker’s asyncapi.json describes every frame, so a Unity or mobile client reads the same events a web app does. The socket contract is how a frame may change between releases.

Two Durable Objects means real wiring

Two bindings, two class migration tags, two exports from your Worker’s entry, across every environment. The CLI writes all of it.

That wiring is the reason this is a capability rather than a snippet. The code that pairs two players is not the hard part; the part that is hard to get right and tedious to redo per environment is everything around it.

Nothing here is a hard dependency

That is unusual enough to state plainly, and each absence has a defined behavior rather than a crash:

WithoutWhat happens
authEvery route denies. There is no anonymous matchmaking
ratingThe queue buckets by region alone
multiplayerSession minting is off. The four ways in still work; they just do not produce a game

Add auth at minimum. The other two are what turn players found each other into players are playing.

What it deliberately does not do

No chat. Not in a lobby, not in a session, not in a friend request.

No parties or teams as a first-class idea. A group of friends entering the queue together is not modeled.

No skill estimation of its own. It reads a number rating produces, rather than estimating one of its own.

No player moderation. Blocking, reporting and banning are your product’s, and they belong next to your own user tables. What a management client gets is housekeeping: it reads who is waiting, every open room and every pending invite, and it cancels a stuck invite or drops a wedged player from a queue, each with a reason that is audited. The reference has the routes.

Read the cost page before production

A presence socket is cheap. A busy queue’s alarm cadence is the dial that decides how cheap, and it is the one number in this capability that can surprise you on a bill.

What a waiting queue costs works through the sweep, what it costs at several queue sizes, and how to tune it. It is a short page and it is worth the ten minutes before you ship, not after.

When you would reach for it

Any multiplayer game where players do not already know each other’s session ids — which is every multiplayer game.

Pick the ways in that match your product. A party game may only ever need room codes; a competitive ladder lives on the queue; most games want three of the four and turn the fourth off.

What it needs

No required peers. auth at minimum in practice.

ESC