Home/Guides/How a matchmaking API works

guide · matchmaking

How a matchmaking API works

Matchmaking answers one question: which players end up in the same room? Here is the whole model — quickmatch, private codes, filters and room lifecycle — with code you can run.

Free sandbox · $19.99/mo to go live · cancel anytime

the model

Three ways players meet

WayCallUse it for
Quickmatchmp.quickmatch({ mode, meta, max_players })“Play now”: join the best matching room or create one, in one round trip
Private roommp.create() + mp.join(code)Playing with friends via a six-character code
Browsemp.list({ mode, 'meta.map': 'desert' })A server list or lobby browser
const room = await mp.quickmatch({
  mode: 'duel',
  meta: { map: 'desert', rank: 'gold' },   // free-form: your game decides what it means
  max_players: 2,
});

// or fail instead of creating a new room
await mp.quickmatch({ mode: 'duel', join_only: true });

// private game with friends
const priv = await mp.create({ max_players: 4 });
console.log(priv.code);                    // e.g. B2K2D3 — send it to a friend
await otherPlayer.join('B2K2D3');
lifecycle

Room lifecycle

  • Phases: lobby → playing → ended. The host moves the room with room.settings({ phase: 'playing' }); moving to playing generally locks it.
  • Capacity: up to 128 players per room; spectators (up to 64, opt-in) do not take a seat.
  • Host: the first player. If they leave, the longest-present player becomes host automatically and every client converges on the same one. Listen to room.on('host', …).
  • Cleanup: empty rooms survive about two minutes so a reconnecting player finds theirs; players who vanish are removed within about 25 seconds.

Skill and region matching

The API assigns no meaning to metadata. A common pattern is to bucket players (rank: 'gold', region: 'eu') and pass the bucket as meta on quickmatch, so only compatible players share a room. The same keys filter GET /v1/rooms?mode=duel&meta.rank=gold.

Plain HTTP

POST /v1/rooms/quickmatch      Authorization: Bearer mp_at_...   X-Mp-Key: mp_pk_...
{ "mode": "duel", "meta": { "map": "desert" }, "max_players": 2 }

→ { "ok": true, "room": { "code": "B2K2D3", ... }, "me": {...}, "members": [...], "created": false, "tick_ms": 2000 }
pitfalls

Mistakes to avoid

  • Making players register first. Use guest accounts and offer upgrade() later.
  • Ignoring tick_ms. It is the recommended cadence for the sync loop; respecting it is the main cost lever.
  • Forgetting host migration. Hosts leave more often than you expect.

Next: build a complete multiplayer browser game, or read the rooms and matchmaking reference.

Questions
What is a matchmaking API?

A service that groups players into game sessions. It decides which room a player joins, creates rooms when none match, and manages their lifecycle.

Does quickmatch support skill-based matching?

You express skill or region as free-form meta on quickmatch and room search, so players are only matched with compatible rooms. The API does not impose a rating system.

Can players join by code?

Yes. mp.create() returns a six-character code that friends pass to mp.join().

Make your game online today

Free sandbox keys in one call, no account and no card. $19.99/month when you ship, for every game you make.

Free sandbox · $19.99/mo to go live · cancel anytime