Three ways players meet
| Way | Call | Use it for |
|---|---|---|
| Quickmatch | mp.quickmatch({ mode, meta, max_players }) | “Play now”: join the best matching room or create one, in one round trip |
| Private room | mp.create() + mp.join(code) | Playing with friends via a six-character code |
| Browse | mp.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');Room lifecycle
- Phases:
lobby→playing→ended. The host moves the room withroom.settings({ phase: 'playing' }); moving toplayinggenerally 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 }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.
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