> ## Documentation Index
> Fetch the complete documentation index at: https://docs.playflowcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lobbies & Matchmaking Overview

> Understand how PlayFlow lobbies and matchmaking work, and how to pick the right pattern for your game.

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.

> [!NOTE]
>
> 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.

> [!TIP]
>
> **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.

> [tab] Quick Match
>
> **"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.

> [tab] Invite a Friend
>
> **"Create a game, share a code, friends join, start playing."**
>
> **1. Host creates a lobby**
>
> `POST /v3/lobbies/casual` — returns an invite code like `MEOW-42`.
>
> **2. Friend joins with the code**
>
> `POST /v3/lobbies/casual/join` with `{"code": "MEOW-42"}`.
>
> **3. Ready up, pick teams**
>
> Each player sets their state: `PATCH /v3/lobbies/casual/me` with `{"state": {"ready": true, "team": "blue"}}`.
>
> **4. Host starts the game**
>
> `POST /v3/lobbies/casual/me/start` — launches a dedicated server immediately.
>
> **Best for:** Party games, Among Us-style lobbies, Minecraft-style private worlds, custom matches.

You can combine both. A lobby can host friends, then optionally queue for matchmaking to find more players.

***

## Authentication

Every request has two headers:

| Header | Purpose | Example |
| :- | :- | :- |
| `api-key` | Your project's API key | `pfclient_abc123...` |
| `x-player-id` | Unique identifier for the player | `player_12345` or any string |

> [!WARNING]
>
> `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.

> [!NOTE]
>
> 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](https://docs.playflowcloud.com/guides/player-authentication) for setup.

***

## Response Shape

Every lobby endpoint returns the same consistent shape:

```json theme={null}
{
  "id": "a1b2c3d4-...",
  "code": "MEOW-42",
  "config": "ranked",
  "status": "waiting",
  "host": "player1",
  "maxPlayers": 8,
  "currentPlayers": 2,
  "region": "us-east",
  "isPrivate": false,
  "allowLateJoin": true,
  "settings": { "map": "forest" },
  "players": [
    { "id": "player1", "state": { "ready": true }, "isHost": true },
    { "id": "player2", "state": { "ready": false }, "isHost": false }
  ],
  "server": null,
  "matchmaking": null,
  "matchId": null,
  "createdAt": "2026-04-01T00:00:00Z",
  "updatedAt": "2026-04-01T00:00:01Z"
}
```

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.

```json theme={null}
{
  "customProperties": {
    "gameMode": "ctf",
    "mapRotation": ["forest", "desert", "ice"],
    "crossplayEnabled": true
  }
}
```

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

> [card] [Quickstart](https://docs.playflowcloud.com/lobbies/quickstart.md)
>
> Get a working lobby in 5 minutes with copy-paste curl commands.

> [card] [Lobby Lifecycle](https://docs.playflowcloud.com/lobbies/lifecycle.md)
>
> Create, join, update your own state, kick, automatic host handoff, start games.

> [card] [Matchmaking](https://docs.playflowcloud.com/lobbies/matchmaking.md)
>
> Configure modes, skill-based rules, asymmetric teams, expanding buckets.

> [card] [Real-time Events](https://docs.playflowcloud.com/lobbies/real-time.md)
>
> Subscribe to SSE for live lobby updates and queue stats.

> [card] [API Reference](https://docs.playflowcloud.com/api-reference/introduction.md)
>
> Every endpoint with request/response schemas and try-it-out.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.