Skip to main content
PlayFlow’s lobby system is the bridge between “my players want to play together” and “here’s your dedicated game server.” It handles everything in between: creating rooms, sharing invite codes, queueing for matchmaking, forming matches, and launching game servers.
This is V3, PlayFlow’s primary lobby API. It’s a clean, player-centric REST API with SSE for real-time updates. If you’re migrating from the older NestJS lobby system at api.scale.computeflow.cloud, that system continues to work — V3 is the new recommended path.

​
Core Concepts

​
Lobbies

A lobby is a virtual room where players gather before a game starts. Every lobby has:
  • A host — the player who created it (has admin powers: kick, settings, start game)
  • A list of players with their individual state (ready, team, loadout, MMR, etc.)
  • Settings — game-specific data (map, mode, difficulty) that gets passed to the game server
  • A status: waiting, in_queue, in_game, etc.
  • Optional invite code for sharing with friends

​
Lobby Configs

A lobby config is a reusable template for lobbies. You define it once (in the dashboard or via API) and reference it by name in your code:
  • casual — 8 players, quick play, no MMR
  • ranked_2v2 — 4 players, MMR-based matchmaking, 2 teams of 2
  • monster_hunt — asymmetric, 1 monster vs 5 hunters
Each config specifies server size, build, matchmaking modes, rules, and more.
No dashboard config needed to get started. Any config name in the URL path works — PlayFlow falls back to sensible defaults (2 players, 5-minute timeout, small server size, “default” build) when no matching config exists.

​
Matchmaking

Matchmaking is when players queue up and the system finds them opponents. A matchmaking game is just a group of lobbies grouped together pointing to the same game server. When two (or more) lobbies enter the queue and match:
  1. They all transition from in_queue to in_game
  2. One dedicated game server is launched
  3. All matched lobbies get the same matchId and server connection info
  4. Players connect to the server and play
Matchmaking supports:
  • Traditional teams — 2v2, 5v5, 100-player FFA, 50-duo battle royale
  • Asymmetric roles — 1 boss vs 5 hunters, custom team compositions
  • 5 rule primitives — difference (skill buckets), equals / not_equals (version, anti-rematch), region (overlap), expression (CEL for anything custom)
  • Auto-expanding buckets — MMR ranges grow automatically as wait time grows
  • Region-aware — weighted voting across player region preferences
  • Match confirmation — CS2/LoL “Accept Match” dialog with configurable timeout
  • Rematch — host can end a match and keep the same players in the lobby
  • Self-healing — lobbies never dead-end, always recover when a server stops
  • Backfill — new players can join matches already in progress

​
The Two Core Flows

Most games use one of these patterns. Pick the one that fits your game.
“Just put me in a game.” The player presses a button, gets connected to a server within seconds.
1

Player creates a lobby

POST /v3/lobbies/ranked — instant, even with no friends.
2

Host starts matchmaking

POST /v3/lobbies/ranked/me/matchmaking with a mode name.
3

System finds opponents

Another queueing lobby matches within seconds.
4

Game server launches

All matched lobbies get a populated server.network_ports[]. Connect your game client to host:external_port.
Best for: Ranked ladders, competitive play, quick play modes, Counter-Strike/League of Legends-style matchmaking.
You can combine both. A lobby can host friends, then optionally queue for matchmaking to find more players.

​
Authentication

Every request has two headers:
x-player-id is not authenticated by default — it’s just an identifier, and PlayFlow trusts whatever value you send. For Phase 0 / prototyping, a random UUID per session is fine.
No player auth is required to start using lobbies. Ship an MVP with random player IDs, add real auth later when you need it.
When you need trusted identity, PlayFlow can verify players for you. Configure a player-auth provider — custom JWT, PlayFab, or Steam — and clients send an x-player-token header that PlayFlow verifies; the verified identity is used and x-player-id is ignored. See Player Authentication for setup.

​
Response Shape

Every lobby endpoint returns the same consistent shape:
When matchmaking is active, matchmaking populates with { mode, startedAt, queueStats, confirmation } — confirmation is only set while the lobby status is match_found (the accept/decline phase). When a game server is running, server mirrors the GET /v3/servers/{id} shape exactly, including instance_id, status, region, and network_ports[]. Read the connection host and port from server.network_ports[] (see Step 4 above) — never hardcode a port.

​
Custom Properties

customProperties on a lobby config is arbitrary JSON-serializable metadata attached to every lobby of that type. PlayFlow itself never reads these values — they are surfaced to game clients in the lobby response so you can drive filters, flags, and UI labels.
Use this for whatever your game needs: game modes, map rotations, skill floor labels, feature flags, regional overrides. Anything you want visible to clients when they browse lobbies.

​
What’s Next

Quickstart

Get a working lobby in 5 minutes with copy-paste curl commands.

Lobby Lifecycle

Create, join, update your own state, kick, automatic host handoff, start games.

Matchmaking

Configure modes, skill-based rules, asymmetric teams, expanding buckets.

Real-time Events

Subscribe to SSE for live lobby updates and queue stats.

API Reference

Every endpoint with request/response schemas and try-it-out.