# CLAUDE
Source: https://docs.playflowcloud.com/CLAUDE



# CLAUDE.md

# Mintlify documentation

## Working relationship

* You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so
* ALWAYS ask for clarification rather than making assumptions
* NEVER lie, guess, or make up information

## Project context

* Format: MDX files with YAML frontmatter
* Config: docs.json for navigation, theme, settings
* Components: Mintlify components

## Content strategy

* Document just enough for user success - not too much, not too little
* Prioritize accuracy and usability of information
* Make content evergreen when possible
* Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason
* Check existing patterns for consistency
* Start by making the smallest reasonable changes

## docs.json

* Refer to the [docs.json schema](https://mintlify.com/docs.json) when building the docs.json file and site navigation

## Frontmatter requirements for pages

* title: Clear, descriptive page title
* description: Concise summary for SEO/navigation

## Writing standards

* Second-person voice ("you")
* Prerequisites at start of procedural content
* Test all code examples before publishing
* Match style and formatting of existing pages
* Include both basic and advanced use cases
* Language tags on all code blocks
* Alt text on all images
* Relative paths for internal links

## Git workflow

* NEVER use --no-verify when committing
* Ask how to handle uncommitted changes before starting
* Create a new branch when no clear branch exists for changes
* Commit frequently throughout development
* NEVER skip or disable pre-commit hooks

## Do not

* Skip frontmatter on any MDX file
* Use absolute URLs for internal links
* Include untested code examples
* Make assumptions - always ask for clarification

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Repository Overview

This is the documentation repository for PlayFlow Cloud, a game-server orchestration platform for multiplayer games. The documentation is built using Mintlify, a modern documentation platform optimized for developer docs.

## Common Development Commands

```bash theme={null}
# Install Mintlify CLI (required for local development)
npm i -g mintlify

# Run local development server (default port 3000)
mintlify dev

# Run on custom port
mintlify dev --port 3333

# Check for broken links
mintlify broken-links

# Troubleshooting: Reinstall dependencies if dev server fails
mintlify install
```

## Architecture & Structure

### Core Configuration

* **docs.json** - Main configuration file that defines:
  * Navigation structure (tabs, groups, pages)
  * Theme settings (colors, icons, logos)
  * SEO metadata
  * API reference integration via OpenAPI specs

### Content Organization

* **MDX Format**: All documentation uses MDX (Markdown + JSX components)
* **Frontmatter**: Each page includes metadata (title, description, icon)
* **Navigation**: Two-tab structure - "Documentation" and "API Reference"

### Key Directories

* `/api-reference/` - API reference pages
  * `introduction.mdx` - API overview, auth, rate limits, error format
  * Endpoint pages are generated from the live OpenAPI spec at `https://api.computeflow.cloud/api/doc` (configured in `docs.json`). Do not check in local OpenAPI JSON files — the Hono engine serves the canonical spec.
* `/unity/` - Unity SDK documentation with lobby system and matchmaking guides
* `/guides/` - Tutorials including WebGL deployments and migration guides
* `/fundamentals/` - Core concepts like plan instance types
* `/images/` - Documentation images and diagrams
* `/logo/` - Brand assets (light/dark mode SVGs)

### Mintlify Components

Common components used throughout the docs:

* `<Card>` and `<CardGroup>` - Feature cards with icons
* `<Info>`, `<Warning>`, `<Tip>` - Callout boxes
* `<CodeGroup>` - Multi-language code examples
* `<ResponseExample>` - API response examples

### Deployment

* Automatic deployment via GitHub App integration
* Changes to main branch auto-deploy to production
* No manual build process required

## PlayFlow Context

This documentation covers:

* **Game Server Management**: On-demand server spinning, auto-scaling
* **Matchmaking System**: ELO-based, region-aware player matching
* **Lobby System**: WebSocket-powered lobbies with chat and ready-checks
* **Unity SDK**: Primary SDK focus with comprehensive guides
* **WebGL Deployments**: Browser-based game hosting
* **Global Infrastructure**: Multi-region, multi-cloud support

## Development Guidelines

1. **MDX Best Practices**:
   * Use appropriate Mintlify components for better UX
   * Include code examples in relevant languages (Unity C#, REST API)
   * Add icons to pages via frontmatter for visual hierarchy

2. **API Documentation**:
   * API reference endpoint pages are auto-generated from the live OpenAPI spec served by the engine at `https://api.computeflow.cloud/api/doc`.
   * API contract changes happen in `playflow-core/engine/` (routes, Zod schemas). Regenerate the local snapshot with `npm run generate:openapi` for inspection.
   * Don't manually edit generated API reference pages.

3. **Navigation Updates**:
   * Modify `docs.json` to add/remove pages or reorganize structure
   * Maintain logical grouping (Getting Started → SDK → Advanced)
   * Use descriptive icons from Lucide icon set

4. **Local Development**:
   * Always run `mintlify dev` to preview changes
   * Test navigation and links before committing
   * Verify images load correctly from `/images/` directory


# Create build from Docker image
Source: https://docs.playflowcloud.com/api-reference/builds/create-build-from-docker-image

https://api.computeflow.cloud/api/doc post /api/v3/builds/docker-image
Creates a build from an existing Docker image instead of uploading a ZIP. PlayFlow pulls the image and makes it available for deployment.

Processing is triggered automatically — no need to call `/process` separately. Poll `GET /builds/{build_id}` until status is `ready`.

For private registries, provide `registry_credentials` with username and password/token. Public images (Docker Hub, ghcr.io public repos) don't need credentials.



# Delete a build
Source: https://docs.playflowcloud.com/api-reference/builds/delete-a-build

https://api.computeflow.cloud/api/doc delete /api/v3/builds/{build_id}
Soft-deletes a build and cleans up its stored artifacts. The build status is set to `deleted` and it will no longer appear in list responses or be usable for starting new servers. **Requires a server key (pf_...); client keys (pfclient_*) are rejected with 403.**

**Note:** Servers already running with this build are unaffected — deletion only prevents new servers from using it.



# Get build details
Source: https://docs.playflowcloud.com/api-reference/builds/get-build-details

https://api.computeflow.cloud/api/doc get /api/v3/builds/{build_id}
Returns the full details of a specific build including its status, version, and type. Use this to poll for status changes during processing (`uploading` → `processing` → `ready` or `failed`).



# Get build processing logs
Source: https://docs.playflowcloud.com/api-reference/builds/get-build-processing-logs

https://api.computeflow.cloud/api/doc get /api/v3/builds/{build_id}/logs
Returns paginated build processing logs in chronological order. Each log entry includes a phase (e.g., download, extract, compress, upload), a message, and a severity level.

Useful for debugging failed builds — check for `error` level entries. Build logs are also available for live streaming in the PlayFlow dashboard.



# Get presigned upload URL
Source: https://docs.playflowcloud.com/api-reference/builds/get-presigned-upload-url

https://api.computeflow.cloud/api/doc post /api/v3/builds/upload-url
Generates a presigned upload URL for uploading your game server as a ZIP file. Upload flow:

1. **Call this endpoint** to get a `build_id` and `upload_url`
2. **PUT your ZIP** directly to the `upload_url` (expires in 5 minutes)
3. **Done!** Processing starts automatically when the upload completes
4. **Poll GET /builds/{build_id}** until status is `ready`

Versions auto-increment per build name: first "default" build is version 1, next is version 2, etc.



# List builds
Source: https://docs.playflowcloud.com/api-reference/builds/list-builds

https://api.computeflow.cloud/api/doc get /api/v3/builds
Returns a paginated list of builds for your project, sorted by creation date (newest first). Soft-deleted builds are excluded. Use the `name` filter to list versions of a specific build name.



# API Introduction
Source: https://docs.playflowcloud.com/api-reference/introduction

Authenticate, explore endpoints, and download the OpenAPI spec for the PlayFlow REST API.

PlayFlow is a game server hosting and orchestration platform. Deploy, manage, and scale multiplayer game servers globally with built-in matchmaking, lobby management, and billing.

<CardGroup>
  <Card title="OpenAPI Spec (JSON)" icon="download" href="https://api.computeflow.cloud/api/doc">
    Download the machine-readable OpenAPI 3.1 spec for use with Postman, code generators, or custom tooling.
  </Card>

  <Card title="Interactive Reference" icon="flask-vial" href="https://api.computeflow.cloud/api/reference">
    Try out endpoints directly in the Scalar API playground with live request/response previews.
  </Card>
</CardGroup>

***

## Authentication

All API endpoints (except Health) require the `api-key` header:

```bash theme={null}
curl https://api.computeflow.cloud/api/v3/servers \
  -H "api-key: pf_your_project_api_key"
```

Each project has two keys:

| Key Type       | Prefix       | Use Case                             |
| :------------- | :----------- | :----------------------------------- |
| Server API Key | `pf_*`       | Backend services, CI/CD, admin tools |
| Client API Key | `pfclient_*` | Game clients, browser apps           |

<Info>
  Find your API keys in the [PlayFlow Dashboard](https://app.playflowcloud.com) under **Project Settings**.
</Info>

<Warning>
  Never expose your **Server API Key** in client-side code. Use the **Client API Key** for anything that ships to players.
</Warning>

<Info>
  A few operations — deleting builds and updating project settings — require a **Server API Key**. A Client API Key on these endpoints returns `403`.
</Info>

***

## Quick Start

<Steps>
  <Step title="Upload a build">
    `POST /v3/builds/upload-url` — get a presigned URL, then `PUT` your ZIP to it. Processing starts automatically when the upload completes.
  </Step>

  <Step title="Wait for it to be ready">
    Poll `GET /v3/builds/{id}` until `status` is `ready`.
  </Step>

  <Step title="Start a server">
    `POST /v3/servers/start` with a `name`, a `region`, and the build's `version_tag` (its name). The response includes a `network_ports` array with the connection details.
  </Step>

  <Step title="Connect your game client">
    Read `host` and `external_port` from `network_ports[]` in the response to connect players. Ports are proxy-allocated, so always read them from the response rather than hardcoding a fixed port.
  </Step>
</Steps>

For detailed examples with cURL, C#, and Python, see the [full API guide](/fundamentals/api).

***

## Key Concepts

* **Builds** — Your game server binary packaged as a ZIP or Docker image. Versioned per name per project.
* **Servers** — Running game server instances. Each gets dedicated compute and network ports with automatic health monitoring. Servers launch on-demand and cold-start.
* **Regions** — 13 global regions. `region` is required when you start a server. See [Server Regions](/fundamentals/regions) for the full list.
* **Compute Sizes** — 9 launchable sizes, from `micro` (1 shared vCPU / 512MB) to `dedicated-xlarge` (2 perf vCPU / 16GB). The default is `small`. See [Plan & Instance Types](/fundamentals/plan-instance-types).

***

## Lifecycles

### Server Lifecycle

```
launching → running (game ports open) → stopped (game exits, TTL expires, or manual stop)
```

### Build Lifecycle

```
uploading → processing (build pipeline creates deployable image) → ready | failed
```

***

## Rate Limits

| Endpoint Type                    | Limit                   |
| :------------------------------- | :---------------------- |
| Read endpoints (list, get, logs) | 100 req/sec per API key |
| Write endpoints (start, upload)  | 10 req/sec per API key  |

Rate limit status is returned via `X-RateLimit-Limit` and `X-RateLimit-Remaining` headers. Exceeding the limit returns `429`.

***

## Plan Limits

| Plan              | Servers      | TTL                     | Compute Sizes |
| :---------------- | :----------- | :---------------------- | :------------ |
| **Free**          | 1 active max | Forced 1 hour (3600s)   | `small` only  |
| **Pro** (\$20/mo) | Unlimited    | Up to 24 hours (86400s) | All sizes     |

***

## Error Format

All errors return a consistent JSON shape:

```json theme={null}
{
  "error": "Human-readable message",
  "detail": "Additional context",
  "status": 404
}
```

Validation errors (422) include structured details:

```json theme={null}
{
  "error": "Validation error",
  "detail": [
    { "loc": ["region"], "msg": "Required", "type": "invalid_type" }
  ],
  "status": 422
}
```

***

## Base URL

```
https://api.computeflow.cloud/api
```

| Version            | Prefix      | Notes                                    |
| :----------------- | :---------- | :--------------------------------------- |
| **V3** (canonical) | `/api/v3/*` | OpenAPI-validated, clean response shapes |
| **V2** (legacy)    | `/api/v2/*` | Compatibility layer for older SDKs       |


# Browse lobbies
Source: https://docs.playflowcloud.com/api-reference/lobbies/browse-lobbies

https://api.computeflow.cloud/api/doc get /api/v3/lobbies/{config}
Returns a paginated list of public lobbies for the given config. Private (invite-only) lobbies are excluded.

Use `status` to filter by lobby state (`waiting`, `in_queue`, `in_game`). Use `region` to filter by region.

**`includePrivate`:** Set to `true` to also return private lobbies. Honored ONLY when authenticated with a server key (`pf_*`) — the project owner's own dashboard/admin view. Client keys (`pfclient_*`) always get public-only results, so invite codes stay meaningful.

**No x-player-id required.** This endpoint is designed for lobby browsers and server-side matchmaking systems.

Results are ordered by creation time (newest first).



# Cancel matchmaking
Source: https://docs.playflowcloud.com/api-reference/lobbies/cancel-matchmaking

https://api.computeflow.cloud/api/doc delete /api/v3/lobbies/{config}/me/matchmaking
**Host only.** Removes the lobby from the matchmaking queue and returns to `waiting` status.

This clears the `matchmaking` field and stops queue stat updates via SSE.

**Note:** If a match has already been found (`match_found` status), cancellation may not be possible and the game will proceed.



# Confirm a found match
Source: https://docs.playflowcloud.com/api-reference/lobbies/confirm-a-found-match

https://api.computeflow.cloud/api/doc post /api/v3/lobbies/{config}/me/confirm-match
Accepts a match while the lobby is in `match_found` state (CS2-style 'Accept Match' flow).

**Who can call:** Any player in the lobby. Confirmation is per-lobby (parties confirm together).

**Behavior:** Records the confirmation. When every lobby in the match has confirmed, the engine automatically launches the game server and transitions every lobby to `in_game`.

**Match-confirmation requires the mode to be configured with `matchConfirmation.enabled: true`.** If a mode does NOT enable confirmation, matches transition directly from queue to `in_game` and this endpoint returns `409`.



# Create a lobby
Source: https://docs.playflowcloud.com/api-reference/lobbies/create-a-lobby

https://api.computeflow.cloud/api/doc post /api/v3/lobbies/{config}
Creates a new lobby and makes the caller the host. The caller is identified by the `x-player-id` header.

The lobby starts in `waiting` status. Other players can join via `POST /{config}/join` using the lobby ID or invite code (if the lobby is private).

**Lobby config:** The `{config}` path parameter maps to a lobby configuration defined in your project settings. Each config controls timeout, server size, matchmaking modes, and custom properties. If no matching config exists, sensible defaults are used.

**Player state:** Optionally pass `state` to set initial player state (ready status, team, loadout, MMR, etc.). Other players see this in the `players` array.

**Private lobbies:** Set `isPrivate: true` to hide the lobby from browsing and generate an invite code.



# Decline a found match
Source: https://docs.playflowcloud.com/api-reference/lobbies/decline-a-found-match

https://api.computeflow.cloud/api/doc delete /api/v3/lobbies/{config}/me/confirm-match
Declines a match. **Cancels the match for every participating lobby** — all of them return to `waiting`. Players explicitly re-queue when ready.

**Who can call:** Any player in any lobby of the match.

**Compare to `cancel-matchmaking`:** Cancel-matchmaking exits the queue entirely (returns to `waiting`). Decline-match also returns to `waiting` but cancels the match for every participating lobby, not just yours.



# Delete a lobby by ID (admin)
Source: https://docs.playflowcloud.com/api-reference/lobbies/delete-a-lobby-by-id-admin

https://api.computeflow.cloud/api/doc delete /api/v3/lobbies/{config}/{id}
Force-deletes a lobby by ID. Removes all players and cancels any active matchmaking. Unlike `DELETE /{config}/me` (which makes the caller leave), this bypasses ownership checks — use from server-side admin tools only. **Requires a server key (pf_...); client keys (pfclient_*) are rejected with 403.**

**Behavior:**
- Stops any running game server best-effort
- Deletes the lobby row (cascades all player and matchmaking state stored on it)
- Connected SSE clients receive a `lobby_deleted` event and disconnect cleanly

Returns `404` if no lobby with the given ID exists in the caller's project for the specified config.



# End the current match
Source: https://docs.playflowcloud.com/api-reference/lobbies/end-the-current-match

https://api.computeflow.cloud/api/doc post /api/v3/lobbies/{config}/me/end-match
**Host only.** Ends the current in-game match and returns the lobby to `waiting` status so the same players can start another round (or queue again).

**What it does:**
1. Atomically transitions lobby status `in_game` → `waiting`
2. Clears `server`, `matchId`, and `matchmaking` fields
3. Stops the associated game server best-effort
4. Preserves players, settings, and lobby metadata

All players receive a `lobby_updated` SSE event with the reset state.

**When to use:** Rematch flows, party-persistent games, or any scenario where the host wants to reuse the lobby without forcing players to rejoin.

**Natural server exits:** If your game server shuts down on its own, the lobby transitions to `completed` and is cleaned up. Use `end-match` only when the host explicitly wants to rematch with the same group.



# Get lobby by ID
Source: https://docs.playflowcloud.com/api-reference/lobbies/get-lobby-by-id

https://api.computeflow.cloud/api/doc get /api/v3/lobbies/{config}/{id}
Returns the full state of a specific lobby by its ID. No `x-player-id` required. **Requires a server key (pf_...); client keys (pfclient_*) are rejected with 403.**

Use this for admin dashboards, debugging, and server-side systems that need to inspect lobby state without being a participant.

**Note:** This endpoint matches any `{id}` path segment under `{config}`, so it must be registered last to avoid shadowing other routes.



# Get my lobby
Source: https://docs.playflowcloud.com/api-reference/lobbies/get-my-lobby

https://api.computeflow.cloud/api/doc get /api/v3/lobbies/{config}/me
Returns the full state of the lobby the caller is currently in. The caller is identified by `x-player-id`.

If the lobby is in `in_queue` status (matchmaking active), the response includes live `matchmaking.queueStats` with the number of players searching, lobbies in queue, and average wait time.

**Use this to poll lobby state.** For real-time updates, use `GET /{config}/me/events` (SSE) instead.

Returns `404` if the player is not currently in a lobby.



# Join a lobby
Source: https://docs.playflowcloud.com/api-reference/lobbies/join-a-lobby

https://api.computeflow.cloud/api/doc post /api/v3/lobbies/{config}/join
Joins an existing lobby by its ID or invite code. The caller is identified by `x-player-id`.

**By ID:** Set `lobbyId` to the UUID from the browse or create response.

**By invite code:** Set `code` to the invite code shared by the host (e.g. `"MEOW-42"`).

Exactly one of `lobbyId` or `code` must be provided.

**Player state:** Optionally pass `state` to set initial player state on join.

**Errors:**
- `404` — Lobby not found or invalid invite code
- `400` — Lobby is full or not accepting players
- `409` — Player is already in a lobby for this config



# Kick a player
Source: https://docs.playflowcloud.com/api-reference/lobbies/kick-a-player

https://api.computeflow.cloud/api/doc delete /api/v3/lobbies/{config}/me/players/{playerId}
**Host only.** Removes a player from the lobby by their player ID.

The kicked player receives a `lobby_updated` event via SSE showing they are no longer in the lobby. The host cannot kick themselves (use `DELETE /{config}/me` to leave instead).

If the kicked player is the last non-host player, the lobby continues with just the host.



# Leave a lobby
Source: https://docs.playflowcloud.com/api-reference/lobbies/leave-a-lobby

https://api.computeflow.cloud/api/doc delete /api/v3/lobbies/{config}/me
Removes the caller from their current lobby. If the caller is the host, host duty is transferred to the next player. If the caller is the last player, the lobby is deleted.

**Response:**
- If the lobby still has players: returns the updated lobby state.
- If the lobby was deleted (last player left): returns `{ "status": "lobby_deleted" }`.

Players who leave while matchmaking is active are removed from the queue.



# Send a player heartbeat
Source: https://docs.playflowcloud.com/api-reference/lobbies/send-a-player-heartbeat

https://api.computeflow.cloud/api/doc post /api/v3/lobbies/{config}/me/heartbeat
Updates the caller's `lastHeartbeat` timestamp. Only needed if the lobby config has `heartbeat: true` enabled — in that case, players whose heartbeat is older than `heartbeatTimeout` seconds are evicted by the `lobby-sweep` cron.

Use this for polling clients where the SSE connection (which acts as an implicit heartbeat) isn't available. Send every few seconds (well under `heartbeatTimeout`).



# Start matchmaking
Source: https://docs.playflowcloud.com/api-reference/lobbies/start-matchmaking

https://api.computeflow.cloud/api/doc post /api/v3/lobbies/{config}/me/matchmaking
**Host only.** Enters the lobby into the matchmaking queue for the specified mode.

The `mode` must be a matchmaking mode defined in the lobby config (e.g. `"ranked_2v2"`, `"casual_ffa"`).

**How it works:**
1. Lobby status transitions to `in_queue`
2. The matchmaking system immediately attempts to find compatible opponents
3. If no immediate match, the lobby waits in the queue
4. When matched, status transitions to `match_found` and a game server is started

**Queue stats:** The response includes `matchmaking.queueStats` with the number of players searching and average wait time. Players receive live updates via SSE (`queue_stats` events every 10 seconds).

**Cancel:** Use `DELETE /{config}/me/matchmaking` to leave the queue and return to `waiting`.



# Start the game
Source: https://docs.playflowcloud.com/api-reference/lobbies/start-the-game

https://api.computeflow.cloud/api/doc post /api/v3/lobbies/{config}/me/start
**Host only.** Starts the game for the lobby. This triggers a three-step process:

1. Lobby status transitions to `starting`
2. A game server is provisioned (uses the build and compute size from the lobby config)
3. Lobby status transitions to `in_game` with server connection details

The response includes `server.ports` with host and port for game client connections. All players receive a `lobby_updated` event via SSE with the server details.

**Server provisioning** typically takes 10-30 seconds (or ~5 seconds with pool servers). The lobby stays in `starting` status until the server is ready.

If server provisioning fails, the lobby rolls back to `waiting` status.



# Subscribe to lobby events (SSE)
Source: https://docs.playflowcloud.com/api-reference/lobbies/subscribe-to-lobby-events-sse

https://api.computeflow.cloud/api/doc get /api/v3/lobbies/{config}/me/events
Opens a Server-Sent Events (SSE) stream for real-time lobby updates. The caller is identified by `x-player-id`.

**Event types:**

| Event | Description | Frequency |
|-|-|-|
| `connected` | Initial event with full lobby state | Once on connect |
| `lobby_updated` | Lobby state changed (player joined/left, settings changed, game started, etc.) | On every change |
| `lobby_deleted` | Lobby was deleted (all players left or timeout) | Once, then stream closes |
| `queue_stats` | Live matchmaking queue statistics | Every 10s while `in_queue` |
| `ping` | Keep-alive heartbeat | Every 30s |

**Usage (JavaScript):**
```javascript
const es = new EventSource('/api/v3/lobbies/casual/me/events', {
  headers: { 'api-key': 'pf_...', 'x-player-id': 'player123' }
});
es.addEventListener('lobby_updated', (e) => {
  const lobby = JSON.parse(e.data);
  updateUI(lobby);
});
```

**Connection lifecycle:** The stream stays open until the client disconnects, the lobby is deleted, or the player is kicked. Reconnect automatically on disconnect.



# Update lobby settings
Source: https://docs.playflowcloud.com/api-reference/lobbies/update-lobby-settings

https://api.computeflow.cloud/api/doc patch /api/v3/lobbies/{config}/me/settings
**Host only.** Updates the lobby's shared settings (name, max players, region, game settings, etc.).

All fields are optional. Omitted fields keep their current values. The `settings` object is merged with the existing settings (existing keys are preserved unless overwritten).

**Example:** Change the map and toggle private mode:
```json
{ "isPrivate": true, "settings": { "map": "desert" } }
```

All players see setting changes in real-time via the SSE stream.



# Update my player state
Source: https://docs.playflowcloud.com/api-reference/lobbies/update-my-player-state

https://api.computeflow.cloud/api/doc patch /api/v3/lobbies/{config}/me
Updates the caller's player state within the lobby. State is merged with existing state (existing keys are preserved unless explicitly overwritten).

Use this to signal ready status, select a team, set a loadout, report MMR, or store any per-player data that the host or game server needs.

**Example states:**
- `{ "ready": true }`
- `{ "team": "blue", "role": "healer" }`
- `{ "mmr": 1500, "loadout": "sniper" }`

All players in the lobby see state changes in real-time via the SSE stream (`GET /{config}/me/events`).



# Get project settings
Source: https://docs.playflowcloud.com/api-reference/projects/get-project-settings

https://api.computeflow.cloud/api/doc get /api/v3/projects/settings
Returns the complete project configuration including network ports, player authentication, default environment variables, server pool settings, and lobby/matchmaking rules.

These settings are applied as defaults to every server started in this project. Individual settings can be overridden per-server at start time.



# Get project-wide log-volume histogram
Source: https://docs.playflowcloud.com/api-reference/projects/get-project-wide-log-volume-histogram

https://api.computeflow.cloud/api/doc get /api/v3/projects/log-histogram
Returns a stacked info/warn/error log-volume time-series across ALL servers in the project over the same window as the project logs. Overlay it on fleet resource charts to spot which time bucket a freeze/error spike falls in.

Bins are `step` seconds wide (default 60). Empty bins may be omitted — treat gaps as zero.



# Get project-wide server logs
Source: https://docs.playflowcloud.com/api-reference/projects/get-project-wide-server-logs

https://api.computeflow.cloud/api/doc get /api/v3/projects/logs
Retrieves aggregated runtime logs from all servers in the project. Each log entry includes the server name, making it easy to filter and search across your entire fleet.

Use `start_time` and optionally `end_time` to define the time range. Returns the **most recent** entries within that window (up to `limit`), ordered oldest-to-newest.

Narrow results server-side with `search` (case-insensitive substring) and/or `level` (error/warn/info) — both apply across the ENTIRE window, not just the returned page, so you can find a specific error or session ID anywhere in the range. Set `include_counts=true` to also get per-level totals for the window.

**Paging back:** if the window holds more than `limit` entries, pass the response's `older_token` as `end_time` (keeping the same `start_time`) to fetch the next older page. **Live tail:** poll with `next_token` as the next `start_time`; it points just after the newest entry returned, so each poll fetches only newer logs.



# Update project settings
Source: https://docs.playflowcloud.com/api-reference/projects/update-project-settings

https://api.computeflow.cloud/api/doc post /api/v3/projects/settings
Updates project-level configuration. All fields are optional — only include what you want to change. Omitted fields remain unchanged. **Requires a server key (pf_...); client keys (pfclient_*) are rejected with 403.**

**port_configs:** Network ports allocated for every server (max 10). Define game ports, query ports, etc.

**auth_config:** Player authentication provider (none, custom_jwt, playfab, steam).

**environment_variables:** Default env vars injected into every game server.

**pool_config:** Pre-provisioned server pool sizes per region and compute size.

**lobby_configs:** Lobby types with matchmaking rules, team structures, and invite codes (max 20).



# Close backfill (server-authoritative)
Source: https://docs.playflowcloud.com/api-reference/servers/close-backfill-server-authoritative

https://api.computeflow.cloud/api/doc post /api/v3/servers/{instance_id}/backfill/lock
Closes backfill for the match backing this server — no further joiners are admitted. Convenience shorthand for `PATCH /{instance_id}/backfill` with `accepting: false`.

Requires a server API key (`pf_...`).



# Get server details
Source: https://docs.playflowcloud.com/api-reference/servers/get-server-details

https://api.computeflow.cloud/api/doc get /api/v3/servers/{instance_id}
Returns the full details of a specific server instance, including its current status, network ports, configuration, and metadata. Use this to poll for status changes (e.g., wait for `launching` → `running`) or to get connection info for game clients.



# Get server log-volume histogram
Source: https://docs.playflowcloud.com/api-reference/servers/get-server-log-volume-histogram

https://api.computeflow.cloud/api/doc get /api/v3/servers/{instance_id}/log-histogram
Returns a stacked info/warn/error log-volume time-series for a single server over the same window as the logs. Use it to correlate a spike in error volume with a freeze: overlay these buckets on the CPU/memory/network charts on a shared time axis.

Bins are `step` seconds wide (default 60). Empty bins may be omitted — treat gaps as zero.



# Get server resource metrics
Source: https://docs.playflowcloud.com/api-reference/servers/get-server-resource-metrics

https://api.computeflow.cloud/api/doc get /api/v3/servers/{instance_id}/metrics
Returns CPU, memory, network, load, and connection metrics for a running server over a configurable time window. Each metric is a time series of `{t, v}` data points where `t` is a Unix timestamp and `v` is the metric value.

Use `period` to control the time window (e.g., `1h` for last hour) and `step` for data point resolution (e.g., `60s` for one point per minute).

Only available for servers that are currently running.



# Get server runtime logs
Source: https://docs.playflowcloud.com/api-reference/servers/get-server-runtime-logs

https://api.computeflow.cloud/api/doc get /api/v3/servers/{instance_id}/logs
Retrieves runtime logs (stdout/stderr) from a game server, including timestamps, log levels, and region info.

**Pagination:** Use the `next_token` from the response as `start_time` in the next request to fetch subsequent logs. Returns an empty logs array if the server has never launched.



# Get the authoritative match roster
Source: https://docs.playflowcloud.com/api-reference/servers/get-the-authoritative-match-roster

https://api.computeflow.cloud/api/doc get /api/v3/servers/{instance_id}/roster
Returns the authoritative roster of players admitted to the match backing this server. Game servers call this (with their server API key and their own `INSTANCE_ID`) to know exactly which players to admit — this is the source of truth for admission and fixes reconnect / "denied by proxy" edge cases.

The response includes per-team slots, total `capacity`, `current_players`, backfill state, and a monotonically increasing `roster_version`. Poll `roster_version` cheaply to detect roster changes (e.g., when a backfill joiner is admitted).

Only available for servers that back a match (created through matchmaking/lobbies).



# List servers
Source: https://docs.playflowcloud.com/api-reference/servers/list-servers

https://api.computeflow.cloud/api/doc get /api/v3/servers
Returns a paginated list of game servers for your project. By default, only servers in `running` status are returned. Use `include_launching=true` to also see servers that are still starting up, or `include_pool=true` to include pre-provisioned pool machines.



# Override backfill state (server-authoritative)
Source: https://docs.playflowcloud.com/api-reference/servers/override-backfill-state-server-authoritative

https://api.computeflow.cloud/api/doc patch /api/v3/servers/{instance_id}/backfill
Lets an advanced game server take control of its match's backfill. Set `accepting` to open or close backfill joiners, and optionally replace the `skillBand` that gates joiners.

This is an optional override — the engine manages backfill automatically for modes with backfill enabled. Use this only when the game server has better knowledge of when it can accept joiners (e.g., between rounds).

Requires a server API key (`pf_...`).



# Restart a server
Source: https://docs.playflowcloud.com/api-reference/servers/restart-a-server

https://api.computeflow.cloud/api/doc post /api/v3/servers/{instance_id}/restart
Restarts a server with a fresh instance. The old machine is replaced and new network ports are allocated. You can optionally change the build version, compute size, TTL, startup args, and other settings during restart.

All fields in the request body are optional — omitted fields keep their current values. The server returns to `launching` status.

**Note:** Pool servers cannot be restarted.



# Start a new server
Source: https://docs.playflowcloud.com/api-reference/servers/start-a-new-server

https://api.computeflow.cloud/api/doc post /api/v3/servers/start
Creates and launches a new game server instance. The server starts in `launching` status and transitions to `running` when the game process opens its configured ports (typically 10–30 seconds, or ~5 seconds if a pool server is available).

The response includes `network_ports` with the connection details (host + external_port) that game clients need to connect.

**Plan limits:** Free plan allows 1 active server with a 1-hour TTL and `small` compute. Pro plan unlocks unlimited servers with all compute sizes.

**Build resolution:** Uses the latest `ready` build matching `version_tag` (defaults to `"default"`). Pin to a specific build with the `version` parameter.



# Stop a server
Source: https://docs.playflowcloud.com/api-reference/servers/stop-a-server

https://api.computeflow.cloud/api/doc delete /api/v3/servers/{instance_id}
Stops a running server. The status is updated to `stopped` immediately, and infrastructure cleanup happens in the background.

Optionally provide a `shutdown_reason` for analytics (e.g., `PROCESS_EXITED`, `TTL_EXPIRED`). PlayFlow also calls this automatically when the game process exits or TTL expires.



# Update server custom_data
Source: https://docs.playflowcloud.com/api-reference/servers/update-server-custom_data

https://api.computeflow.cloud/api/doc post /api/v3/servers/{instance_id}/update
Updates the `custom_data` field on a running server. Use this to store match state, player counts, map info, or any metadata that your game server or matchmaking system needs to expose via the API. The data is immediately visible in list and get responses.



# REST API Reference
Source: https://docs.playflowcloud.com/fundamentals/api

Authenticate, manage game servers, upload builds, and configure projects using the PlayFlow Cloud REST API.

The PlayFlow Cloud API gives you full programmatic control over your game server infrastructure. You can start and stop servers, upload and manage builds, configure project settings, and monitor server health -- all through standard HTTP requests.

The API is designed for consumption by game clients, backend services, CI/CD pipelines, and AI agents alike. Every endpoint returns predictable JSON with machine-readable status fields and clear error messages.

<Card title="Full OpenAPI Reference" icon="book-open" href="/api-reference/introduction">
  Explore the interactive API reference with schemas, parameters, and try-it-out functionality for every endpoint.
</Card>

## Prerequisites

Before you make your first request, make sure you have:

* A PlayFlow account with an organization and a project.
* An API key for that project (found under **Project Settings** in the dashboard). Use a **Server API Key** (`pf_*`) for backend and CI/CD calls, or a **Client API Key** (`pfclient_*`) for code that ships to players.
* A processed build (`status: ready`) if you plan to start servers -- see [Upload a Build](#upload-a-build).

<Info>
  Deleting builds and updating project settings require a **Server API Key**. A Client API Key receives a `403` on those operations.
</Info>

***

## Authentication

All API endpoints (except `/api/health`) require an API key passed via the `api-key` HTTP header.

```bash theme={null}
curl https://api.computeflow.cloud/api/v3/servers \
  -H "api-key: pf_your_server_api_key"
```

### API Key Types

PlayFlow projects have two API keys, each with a different access level:

| Key Type       | Prefix       | Access Level                   | Use Case                             |
| :------------- | :----------- | :----------------------------- | :----------------------------------- |
| Server API Key | `pf_*`       | Full read/write                | Backend services, CI/CD, admin tools |
| Client API Key | `pfclient_*` | Limited client-safe operations | Game clients, browser apps           |

<Info>
  You can find and regenerate your API keys in the [PlayFlow Dashboard](https://app.playflowcloud.com) under **Project Settings**.
</Info>

<Warning>
  Never expose your **Server API Key** in client-side code or public repositories. Use the **Client API Key** for any code that ships to players.
</Warning>

***

## Base URL

All API requests are made to:

```
https://api.computeflow.cloud/api
```

The canonical API version is **v3**. A v2 compatibility layer is available for legacy SDKs but all new integrations should target v3.

| Version        | Path Prefix | Notes                                              |
| :------------- | :---------- | :------------------------------------------------- |
| V3 (canonical) | `/api/v3/*` | Zod-validated, OpenAPI spec, clean response shapes |
| V2 (legacy)    | `/api/v2/*` | Compatibility layer for older SDKs                 |

***

## Endpoints Overview

### Servers

Manage the full lifecycle of your game servers -- create, inspect, update, restart, and stop.

| Method   | Endpoint                           | Description                       |
| :------- | :--------------------------------- | :-------------------------------- |
| `GET`    | `/v3/servers`                      | List servers for your project     |
| `POST`   | `/v3/servers/start`                | Launch a new game server          |
| `GET`    | `/v3/servers/:instance_id`         | Get details for a specific server |
| `POST`   | `/v3/servers/:instance_id/update`  | Update a server's `custom_data`   |
| `DELETE` | `/v3/servers/:instance_id`         | Stop a running server             |
| `POST`   | `/v3/servers/:instance_id/restart` | Restart a server                  |
| `GET`    | `/v3/servers/:instance_id/logs`    | Retrieve server logs              |
| `GET`    | `/v3/servers/:instance_id/metrics` | Retrieve server resource metrics  |

### Builds

Upload game server binaries and manage the build pipeline.

| Method   | Endpoint                    | Description                        |
| :------- | :-------------------------- | :--------------------------------- |
| `GET`    | `/v3/builds`                | List builds for your project       |
| `POST`   | `/v3/builds/upload-url`     | Get a presigned URL for ZIP upload |
| `POST`   | `/v3/builds/docker-image`   | Create a build from a Docker image |
| `GET`    | `/v3/builds/:build_id`      | Get build details                  |
| `DELETE` | `/v3/builds/:build_id`      | Soft-delete a build                |
| `GET`    | `/v3/builds/:build_id/logs` | Get build processing logs          |

### Projects

Read and update project-level configuration, and query logs across all servers.

| Method | Endpoint                | Description                   |
| :----- | :---------------------- | :---------------------------- |
| `GET`  | `/v3/projects/settings` | Get project configuration     |
| `POST` | `/v3/projects/settings` | Update project configuration  |
| `GET`  | `/v3/projects/logs`     | Query logs across all servers |

***

## Common Operations

### List Servers

Retrieve all running servers for your project. By default, only servers with status `running` are returned.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.computeflow.cloud/api/v3/servers?include_launching=true&limit=20" \
    -H "api-key: pf_your_server_api_key"
  ```

  ```csharp C# theme={null}
  using var client = new HttpClient();
  client.DefaultRequestHeaders.Add("api-key", "pf_your_server_api_key");

  var response = await client.GetAsync(
      "https://api.computeflow.cloud/api/v3/servers?include_launching=true&limit=20"
  );
  var json = await response.Content.ReadAsStringAsync();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.computeflow.cloud/api/v3/servers",
      headers={"api-key": "pf_your_server_api_key"},
      params={"include_launching": "true", "limit": 20},
  )
  data = response.json()
  ```
</CodeGroup>

**Query parameters:**

<ParamField type="boolean">
  Include servers that are still in the `launching` state.
</ParamField>

<ParamField type="boolean">
  Include pre-warmed pool servers in the results. Pre-warmed pooling is not currently enabled, so this filter returns nothing today; every server cold-starts on demand.
</ParamField>

<ParamField type="integer">
  Maximum number of servers to return (1-100).
</ParamField>

<ParamField type="integer">
  Number of servers to skip for pagination.
</ParamField>

**Response:**

```json theme={null}
{
  "total": 3,
  "total_servers": 3,
  "servers": [
    {
      "instance_id": "abc123",
      "name": "us-east-lobby-1",
      "status": "running",
      "region": "us-east",
      "compute_size": "small",
      "version_tag": "default",
      "version": 4,
      "network_ports": [
        {
          "name": "game",
          "internal_port": 7777,
          "external_port": 30412,
          "protocol": "udp",
          "host": "37.16.24.10",
          "tls_enabled": false
        }
      ],
      "started_at": "2026-03-15T10:30:00.000Z",
      "stopped_at": null,
      "custom_data": { "map": "arena_01" },
      "ttl": 3600,
      "is_pool_server": false,
      "match_id": null,
      "auto_restart": false,
      "created_at": "2026-03-15T10:29:55.000Z",
      "updated_at": "2026-03-15T10:30:00.000Z"
    }
  ],
  "limit": 50,
  "offset": 0,
  "has_more": false
}
```

***

### Start a Server

Launch a new game server instance. The server is provisioned immediately and moves through `launching` to `running` status.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.computeflow.cloud/api/v3/servers/start" \
    -H "api-key: pf_your_server_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "us-east-lobby-1",
      "region": "us-east",
      "compute_size": "small",
      "version_tag": "default",
      "ttl": 3600,
      "custom_data": {
        "map": "arena_01",
        "max_players": 16
      }
    }'
  ```

  ```csharp C# theme={null}
  using var client = new HttpClient();
  client.DefaultRequestHeaders.Add("api-key", "pf_your_server_api_key");

  var body = new StringContent(
      JsonSerializer.Serialize(new {
          name = "us-east-lobby-1",
          region = "us-east",
          compute_size = "small",
          version_tag = "default",
          ttl = 3600,
          custom_data = new { map = "arena_01", max_players = 16 }
      }),
      Encoding.UTF8,
      "application/json"
  );

  var response = await client.PostAsync(
      "https://api.computeflow.cloud/api/v3/servers/start", body
  );
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://api.computeflow.cloud/api/v3/servers/start",
      headers={
          "api-key": "pf_your_server_api_key",
          "Content-Type": "application/json",
      },
      json={
          "name": "us-east-lobby-1",
          "region": "us-east",
          "compute_size": "small",
          "version_tag": "default",
          "ttl": 3600,
          "custom_data": {"map": "arena_01", "max_players": 16},
      },
  )
  server = response.json()
  print(f"Instance ID: {server['instance_id']}")
  ```
</CodeGroup>

**Request body:**

<ParamField type="string">
  A display name for the server instance.
</ParamField>

<ParamField type="string">
  The deployment region. See [Server Regions](/fundamentals/regions) for the full list.
</ParamField>

<ParamField type="string">
  Server instance size. One of: `micro`, `small`, `medium`, `large`, `xlarge`, `dedicated-small`, `dedicated-medium`, `dedicated-large`, `dedicated-xlarge`. See [Pricing & Plan Types](/fundamentals/plan-instance-types) for specs.
</ParamField>

<ParamField type="string">
  The build name to deploy. Defaults to the latest build if not specified.
</ParamField>

<ParamField type="integer">
  A specific build version number. If omitted, the latest version for the given `version_tag` is used.
</ParamField>

<ParamField type="string">
  Command-line arguments passed to your game server executable on launch.
</ParamField>

<ParamField type="integer">
  Time-to-live in seconds (60-86400). The server automatically stops after this duration.
</ParamField>

<ParamField type="boolean">
  If `true`, the server restarts automatically if the game process exits.
</ParamField>

<ParamField type="object">
  Arbitrary key-value data attached to the server. Useful for passing map names, game modes, or match metadata to your game server at runtime.
</ParamField>

<ParamField type="string">
  An optional match identifier to associate this server with a specific match or lobby.
</ParamField>

<ParamField type="object">
  Key-value string pairs set as environment variables on the server instance.
</ParamField>

<ParamField type="array">
  Override the project-level port configuration for this server. Each entry specifies a `name`, `internal_port`, `protocol` (`udp` or `tcp`), and optional `tls_enabled` flag.
</ParamField>

**Response (201 Created):**

```json theme={null}
{
  "instance_id": "abc123",
  "name": "us-east-lobby-1",
  "status": "launching",
  "region": "us-east",
  "compute_size": "small",
  "version_tag": "default",
  "version": 4,
  "network_ports": [
    {
      "name": "game",
      "internal_port": 7777,
      "external_port": 30412,
      "protocol": "udp",
      "host": "37.16.24.10",
      "tls_enabled": false
    }
  ],
  "startup_args": null,
  "service_type": "match_based",
  "started_at": null,
  "stopped_at": null,
  "auto_restart": false,
  "custom_data": { "map": "arena_01", "max_players": 16 },
  "ttl": 3600,
  "is_pool_server": false,
  "pool_claimed_at": null,
  "match_id": null,
  "created_at": "2026-03-15T10:29:55.000Z",
  "updated_at": "2026-03-15T10:29:55.000Z"
}
```

<Info>
  The server starts in `launching` status. Once the game process is ready, the status changes to `running` and `started_at` is populated. You can poll `GET /v3/servers/:instance_id` or use `include_launching=true` when listing servers to track this transition.
</Info>

<Warning>
  Always read the connection host and port from `network_ports[]` in the live API response -- never hardcode them. The proxy allocates a fresh `external_port` per server (it is not the same as your `internal_port`, and it is not a fixed value like `7777`). TCP ports resolve through a relay hostname (`relay.computeflow.cloud`); UDP ports return a raw proxy IPv4 address. Read `host` + `external_port` together for each port your client needs.
</Warning>

***

### Stop a Server

Shut down a running server and release its resources.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X DELETE "https://api.computeflow.cloud/api/v3/servers/abc123" \
    -H "api-key: pf_your_server_api_key"
  ```

  ```python Python theme={null}
  response = requests.delete(
      "https://api.computeflow.cloud/api/v3/servers/abc123",
      headers={"api-key": "pf_your_server_api_key"},
  )
  ```
</CodeGroup>

**Query parameters:**

<ParamField type="string">
  An optional reason for stopping the server, recorded for logging purposes.
</ParamField>

**Response:**

The `status` field is a human-readable confirmation message, not a state enum -- do not branch on it matching `"stopped"`.

```json theme={null}
{
  "status": "Server stopped successfully"
}
```

***

### Upload a Build

Uploading a build is a two-step process: request a presigned upload URL, then upload your ZIP file. Processing starts automatically when the upload finishes.

<Steps>
  <Step title="Request an upload URL">
    Call the upload-url endpoint to get a presigned R2 URL and a `build_id`.

    The `executable_path` query parameter is optional. If omitted, PlayFlow runs `Server.x86_64` inside your ZIP. Set it when your server binary has a different name.

    ```bash theme={null}
    curl -X POST "https://api.computeflow.cloud/api/v3/builds/upload-url?name=default&executable_path=GameServer.x86_64" \
      -H "api-key: pf_your_server_api_key"
    ```

    **Response (201 Created):**

    ```json theme={null}
    {
      "build_id": "build_abc123",
      "name": "default",
      "upload_url": "https://r2.cloudflarestorage.com/...",
      "message": "Upload URL generated. PUT your ZIP to upload_url within 60 minutes."
    }
    ```

    The presigned `upload_url` expires 60 minutes after it is issued.
  </Step>

  <Step title="Upload your ZIP file">
    Use the presigned URL to upload your game server build as a ZIP archive. Processing begins automatically once the upload completes.

    ```bash theme={null}
    curl -X PUT "https://r2.cloudflarestorage.com/..." \
      -H "Content-Type: application/zip" \
      --data-binary @my-game-server.zip
    ```
  </Step>

  <Step title="Poll for status">
    Poll `GET /v3/builds/{build_id}` until `status` is `ready` (or `failed`).

    ```bash theme={null}
    curl "https://api.computeflow.cloud/api/v3/builds/build_abc123" \
      -H "api-key: pf_your_server_api_key"
    ```
  </Step>
</Steps>

You can track build progress by polling `GET /v3/builds/:build_id` or by streaming build logs from `GET /v3/builds/:build_id/logs`.

***

### Create a Build from Docker Image

If you already have a containerized game server, you can create a build directly from a Docker image instead of uploading a ZIP.

```bash theme={null}
curl -X POST "https://api.computeflow.cloud/api/v3/builds/docker-image" \
  -H "api-key: pf_your_server_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "default",
    "image_url": "ghcr.io/my-org/game-server:latest",
    "executable_path": "/app/GameServer",
    "registry_credentials": {
      "username": "my-user",
      "password": "my-token"
    }
  }'
```

<ParamField type="string">
  The build name (used as the `version_tag` when starting servers).
</ParamField>

<ParamField type="string">
  The full Docker image URL including tag.
</ParamField>

<ParamField type="string">
  Path to the game server executable inside the container.
</ParamField>

<ParamField type="object">
  Credentials for private registries. Include `username` and `password` fields.
</ParamField>

***

## Response Shapes

### Server Object

Every server endpoint returns or includes the following shape:

<Expandable title="Server response fields">
  <ResponseField name="instance_id" type="string">
    Unique identifier for the server instance.
  </ResponseField>

  <ResponseField name="name" type="string">
    Display name of the server.
  </ResponseField>

  <ResponseField name="status" type="string">
    Current server state: `launching`, `running`, or `stopped`.
  </ResponseField>

  <ResponseField name="network_ports" type="array">
    List of port mappings. Each entry contains `name`, `internal_port`, `external_port`, `protocol`, `host`, and `tls_enabled`.
  </ResponseField>

  <ResponseField name="startup_args" type="string | null">
    Command-line arguments passed to the game server.
  </ResponseField>

  <ResponseField name="service_type" type="string">
    Either `match_based` or `persistent_world`.
  </ResponseField>

  <ResponseField name="compute_size" type="string">
    Instance size (e.g., `small`, `large`, `dedicated-medium`).
  </ResponseField>

  <ResponseField name="region" type="string">
    Deployment region identifier.
  </ResponseField>

  <ResponseField name="version_tag" type="string">
    The build name deployed on this server.
  </ResponseField>

  <ResponseField name="version" type="integer | null">
    The build version number, if applicable.
  </ResponseField>

  <ResponseField name="started_at" type="string | null">
    ISO 8601 timestamp when the server became `running`. Null while `launching`.
  </ResponseField>

  <ResponseField name="stopped_at" type="string | null">
    ISO 8601 timestamp when the server was stopped.
  </ResponseField>

  <ResponseField name="auto_restart" type="boolean">
    Whether the server restarts automatically on process exit.
  </ResponseField>

  <ResponseField name="custom_data" type="object | null">
    Arbitrary metadata attached to the server.
  </ResponseField>

  <ResponseField name="ttl" type="integer | null">
    Time-to-live in seconds, if set.
  </ResponseField>

  <ResponseField name="is_pool_server" type="boolean">
    Whether this server was provisioned from the pre-warmed pool. Pre-warmed pooling is not currently enabled, so this is always `false` today.
  </ResponseField>

  <ResponseField name="pool_claimed_at" type="string | null">
    ISO 8601 timestamp when a pool server was claimed. Always `null` while pooling is disabled.
  </ResponseField>

  <ResponseField name="match_id" type="string | null">
    Associated match or lobby identifier.
  </ResponseField>

  <ResponseField name="created_at" type="string">
    ISO 8601 timestamp when the instance record was created.
  </ResponseField>

  <ResponseField name="updated_at" type="string">
    ISO 8601 timestamp of the last update.
  </ResponseField>
</Expandable>

### Build Object

<Expandable title="Build response fields">
  <ResponseField name="build_id" type="string">
    Unique identifier for the build.
  </ResponseField>

  <ResponseField name="name" type="string">
    Build name, used as the `version_tag` when starting servers.
  </ResponseField>

  <ResponseField name="version" type="integer">
    Auto-incremented version number within this build name.
  </ResponseField>

  <ResponseField name="status" type="string">
    Build state: `uploading`, `processing`, `ready`, `failed`, or `deleted`.
  </ResponseField>

  <ResponseField name="build_type" type="string">
    Either `zip` (uploaded archive) or `docker_image`.
  </ResponseField>

  <ResponseField name="executable_path" type="string | null">
    Path to the game server executable.
  </ResponseField>

  <ResponseField name="image_url" type="string | null">
    Docker image URL, if the build was created from a container image.
  </ResponseField>

  <ResponseField name="created_at" type="string">
    ISO 8601 timestamp when the build was created.
  </ResponseField>

  <ResponseField name="updated_at" type="string | null">
    ISO 8601 timestamp of the last update.
  </ResponseField>
</Expandable>

***

## Server Logs and Metrics

### Server Logs

Retrieve stdout/stderr logs from a running or recently stopped server.

```bash theme={null}
curl "https://api.computeflow.cloud/api/v3/servers/abc123/logs?limit=100" \
  -H "api-key: pf_your_server_api_key"
```

<ParamField type="string">
  ISO 8601 timestamp to begin retrieving logs from.
</ParamField>

<ParamField type="string">
  ISO 8601 timestamp to stop retrieving logs at.
</ParamField>

<ParamField type="string">
  Filter to log lines containing this substring.
</ParamField>

<ParamField type="string">
  Filter by log level (e.g. `info`, `warn`, `error`).
</ParamField>

<ParamField type="integer">
  Number of log entries to return (1-1000).
</ParamField>

**Response:**

```json theme={null}
{
  "logs": [
    {
      "timestamp": "2026-03-15T10:30:05.123Z",
      "message": "Server started on port 7777",
      "level": "info",
      "instance": "abc123",
      "region": "us-east"
    }
  ],
  "instance_id": "abc123",
  "machine_id": "fly-machine-id",
  "next_token": null,
  "older_token": null
}
```

### Server Metrics

Retrieve CPU, memory, network, and connection metrics for a running server.

```bash theme={null}
curl "https://api.computeflow.cloud/api/v3/servers/abc123/metrics?period=1h&step=60s" \
  -H "api-key: pf_your_server_api_key"
```

<ParamField type="string">
  Time window for metrics. One of: `5m`, `15m`, `1h`, `6h`, `24h`.
</ParamField>

<ParamField type="string">
  Resolution between data points. One of: `15s`, `30s`, `60s`, `300s`.
</ParamField>

**Response:**

```json theme={null}
{
  "instance_id": "abc123",
  "machine_id": "fly-machine-id",
  "region": "us-east",
  "period": {
    "start": 1742036400,
    "end": 1742040000,
    "step": "60s"
  },
  "cpu": {
    "usage_percent": [{ "t": 1742036400, "v": 12.5 }]
  },
  "memory": {
    "used_mb": [{ "t": 1742036400, "v": 256 }],
    "total_mb": 1024
  },
  "network": {
    "rx_bytes_per_sec": [{ "t": 1742036400, "v": 1024 }],
    "tx_bytes_per_sec": [{ "t": 1742036400, "v": 2048 }]
  },
  "load": {
    "average_1m": [{ "t": 1742036400, "v": 0.5 }]
  },
  "connections": {
    "tcp": [{ "t": 1742036400, "v": 8 }]
  }
}
```

***

## Error Handling

All error responses share a consistent JSON structure:

```json theme={null}
{
  "error": "Human-readable error message",
  "detail": "Same as error (for legacy SDK compatibility)",
  "status": 400
}
```

### Common Status Codes

| Status | Meaning                                                              |
| :----- | :------------------------------------------------------------------- |
| `200`  | Success                                                              |
| `201`  | Resource created (server started, upload URL generated)              |
| `202`  | Accepted (build processing triggered)                                |
| `401`  | Missing or invalid `api-key` header                                  |
| `404`  | Server, build, or resource not found                                 |
| `422`  | Validation error (malformed request body or missing required fields) |
| `429`  | Rate limit exceeded                                                  |
| `500`  | Internal server error                                                |

### Validation Errors

When request validation fails, the response includes structured error details:

```json theme={null}
{
  "error": "Validation error",
  "detail": [
    {
      "loc": ["region"],
      "msg": "Required",
      "type": "invalid_type"
    }
  ],
  "status": 422
}
```

***

## Rate Limiting

The API uses token-bucket rate limiting per API key. Rate limit status is returned in response headers.

| Endpoint Type                                | Limit               |
| :------------------------------------------- | :------------------ |
| Read endpoints (list, get, logs, metrics)    | 100 requests/second |
| Write endpoints (start server, upload build) | 10 requests/second  |

**Response headers:**

| Header                  | Description                        |
| :---------------------- | :--------------------------------- |
| `X-RateLimit-Limit`     | Maximum tokens in the bucket       |
| `X-RateLimit-Remaining` | Tokens remaining before throttling |

When the rate limit is exceeded, you receive a `429` response:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "detail": "Rate limit exceeded. Please retry after a short wait.",
  "status": 429
}
```

***

## Regions

Deploy your servers across 13 global regions for low-latency gameplay. Pass any of these region IDs to the `region` field when starting a server.

| Region                     | ID                     |
| :------------------------- | :--------------------- |
| US East                    | `us-east`              |
| US South (Dallas)          | `us-south`             |
| US West                    | `us-west`              |
| Europe North (Sweden)      | `eu-north`             |
| Europe West (Germany)      | `eu-west`              |
| Europe (United Kingdom)    | `eu-uk`                |
| Asia South (India)         | `ap-south`             |
| Southeast Asia (Singapore) | `sea`                  |
| Asia North (Japan)         | `ap-north`             |
| Australia                  | `ap-southeast`         |
| South Africa               | `south-africa`         |
| South America (Brazil)     | `south-america-brazil` |
| South America (Chile)      | `south-america-chile`  |

See [Server Regions](/fundamentals/regions) for the full details on each region.

***

## SDK and Tooling

<CardGroup>
  <Card title="Unity SDK" icon="gamepad" href="/unity/programmatic-access">
    Use the PlayFlow Unity SDK for C# wrappers around the REST API, including server management from your game client.
  </Card>

  <Card title="Interactive API Reference" icon="flask-vial" href="/api-reference/introduction">
    Explore every endpoint with the full OpenAPI specification, request/response schemas, and a try-it-out console.
  </Card>
</CardGroup>


# Pricing & Plan Types
Source: https://docs.playflowcloud.com/fundamentals/plan-instance-types

Explore PlayFlow Cloud's flexible and transparent pricing for game server instances.

<Frame>
  <div>
    <h2>Flexible, Transparent Game Server Pricing</h2>

    <p>
      PlayFlow Cloud offers usage-based billing with no long-term commitments.
      Only pay for the compute time your servers actually run.
    </p>
  </div>
</Frame>

## Instance Types & Pricing

PlayFlow Cloud offers a comprehensive range of server options to power your game's multiplayer infrastructure:

* **Standard Instances** - Efficient shared CPU resources with quick deployment. Optimized for development environments, testing, and games with variable player loads. Provides an excellent balance of performance and cost-effectiveness.

* **Dedicated Instances** - Guaranteed CPU resources that deliver consistent performance. Ideal for production environments where reliable, predictable performance is critical for player experience. Ensures stability during high-demand periods.

<Tabs>
  <Tab title="All Instances">
    <div>
      <p>Our complete range of game server instances, from low-cost development options to high-performance dedicated resources.</p>

      | Instance Type      | CPU Type  | vCPU | RAM   | Price (USD/hr) |
      | :----------------- | :-------- | :--- | :---- | :------------- |
      | `micro`            | Standard  | 1    | 512MB | \$0.01         |
      | `small`            | Standard  | 1    | 1GB   | \$0.02         |
      | `medium`           | Standard  | 1    | 2GB   | \$0.04         |
      | `large`            | Standard  | 2    | 4GB   | \$0.06         |
      | `xlarge`           | Standard  | 4    | 8GB   | \$0.12         |
      | `dedicated-small`  | Dedicated | 1    | 2GB   | \$0.07         |
      | `dedicated-medium` | Dedicated | 1    | 4GB   | \$0.09         |
      | `dedicated-large`  | Dedicated | 1    | 8GB   | \$0.13         |
      | `dedicated-xlarge` | Dedicated | 2    | 16GB  | \$0.26         |

      <Info>
        `small` is the default compute size if you don't pass `compute_size` when starting a server. Standard instances use shared vCPU; dedicated instances use performance (dedicated) vCPU.
      </Info>
    </div>
  </Tab>

  <Tab title="Standard Instances">
    <div>
      <p>Standard instances use shared CPU resources and are ideal for development, testing, and games with moderate performance requirements.</p>

      | Instance Type | vCPU | RAM   | Price (USD/hr) |
      | :------------ | :--- | :---- | :------------- |
      | `micro`       | 1    | 512MB | \$0.01         |
      | `small`       | 1    | 1GB   | \$0.02         |
      | `medium`      | 1    | 2GB   | \$0.04         |
      | `large`       | 2    | 4GB   | \$0.06         |
      | `xlarge`      | 4    | 8GB   | \$0.12         |
    </div>
  </Tab>

  <Tab title="Dedicated Instances">
    <div>
      <p>Dedicated instances provide guaranteed CPU resources, ensuring consistent performance for production games and demanding workloads.</p>

      | Instance Type      | vCPU | RAM  | Price (USD/hr) |
      | :----------------- | :--- | :--- | :------------- |
      | `dedicated-small`  | 1    | 2GB  | \$0.07         |
      | `dedicated-medium` | 1    | 4GB  | \$0.09         |
      | `dedicated-large`  | 1    | 8GB  | \$0.13         |
      | `dedicated-xlarge` | 2    | 16GB | \$0.26         |
    </div>
  </Tab>
</Tabs>

## Plans

Every new organization starts on the **Free** plan. Upgrade to **Pro** when you need more concurrent servers, longer-running sessions, or access to every compute size.

<CardGroup>
  <Card title="Free" icon="rocket">
    Best for prototyping and testing.

    * **1** active server at a time
    * Forced `small` compute size
    * Forced **1 hour** TTL (server auto-stops after 3600s)
    * No compute billing — you're never charged
    * No credit card required
  </Card>

  <Card title="Pro — $20/mo" icon="crown">
    Best for launching and scaling a live game.

    * **Unlimited** active servers
    * Every compute size (`micro` through `dedicated-xlarge`)
    * TTL up to **24 hours** (86400s)
    * Usage-metered compute billing at the per-hour rates above, on top of the \$20/mo base
  </Card>
</CardGroup>

<Info>
  The per-hour instance rates in the tables above apply to metered compute on the Pro plan. Free-plan servers run the `small` size at no charge.
</Info>

## Key Features

<Steps>
  <Step title="Usage-Based Billing">
    Pay only for the compute time your servers run, metered proportionally to runtime. No flat monthly server fees.
  </Step>

  <Step title="No Hidden Fees">
    Transparent pricing with no surprise charges. Unlimited data transfer included with all plans.
  </Step>

  <Step title="On-Demand Servers">
    Launch servers when you need them through the dashboard or API. Servers start on demand and are billed only while they run.
  </Step>

  <Step title="Global Deployment">
    Deploy your game servers across 13 regions worldwide to reduce latency for all your players. A `region` is required when you start a server.
  </Step>

  <Step title="Free Development Tier">
    Get started for free with 1 active server, a forced `small` size, and a 1-hour TTL — no credit card and no compute charges.
  </Step>
</Steps>

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="How does usage-based billing work?">
    <p>PlayFlow Cloud meters your server usage while each server is running. When you start a server, we begin counting its runtime and stop when the server is terminated (or auto-stops at its TTL). Usage is billed proportionally to runtime at the per-hour rate for the compute size, and totals accrue over your billing cycle. Free-plan servers are never charged.</p>
  </Accordion>

  <Accordion title="Is there a minimum usage time?">
    <p>There is no minimum usage requirement or contract. Compute is billed proportionally to how long your server runs (fractional-hour windows at the per-hour rate), so a server that runs for a few minutes costs only a small fraction of its hourly price. Very short sessions may be absorbed rather than metered.</p>
  </Accordion>

  <Accordion title="Are there any long-term commitments?">
    <p>No, PlayFlow Cloud is entirely pay-as-you-go. There are no contracts, minimum spending requirements, or termination fees. You can start or stop using our services at any time without penalty.</p>
  </Accordion>

  <Accordion title="Is data transfer included?">
    <p>Yes! All PlayFlow plans include unlimited data transfer at no extra cost. You'll never be charged for bandwidth — only for the compute time your servers are running. A soft fair-use limit applies to prevent abuse, but it's more than enough for the vast majority of games.</p>
  </Accordion>

  <Accordion title="Do you offer custom plans for large-scale deployments?">
    <p>Yes, for large-scale deployments or games with specific requirements, please contact our sales team to discuss custom plans and potential volume discounts. We can tailor solutions for studios of any size and games of any scale.</p>
    <p>Reach out via our <a href="https://discord.gg/P5w45Vx5Q8">Discord community</a> or through the support options in your dashboard.</p>
  </Accordion>
</AccordionGroup>

<div>
  <a href="https://app.playflowcloud.com">
    <span>Deploy Your Game Server Now</span>

    <svg>
      <path />
    </svg>
  </a>
</div>


# Server Regions
Source: https://docs.playflowcloud.com/fundamentals/regions

Deploy your game servers across the globe to ensure the lowest latency for your players.

PlayFlow operates a global network of data centers, allowing you to deploy your dedicated servers as close to your players as possible. Choosing the right region is the most effective way to reduce latency and provide a smooth gameplay experience.

The `region` field is **required** when you start a server. You select it when launching a new server via the dashboard or through the [Game Servers API](/unity/game-servers).

## Available Regions

Below is the full list of currently supported deployment regions.

| Region Name                | Region ID              | Location             | Flag |
| :------------------------- | :--------------------- | :------------------- | :--: |
| North America (US East)    | `us-east`              | Secaucus, New Jersey | 🇺🇸 |
| North America (US Central) | `us-south`             | Dallas, Texas        | 🇺🇸 |
| North America (US West)    | `us-west`              | Los Angeles          | 🇺🇸 |
| Europe (Sweden)            | `eu-north`             | Stockholm            | 🇸🇪 |
| Europe (Germany)           | `eu-west`              | Frankfurt            | 🇩🇪 |
| Europe (United Kingdom)    | `eu-uk`                | London               | 🇬🇧 |
| Asia (India)               | `ap-south`             | Mumbai               | 🇮🇳 |
| Asia (Singapore)           | `sea`                  | Singapore            | 🇸🇬 |
| Asia (Japan)               | `ap-north`             | Tokyo                | 🇯🇵 |
| Australia                  | `ap-southeast`         | Sydney               | 🇦🇺 |
| Africa (South Africa)      | `south-africa`         | Johannesburg         | 🇿🇦 |
| South America (Brazil)     | `south-america-brazil` | São Paulo            | 🇧🇷 |
| South America (Chile)      | `south-america-chile`  | São Paulo (nearest)  | 🇨🇱 |

<Info>
  Region IDs are case-insensitive — pass the exact `Region ID` value shown above (lowercase) when you start a server.
</Info>


# Docker Image Builds
Source: https://docs.playflowcloud.com/guides/docker-builds

Deploy game servers from your own Docker images.

# Docker Image Builds

PlayFlow supports two ways to deploy your game server: uploading a ZIP of your server build, or importing a pre-built Docker image. This guide covers the Docker image approach, which gives you full control over your server environment and enables tighter CI/CD integration.

## How It Works

When you import a Docker image, PlayFlow pulls it from your container registry and makes it available for server launches. Servers started from a Docker image build skip the ZIP download and extraction step entirely -- the image is ready to run immediately.

<Info>
  Docker image builds are ideal for teams that already have a containerized build pipeline. If you are new to containers or prefer a simpler workflow, the [ZIP upload method](/unity/game-servers) handles containerization for you automatically.
</Info>

## Prerequisites

Before you begin, make sure you have:

* A PlayFlow project with a **server API key** (the `pf_`-prefixed key from **Project Settings** on the dashboard). Keep it server-side — in CI, store it as a secret. Client keys (`pfclient_`) are meant for game builds and cannot manage builds.
* A Docker image pushed to an accessible container registry (Docker Hub, GitHub Container Registry, AWS ECR, etc.)
* If your registry is private, the credentials to pull the image

## Importing a Docker Image

<Steps>
  <Step title="Push your image to a container registry">
    Build and push your game server image to any Docker-compatible registry. Make sure the image contains everything your server needs to run.

    ```bash theme={null}
    docker build -t registry.example.com/my-game-server:v1.0 .
    docker push registry.example.com/my-game-server:v1.0
    ```
  </Step>

  <Step title="Import the image into PlayFlow">
    Call the Docker image import endpoint with your image URL and, optionally, registry credentials and an executable path.

    <CodeGroup>
      ```bash curl (public registry) theme={null}
      curl -X POST https://api.computeflow.cloud/api/v3/builds/docker-image \
        -H "api-key: YOUR_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "my-server-build",
          "image_url": "registry.example.com/my-game-server:v1.0"
        }'
      ```

      ```bash curl (private registry) theme={null}
      curl -X POST https://api.computeflow.cloud/api/v3/builds/docker-image \
        -H "api-key: YOUR_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "my-server-build",
          "image_url": "registry.example.com/my-game-server:v1.0",
          "executable_path": "/app/server",
          "registry_credentials": {
            "username": "your-username",
            "password": "your-access-token"
          }
        }'
      ```
    </CodeGroup>
  </Step>

  <Step title="Wait for processing to complete">
    The build is created with status `processing`. PlayFlow pulls the image and prepares it for server launches. You can poll the build status endpoint or watch for updates on the dashboard.

    ```bash theme={null}
    curl https://api.computeflow.cloud/api/v3/builds/BUILD_ID \
      -H "api-key: YOUR_API_KEY"
    ```

    When processing finishes, the status changes to `ready`.
  </Step>

  <Step title="Launch a server from the build">
    Once the build is ready, start a server using it just like any other build. PlayFlow uses the Docker image directly -- no ZIP download or extraction required.

    You reference a build **by the name you gave it at import**, not by its ID. Pass that name as `version_tag`, and always include a `name` and `region` (both required):

    ```bash theme={null}
    curl -X POST https://api.computeflow.cloud/api/v3/servers/start \
      -H "api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "my-match-1",
        "region": "us-east",
        "version_tag": "my-server-build"
      }'
    ```

    <Info>
      `version_tag` is the build name you chose when importing (here, `my-server-build`) — PlayFlow launches the latest `ready` build with that name. To pin an exact build version, also pass `version` (a number). The `BUILD_ID` you polled in the previous step is only for checking build status; it is not used to launch a server.
    </Info>

    <Tip>
      Read the connection host and port from the `network_ports[]` array in the start response (each entry has `host` and `external_port`) rather than assuming a fixed port — PlayFlow allocates the external port dynamically, and it differs from your internal port.
    </Tip>
  </Step>
</Steps>

## Request Body Reference

| Field                           | Type   | Required                      | Description                                                                                                                                              |
| :------------------------------ | :----- | :---------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                          | string | No (defaults to `"default"`)  | The name for this build — this is what you pass as `version_tag` when launching a server. Builds with the same name auto-increment their version number. |
| `image_url`                     | string | Yes                           | The full image URL including tag (e.g., `registry.example.com/my-server:v1.0`).                                                                          |
| `executable_path`               | string | No                            | The path to the server executable inside the container. Only needed if it cannot be inferred automatically.                                              |
| `registry_credentials`          | object | No                            | Credentials for pulling from a private registry.                                                                                                         |
| `registry_credentials.username` | string | Yes (if credentials provided) | Registry username or service account name.                                                                                                               |
| `registry_credentials.password` | string | Yes (if credentials provided) | Registry password, access token, or personal access token.                                                                                               |

## Docker Image vs. ZIP Upload

<Tabs>
  <Tab title="Docker Image">
    **Best for:** advanced users, custom runtimes, CI/CD pipelines, non-standard server setups.

    * You build and manage the Docker image yourself
    * Full control over the base image, dependencies, and runtime environment
    * Faster server startup since the image is pre-built
    * Integrates naturally with CI/CD -- push to your registry, then import to PlayFlow
    * Supports any language, framework, or game engine
  </Tab>

  <Tab title="ZIP Upload">
    **Best for:** simple deployments, Unity/Godot builds, getting started quickly.

    * Upload a ZIP of your server binary and PlayFlow handles containerization
    * No Docker knowledge required
    * Great for standard Unity or Godot dedicated server builds
    * PlayFlow manages the image build and optimization
  </Tab>
</Tabs>

## CI/CD Integration

Docker image builds fit naturally into automated pipelines. Here is an example GitHub Actions workflow that builds your server image, pushes it to a registry, and imports it into PlayFlow:

```yaml github-actions.yml theme={null}
name: Deploy Game Server
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Build and push Docker image
        run: |
          docker build -t ghcr.io/${{ github.repository }}/server:${{ github.sha }} .
          echo "${{ secrets.GHCR_TOKEN }}" | docker login ghcr.io -u ${{ github.actor }} --password-stdin
          docker push ghcr.io/${{ github.repository }}/server:${{ github.sha }}

      - name: Import to PlayFlow
        run: |
          curl -X POST https://api.computeflow.cloud/api/v3/builds/docker-image \
            -H "api-key: ${{ secrets.PLAYFLOW_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{
              "name": "production-server",
              "image_url": "ghcr.io/${{ github.repository }}/server:${{ github.sha }}",
              "registry_credentials": {
                "username": "${{ github.actor }}",
                "password": "${{ secrets.GHCR_TOKEN }}"
              }
            }'
```

## Tips

<Warning>
  Always use a specific image tag (e.g., `:v1.0` or a commit SHA) rather than `:latest`. This ensures that your servers run the exact version you tested, and makes rollbacks straightforward.
</Warning>

* **Keep images small.** Smaller images pull faster, which reduces build processing time. Use multi-stage builds and minimal base images (e.g., `debian-slim`, `alpine`) where possible.
* **Signal readiness from your server.** PlayFlow does not probe a custom health endpoint in your game. Server readiness is reported by the PlayFlow agent sidecar via a status callback once your game process is up, so make sure your server starts and binds its ports promptly.
* **Test locally first.** Run your image with `docker run` before importing to PlayFlow to catch configuration issues early.

***

## Next Steps

<CardGroup>
  <Card title="Server Regions" icon="globe" href="/fundamentals/regions">
    Choose the best deployment region for your players.
  </Card>

  <Card title="Pricing & Instance Types" icon="credit-card" href="/fundamentals/plan-instance-types">
    Review available compute sizes and pricing.
  </Card>
</CardGroup>


# EOS Lobby Integration
Source: https://docs.playflowcloud.com/guides/eos-lobby-integration

Use Epic Online Services (EOS) lobbies for grouping and identity, and launch the match server on PlayFlow when the lobby owner starts the game.

This guide shows you how to pair **Epic Online Services (EOS) lobbies** with PlayFlow game-server hosting. Players group up in an EOS lobby; when the lobby owner starts the match, a dedicated server is launched on PlayFlow and its address is shared back through **EOS Lobby Properties** so everyone can connect.

The PlayFlow side is a handful of REST calls, so this works with any engine — Unreal, Unity, or custom — that can call the EOS lobby APIs and make HTTP requests.

<Warning>
  **Never ship a PlayFlow server key (`pf_...`) inside a game client.** A client holding it could start unlimited servers on your account. Route the "start the server" call through a **trusted service you control** (your backend, or a serverless function). See [Keeping the API key safe](#keeping-the-api-key-safe) below for the exact options PlayFlow gives you.
</Warning>

Before getting started, we expect that:

* You have a working EOS lobby flow (players can create/join a lobby and read [lobby & member properties](https://dev.epicgames.com/docs/game-services/lobbies)).
* You have a PlayFlow project and an uploaded **dedicated Linux server build**. See [Docker builds](/guides/docker-builds).

## How it works

```mermaid theme={null}
sequenceDiagram
    participant O as Lobby Owner (client)
    participant SV as Your trusted service
    participant PL as PlayFlow API
    participant M as Lobby Members (EOS)

    O->>SV: "Start match" (lobby id, region)
    SV->>PL: POST /v3/servers/start
    PL-->>SV: instance_id + network_ports (status: launching)
    SV->>PL: Poll GET /v3/servers/{id} until status = running
    SV->>M: Set host:port as EOS Lobby Properties
    M->>PL: Connect to server
    Note over O,SV: Match ends
    SV->>M: Unset EOS Lobby Properties
    SV->>PL: DELETE /v3/servers/{id}
```

## Step 1 — Choose a region

Edgegap places servers from a list of player IPs. **PlayFlow instead takes an explicit `region`** (one of [13 regions](/fundamentals/regions)) — there is no IP-based auto-placement. Pick one of these approaches:

* **Simple:** use a fixed region per lobby (for example, a region the players chose in a menu).
* **Geo-aware:** have each member store a coarse location (from their platform or a client-side lookup) as an EOS **member property**, then have your service average them and pick the nearest PlayFlow region. The nearest-region helper from the [PlayFab Bridge guide](/guides/playfab-bridge) works unchanged here.

<Info>
  `region` is **required** on `POST /v3/servers/start`. If you can't determine a good region, default to the one closest to most of your player base.
</Info>

## Step 2 — Start the server when the owner starts the match

When the lobby owner decides the match is ready, your trusted service starts a PlayFlow server. PlayFlow allocates the network ports up front, so the response already contains the address — you just have to wait for the server to finish booting before handing it out.

```bash Start the server theme={null}
curl -X POST "https://api.computeflow.cloud/api/v3/servers/start" \
  -H "api-key: pf_your_server_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lobby-<EOS_LOBBY_ID>",
    "region": "us-east",
    "version_tag": "your-build-name",
    "ttl": 3600,
    "environment_variables": {
      "EOS_LOBBY_ID": "<EOS_LOBBY_ID>"
    }
  }'
```

```json Response (abridged) theme={null}
{
  "instance_id": "a1b2c3d4-...",
  "status": "launching",
  "region": "us-east",
  "network_ports": [
    {
      "name": "game",
      "internal_port": 7777,
      "external_port": 30412,
      "protocol": "udp",
      "host": "203.0.113.10",
      "tls_enabled": false
    }
  ]
}
```

<Tip>
  Pass a `ttl` (seconds) as a safety net so an abandoned lobby can't leave a server running forever. `version_tag` is the **name** of the build you uploaded to PlayFlow.
</Tip>

## Step 3 — Wait for `running`, then publish the address

The server starts as `launching`. Poll its status until it reports `running` — that's your "ready" signal — then read the address for your named port from `network_ports` and store it as EOS Lobby Properties.

```bash Poll until ready theme={null}
curl "https://api.computeflow.cloud/api/v3/servers/a1b2c3d4-..." \
  -H "api-key: pf_your_server_key"
# repeat every ~2s until "status": "running"
```

From the port named `game`, take `host` and `external_port` and set them as EOS Lobby Properties (for example `SERVER_HOST` and `SERVER_PORT`). EOS notifies every member of the property change.

<Info>
  For **UDP** ports (most game netcode), `host` is a proxy IP and `external_port` is the allocated port. For **TCP** ports, `host` is a PlayFlow relay hostname. Always read both from the response — never hardcode a port; it is allocated per server.
</Info>

## Step 4 — Members connect

When members receive the EOS property-changed notification for `SERVER_HOST` / `SERVER_PORT`, they connect their netcode transport to that address and join the match. Because you only publish the address once the server is `running`, members never receive a dead endpoint.

## Step 5 — End the match (and rematch)

When the match is over, your service clears the EOS Lobby Properties (signalling everyone to disconnect gracefully) and terminates the PlayFlow server:

```bash Terminate the server theme={null}
curl -X DELETE "https://api.computeflow.cloud/api/v3/servers/a1b2c3d4-...?shutdown_reason=MATCH_ENDED" \
  -H "api-key: pf_your_server_key"
```

If the players stay in the lobby, repeat from **Step 2** to run a rematch with the same group. You can also let the server terminate itself — every PlayFlow server is handed `PLAYFLOW_API_KEY`, `PLAYFLOW_API_URL`, and `PLAYFLOW_INSTANCE_ID`, so it can call `DELETE /v3/servers/$PLAYFLOW_INSTANCE_ID` when the last player leaves.

## Keeping the API key safe

The security concern is the same as any host: a client that can start servers can be abused. PlayFlow gives you two key types:

| Key            | Prefix      | Use                                                                                                               |
| -------------- | ----------- | ----------------------------------------------------------------------------------------------------------------- |
| **Server key** | `pf_`       | Full access. Keep it **only** in a trusted server-side context (your service).                                    |
| **Client key** | `pfclient_` | Safe to ship in clients. Can use player-facing lobby/read endpoints; **cannot** touch project settings or builds. |

By default a client key *can* start/stop servers. If you want a trusted service to be the **only** thing that can launch servers, set `client_key_server_control` to `false` in your project settings — server lifecycle calls then require a server key, closing the door on client-triggered starts entirely.

**Recommended:** the lobby owner's client asks your trusted service to start the match; the service holds the server key and makes the PlayFlow calls. The client never sees `pf_...`.

<Info>
  Prefer not to run your own service? PlayFlow's [native lobbies and matchmaking](/lobbies/overview) launch the server for you and deliver connection details over a real-time channel — no external key handling required.
</Info>


# Quick Start - Godot Multiplayer
Source: https://docs.playflowcloud.com/guides/godot-first-multiplayer-game

Step-by-step tutorial for creating your first multiplayer game in Godot with PlayFlow Cloud

# Creating Your First Multiplayer Game in Godot

This comprehensive guide shows you how to create a simple multiplayer game from scratch in Godot that connects to a dedicated server hosted on PlayFlow Cloud. This setup is compatible with both web and desktop platforms using TCP + TLS ("wss" protocol).

<Info>
  **Godot 4.x** - This guide uses Godot 4.4, but any 4.x version should work. We'll be using the Compatibility renderer for web platform support.
</Info>

<Card title="Complete Project" icon="download" href="https://github.com/Xaimelee/playflow-quick-start-guide">
  Download the complete project files from GitHub (community-maintained sample)
</Card>

## What You'll Build

By the end of this tutorial, you'll have:

* A 3D multiplayer game with player movement
* Connection UI for server details
* WebSocket networking with TLS support
* Multiplayer synchronization using Godot's built-in systems
* A working dedicated server setup on PlayFlow

## Before We Begin

<Steps>
  <Step title="Create New Project">
    Create a new Godot project and select the **Compatibility** renderer. This ensures web platform compatibility.
  </Step>

  <Step title="Set Up Main Scene">
    Create a new scene, save it as "main.tscn" and select **3D Scene** as the root type. Right-click the file after saving and select **Set as Main Scene**.
  </Step>
</Steps>

## Part 1: Building the Connection UI

Let's start by creating the user interface that players will use to connect to your PlayFlow server.

<Steps>
  <Step title="Create Connection Display">
    1. Open `main.tscn` and add a child node of type **Control**
    2. Rename it to "ConnectionDisplay"
    3. Set **Custom Minimum Size** to **X: 256.0px** and **Y: 128.0px**
  </Step>

  <Step title="Add Container Layout">
    1. Add a child node to "ConnectionDisplay" of type **VBoxContainer**
    2. Set **Layout Mode** to **Anchors** and **Anchors Preset** to **Full Rect**
  </Step>

  <Step title="Create URL Input Field">
    1. Add a child node to "VBoxContainer" of type **HBoxContainer**
    2. Add a **TextEdit** child to "HBoxContainer" and rename it to "UrlInput"
    3. Set **Placeholder Text** to "Url"
    4. Toggle on **Fit Content Height**
    5. Set **Custom Minimum Size** to **X: 192.0px** and **Y: 32.0px**
    6. Toggle on **Expand** under **Horizontal**
  </Step>

  <Step title="Create Port Input Field">
    1. Add another **TextEdit** child to "HBoxContainer" and rename it to "PortInput"
    2. Set **Placeholder Text** to "Port"
    3. Toggle on **Fit Content Height**
    4. Toggle on **Expand** under **Horizontal**
  </Step>

  <Step title="Add Connection Buttons">
    1. Add a **Button** child to "VBoxContainer" and rename it to "ConnectButton"
    2. Set **Text** to "Connect"
    3. Add another **Button** child to "VBoxContainer" and rename it to "DisconnectButton"
    4. Set **Text** to "Disconnect"
  </Step>

  <Step title="Set Unique Names">
    Right-click each input and button node and select **Access as Unique Name**. This allows us to reference them easily in scripts.
  </Step>

  <Step title="Create Connection Display Script">
    1. Right-click "ConnectionDisplay" and select **Attach Script**
    2. Create a new script called "connection\_display.gd"
    3. Add the following code:

    ```gdscript theme={null}
    extends Control

    @onready var url_input: TextEdit = %UrlInput
    @onready var port_input: TextEdit = %PortInput
    @onready var connect_button: Button = %ConnectButton
    @onready var disconnect_button: Button = %DisconnectButton

    func _ready() -> void:
        disconnect_button.visible = false
        multiplayer.connection_failed.connect(_on_connection_failed)

    func _on_connect_button_pressed() -> void:
        connect_button.visible = false
        disconnect_button.visible = true
        url_input.editable = false
        port_input.editable = false
        MultiplayerManager.start_client(url_input.text, port_input.text)

    func _on_disconnect_button_pressed() -> void:
        connect_button.visible = true
        disconnect_button.visible = false
        url_input.editable = true
        port_input.editable = true
        MultiplayerManager.disconnect_from_server()

    # If we are unable to connect then we enable the connect button and text inputs again.
    func _on_connection_failed() -> void:
        connect_button.visible = true
        disconnect_button.visible = false
        url_input.editable = true
        port_input.editable = true
    ```
  </Step>

  <Step title="Connect Button Signals">
    1. Select the "ConnectButton" and go to the **Node** tab next to the Inspector
    2. Connect the "pressed()" signal to "ConnectionDisplay"
    3. Repeat for "DisconnectButton"
  </Step>

  <Step title="Add Game Environment">
    1. Add a child node to "Main" of type **MeshInstance3D** and rename it to "Ground"
    2. Assign a new **PlaneMesh** to the Ground
    3. Set the PlaneMesh **Size** to **X: 10m** and **Y: 10m**
    4. Add a child node to "Main" of type **Node3D** and rename it to "Players"
    5. Add a child node to "Main" of type **MultiplayerSpawner**
    6. Add a **Camera3D** as a child to "Main" and position it as desired
    7. Add a **DirectionalLight3D** as a child to "Main" and rotate it (suggested: **X: -60.0**)
  </Step>
</Steps>

## Part 2: Creating the Multiplayer Manager

Now we'll create a Multiplayer Manager to handle all networking aspects of our game.

<Steps>
  <Step title="Create Multiplayer Manager Scene">
    1. Create a new scene, save it as "multiplayer\_manager.tscn"
    2. Select **Node** as the root type
  </Step>

  <Step title="Create Multiplayer Manager Script">
    1. Right-click the root node and select **Attach Script**
    2. Create a new script called "multiplayer\_manager.gd"
    3. Add the following code:

    ```gdscript theme={null}
    extends Node

    # Internal server port
    const PORT: int = 8080

    @onready var peer = WebSocketMultiplayerPeer.new()

    func _ready() -> void:
        # The server should always automatically start
        if is_server():
            start_server()

    func start_server() -> void:
        var err: Error = peer.create_server(PORT)
        if err == 0:
            multiplayer.multiplayer_peer = peer
            multiplayer.peer_disconnected.connect(_on_peer_disconnected)

    func start_client(url: String, port: String) -> void:
        # If you want to use localhost (i.e you run a windows server export on your PC for testing), then it must be ws:// instead.
        var err: Error = peer.create_client("wss://" + url + ":" + port)
        if err == 0:
            multiplayer.multiplayer_peer = peer

    func disconnect_from_server() -> void:
        peer.close()

    func is_server() -> bool:
        # Exports have tags and this lets us identify if the build is a dedicated server.
        return OS.has_feature("dedicated_server")

    func _on_peer_disconnected(id: int) -> void:
        var nodes = get_tree().get_nodes_in_group("Players")
        for node in nodes:
            if node.get_multiplayer_authority() == id:
                node.queue_free()
                break
    ```
  </Step>

  <Step title="Add as Autoload Singleton">
    1. Go to **Project → Project Settings → Autoload**
    2. Set **Path** to "res\://multiplayer\_manager.tscn"
    3. Set **Node Name** to "MultiplayerManager"
    4. Click **Add**

    <Info>
      This makes the MultiplayerManager available globally throughout your project.
    </Info>
  </Step>
</Steps>

## Part 3: Creating the Player

Let's create the player character with movement and networking synchronization.

<Steps>
  <Step title="Create Player Scene">
    1. Create a new scene, save it as "player.tscn"
    2. Select **3D Scene** as the root type (this creates a Node3D)
    3. Add **MeshInstance3D** as a child to Player
    4. Assign a **CapsuleMesh** to the MeshInstance3D
    5. Move the MeshInstance3D up by **Y: 1.0m** so it sits on the ground
  </Step>

  <Step title="Add Network Synchronization">
    1. Add a **MultiplayerSynchronizer** as a child to Player
    2. In the MultiplayerSynchronizer, click **Add property to sync**
    3. Select **Player → position** under **Node3D**

    <Info>
      This ensures player positions are automatically synchronized across all clients.
    </Info>
  </Step>

  <Step title="Add Player to Group">
    1. Select the Player root node
    2. Go to the **Groups** tab next to the Inspector
    3. Add the player to group "Players" (type "Players" and click **Add**)
  </Step>

  <Step title="Create Player Script">
    1. Right-click the Player root node and select **Attach Script**
    2. Create a new script called "player.gd"
    3. Add the following movement code:

    ```gdscript theme={null}
    extends Node3D

    @export var speed: float = 5.0

    func _process(delta: float) -> void:
        if not is_multiplayer_authority(): return
        var input_dir: Vector2 = Input.get_vector("move_left", "move_right", "move_forward", "move_backward")
        var offset: Vector3 = (transform.basis * Vector3(input_dir.x, 0, input_dir.y)).normalized() * speed * delta
        translate(offset)
    ```
  </Step>
</Steps>

## Part 4: Input Mapping and Player Spawning

<Steps>
  <Step title="Configure Input Map">
    1. Go to **Project → Project Settings → Input Map**
    2. Add these input actions (click **Add New Action** for each):
       * `move_forward` - Assign W key and Up Arrow
       * `move_backward` - Assign S key and Down Arrow
       * `move_left` - Assign A key and Left Arrow
       * `move_right` - Assign D key and Right Arrow
  </Step>

  <Step title="Create Player Spawning System">
    1. In `main.tscn`, select the **MultiplayerSpawner** node
    2. Right-click and **Attach Script**, create "spawner.gd"
    3. Add the following code:

    ```gdscript theme={null}
    extends MultiplayerSpawner

    func _ready() -> void:
        spawn_function = spawn_player
        # We only want the server spawning new players when new peers connect
        if MultiplayerManager.is_server():
            multiplayer.peer_connected.connect(_on_peer_connected)

    func spawn_player(peer_id: int) -> Node:
        var player: Node = load(get_spawnable_scene(0)).instantiate()
        player.set_multiplayer_authority(peer_id)
        return player

    func _on_peer_connected(id: int) -> void:
        spawn(id)
    ```
  </Step>

  <Step title="Configure MultiplayerSpawner">
    1. Set **Spawn Path** to "Players" (the Node3D we created earlier)
    2. Under **Auto Spawn List**, click **Add Element**
    3. Set the scene path to "res\://player.tscn"

    <Info>
      This tells the spawner which scene to instantiate and where to place new players.
    </Info>
  </Step>
</Steps>

## Part 5: Server Export Configuration

<Steps>
  <Step title="Add Linux Export Preset">
    1. Go to **Project → Export**
    2. Click **Add...** and select **Linux/X11**
    3. Rename the preset to "Linux Server"
    4. Set the export path filename to "Server". Note the exact name you use here — when you upload the build, the executable path you configure must match this exported binary name so PlayFlow knows which file to run.
  </Step>

  <Step title="Configure for Dedicated Server">
    1. In the Linux Server preset, go to the **Resources** tab
    2. Set **Export Mode** to "Export as dedicated server"
    3. This will create a headless server build suitable for PlayFlow
  </Step>

  <Step title="Export the Server">
    1. Click **Export Project...**
    2. Choose your export location
    3. Toggle **Export With Debug** for development builds
    4. Click **Save**
  </Step>

  <Step title="Create Archive">
    Create a .zip archive of all exported files. This is what you'll upload to PlayFlow.

    <Info>
      PlayFlow expects a .zip file containing your server executable and any required assets.
    </Info>
  </Step>
</Steps>

## Part 6: Deploy to PlayFlow and Test

<Steps>
  <Step title="Upload to PlayFlow">
    1. Create your PlayFlow account at [app.playflowcloud.com](https://app.playflowcloud.com/)
    2. Create a new project for your Godot game
    3. Open the project's **Builds** page and upload your server .zip file there

    <Info>
      Prefer automation? You can upload builds through the API instead: request an upload URL with `POST /api/v3/builds/upload-url?name=YOUR_BUILD` and `PUT` the zip to the returned `upload_url`. See the [API guide](/fundamentals/api) for details.
    </Info>
  </Step>

  <Step title="Configure Network Port">
    **CRITICAL**: When configuring the port in PlayFlow:

    1. Set **Port Number** to **8080** (matches our server code)
    2. Set **Protocol** to **TCP**
    3. **Enable TLS** - This is required for "wss\://" protocol used in browser games

    <Warning>
      Without TLS enabled, web clients cannot connect to your server. This is essential for browser compatibility.
    </Warning>
  </Step>

  <Step title="Start Server Instance">
    1. Create and start a server instance in PlayFlow
    2. Copy the **Host** URL and **External Port** from the server details

    <Info>
      The **External Port** is allocated by PlayFlow and will differ from your internal `8080`. Always read the host and external port from the running server (the `network_ports[]` array in the API response, or the server details in the dashboard) rather than assuming a fixed port.
    </Info>
  </Step>

  <Step title="Test the Connection">
    1. Run your Godot project locally (you can enable **Multiple Instances** in Debug settings for testing)
    2. Enter the PlayFlow Host URL in the "Url" field
    3. Enter the External Port in the "Port" field
    4. Click **Connect**
    5. Your player should appear and you can move around with WASD keys!

    <Tip>
      **Testing Multiple Players**: Enable **Debug → Customize Run Instances → Enable Multiple Instances** and set instance count to 2. Run the game and connect both instances to see multiplayer in action.
    </Tip>
  </Step>
</Steps>

## Technical Architecture

### Network Setup

* **Protocol**: WebSocket with TLS ("wss\://")
* **Server Port**: 8080 (internal)
* **Synchronization**: Player position only
* **Authority**: Server-authoritative with client input

### Key Components

1. **MultiplayerManager**: Handles connection logic and server detection
2. **Player**: Networked player with movement and authority management
3. **ConnectionDisplay**: UI for entering server connection details
4. **MultiplayerSpawner**: Automatically spawns players when clients connect

### Platform Support

* **Desktop**: Windows, Linux, macOS
* **Web**: Browser support via WebSocket + TLS
* **Server**: Headless Linux builds for PlayFlow

## Next Steps

<CardGroup>
  <Card title="Lobby System" icon="users" href="/unity/lobby-overview">
    Add lobbies and matchmaking
  </Card>

  <Card title="WebGL Deployment" icon="globe" href="/guides/webgl-deployments">
    Deploy for web browsers
  </Card>
</CardGroup>

## Common Issues

<AccordionGroup>
  <Accordion title="Connection timeout or 'wss://' connection failed">
    * Verify the server URL and port are correct
    * **Ensure TLS is enabled** in PlayFlow port configuration
    * Check that the PlayFlow server instance is running
    * For local testing, use "ws\://" instead of "wss\://" (localhost only)
  </Accordion>

  <Accordion title="Players not synchronizing or appearing">
    * Check that MultiplayerSynchronizer is properly configured on the player
    * Verify the player scene is added to MultiplayerSpawner's Auto Spawn List
    * Ensure players are being added to the "Players" group
    * Check that spawn\_function is set correctly in spawner.gd
  </Accordion>

  <Accordion title="Server not starting automatically">
    * Verify MultiplayerManager is added as an Autoload singleton
    * Check that `OS.has_feature("dedicated_server")` returns true in server builds
    * Ensure the "Export as dedicated server" option is enabled in export settings
  </Accordion>

  <Accordion title="Input not working">
    * Check that input actions are properly defined in Project Settings → Input Map
    * Verify `is_multiplayer_authority()` check in player movement code
    * Ensure the player has authority set via `set_multiplayer_authority()`
  </Accordion>
</AccordionGroup>

## Resources

* **Godot Documentation**: [docs.godotengine.org](https://docs.godotengine.org/)
* **Godot Multiplayer**: [docs.godotengine.org/en/stable/tutorials/networking](https://docs.godotengine.org/en/stable/tutorials/networking/)
* **PlayFlow Documentation**: [docs.playflowcloud.com](https://docs.playflowcloud.com/)
* **Complete Project**: [GitHub Repository](https://github.com/Xaimelee/playflow-quick-start-guide)


# Installation Guide
Source: https://docs.playflowcloud.com/guides/installation

How to install the PlayFlow Unity SDK.

You can install the PlayFlow Unity SDK directly from the Unity Package Manager using a Git URL. This is the recommended method as it makes updates easier.

## Prerequisites

* **Git** installed on your machine and available on your `PATH`. Unity's Package Manager shells out to Git for git-URL installs, and the install fails silently if Git is missing.
* A **supported Unity version**. Check the version matrix in the [SDK repository README](https://github.com/PlayFlowCloud/PlayFlow-Multiplayer-Unity-SDK).

## Installing from Git URL

To install the PlayFlow Multiplayer Unity SDK, follow these steps, which are also available on our official [GitHub repository](https://github.com/PlayFlowCloud/PlayFlow-Multiplayer-Unity-SDK).

1. In your Unity project, open the Package Manager by navigating to **Window > Package Manager**.
2. Click the **`+`** button in the top-left corner of the Package Manager window.
3. Select **"Add package from git URL..."** from the dropdown menu.
4. Enter the following URL in the text field:
   ```
   https://github.com/PlayFlowCloud/PlayFlow-Multiplayer-Unity-SDK.git
   ```
5. Click **Add**.

Unity will now download and install the package and its dependencies into your project.

<Tip>
  The URL above tracks the tip of the default branch. For reproducible builds, pin a specific release by appending `#<version-tag>` to the URL (for example, `...PlayFlow-Multiplayer-Unity-SDK.git#v1.0.0`). Browse available tags on the [repository's releases page](https://github.com/PlayFlowCloud/PlayFlow-Multiplayer-Unity-SDK/releases).
</Tip>

***

## Next Steps

Once the PlayFlow SDK is installed, you are ready to configure it and start building your multiplayer game.

<CardGroup>
  <Card title="Unity SDK Overview" icon="cuboid" href="/unity/index">
    Get an overview of the SDK's features and initial setup.
  </Card>

  <Card title="Set Up Linux Modules" icon="server" href="/guides/unity-modules">
    Install the required Linux modules for building dedicated servers.
  </Card>
</CardGroup>


# Migration Guide
Source: https://docs.playflowcloud.com/guides/migration-guide

Migrate your existing game servers from PlayFlow 1.0 to PlayFlow Cloud.

# Migrate from PlayFlow 1.0

If you're currently using PlayFlow 1.0, moving to PlayFlow Cloud is a clean re-onboarding: you create a new account, project, and API keys, then re-upload your existing server build. There is no automatic import that reaches back into PlayFlow 1.0 — you bring your build zip forward and launch it against the new engine.

<Info>
  **What changed in 2.0.** PlayFlow Cloud is a ground-up rebuild. Servers are launched through a REST engine at `https://api.computeflow.cloud/api`, builds are selected by their **name** (`version_tag`) rather than an internal build ID, every server start now **requires a region**, and connection details (host + port) are returned in the API response instead of being fixed. The steps below map your old workflow onto the new one.
</Info>

## [Prerequisites](#prerequisites)

Before you start, have the following ready:

* Your PlayFlow 1.0 **server build zip** (a Linux dedicated-server build). If you no longer have the zip, rebuild it from your game project.
* A machine with `curl` (or your language's HTTP client) for the upload and launch steps.
* A few minutes to create a new account — there is no data carried over automatically from PlayFlow 1.0.

## [Create your PlayFlow Cloud account](#create-your-playflow-cloud-account)

To begin migrating to PlayFlow Cloud, you'll need to create a new account:

1. Visit [app.playflowcloud.com](https://app.playflowcloud.com)
2. Sign up with your email or connect with your GitHub/Google account
3. Verify your email address if prompted

<Note>
  Even if you had a PlayFlow 1.0 account, you'll need to create a new account for PlayFlow Cloud. This ensures you get access to all the new features and improved infrastructure.
</Note>

## [Set up your organization](#set-up-your-organization)

Organizations help you manage your game projects and team collaborations:

1. After logging in, you'll be prompted to create an organization
2. Give your organization a descriptive name (e.g., your studio name)
3. *Optional:* Invite team members by entering their email addresses
   * Team members will receive an invitation email
   * They can access all projects within your organization

## [Create your project](#create-your-project)

Set up a project for your migrated game:

1. From your organization dashboard, click **Create Project**
2. Enter the same name as your PlayFlow 1.0 project (or choose a new one)
3. *Optional:* Add a description to help identify the project
4. Click **Create Project** to proceed

## [Get your API key](#get-your-api-key)

Server and build operations run through the engine API, so grab a key first:

1. Open the **API Keys** tab in your new project
2. Copy the **server key** (prefix `pf_`) — it has full access and must stay server-side
3. Note the **client key** (prefix `pfclient_`) for anything you ship inside a game build

Authenticate every request with the `api-key` header.

<Warning>
  Uploading and deleting builds and updating project settings require the **server key** (`pf_`). A client key (`pfclient_`) is rejected with `403` on those operations. Never embed a server key in a shipped game client.
</Warning>

## [Re-upload your build](#re-upload-your-build)

There is no legacy importer — you upload your existing build zip to the new project. This is a two-step flow: request a one-time upload URL, then `PUT` your zip to it. Pick a build **name** (`?name=`); PlayFlow auto-increments the version each time you upload under the same name.

<CodeGroup>
  ```bash Request an upload URL theme={null}
  curl -X POST "https://api.computeflow.cloud/api/v3/builds/upload-url?name=my-server" \
    -H "api-key: pf_your_server_key"
  ```

  ```json Response theme={null}
  {
    "build_id": "b3f1c2a4-...",
    "name": "my-server",
    "upload_url": "https://...r2.cloudflarestorage.com/...",
    "message": "Upload URL generated"
  }
  ```

  ```bash Upload the zip theme={null}
  curl -X PUT "<upload_url from the response>" \
    --data-binary @my-server.zip
  ```
</CodeGroup>

<Info>
  The `upload_url` expires **60 minutes** after it is issued. Upload your zip before then; if it expires, request a new one. PlayFlow processes the build after upload and moves it from `processing` to `ready`.
</Info>

## [Verify your build](#verify-your-build)

After the upload:

1. Open the **Builds** tab and confirm your build reached **ready** status
2. Check that the build name matches what you'll pass as `version_tag` when launching servers
3. Note the version number — you can pin a specific version at launch, or omit it to use the latest under that name

## [Configure network settings](#configure-network-settings)

Port configuration lives under the **Settings** tab, not a separate Configuration tab:

1. Go to the **Settings** tab in your project
2. In the port configuration section, add each port your server listens on:
   * Set the protocol with the **TCP/UDP** toggle
   * Enable the separate **TLS** checkbox if that port needs TLS termination
3. Save your settings

<Warning>
  Ports are **allocated by PlayFlow** at launch and do not match your internal port — don't assume `7777` or any fixed value. When you connect a client, read the public host and port from the server's API response: iterate `network_ports[]` and use its `host` and `external_port`. TCP ports resolve to a relay host; UDP ports resolve to a proxy IPv4.
</Warning>

## [Deploy and test](#deploy-and-test)

Now you're ready to launch your migrated server. From the dashboard, open the **Servers** tab and start a server: give it a name, choose a **region**, select your build, and pick a compute size. Or launch it directly through the API:

```bash Launch a server theme={null}
curl -X POST "https://api.computeflow.cloud/api/v3/servers/start" \
  -H "api-key: pf_your_server_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-server-1",
    "region": "us-east",
    "version_tag": "my-server",
    "compute_size": "small",
    "ttl": 3600
  }'
```

`name` and `region` are **required**. Select your build with `version_tag` (the build **name** you uploaded) plus an optional `version`. There is no `build_id` field on server start. Region must be one of the 13 canonical regions (for example `us-east`, `eu-west`, `ap-south`, `sea`). Read the connection host and port back from `network_ports[]` in the response, then test with your game client.

<Info>
  **Free plan limits.** New organizations start on the Free plan: at most **1 active server**, compute size forced to **small**, and TTL forced to **1 hour** (`3600` seconds). Upgrade to **Pro** (\$20/mo) for all compute sizes, TTL up to 24 hours (`86400` seconds), and unlimited active servers.
</Info>

## [What's improved in PlayFlow Cloud](#whats-improved-in-playflow-cloud)

PlayFlow Cloud offers several advantages over PlayFlow 1.0:

<CardGroup>
  <Card title="Modern Infrastructure" icon="zap">
    Rebuilt server infrastructure with global multi-region deployment
  </Card>

  <Card title="Enhanced Monitoring" icon="activity">
    Real-time server metrics and detailed logging capabilities
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Simplified Management" icon="settings">
    Streamlined dashboard and easier project organization
  </Card>

  <Card title="Built-in Player Auth" icon="star">
    Verified player identity via JWT, PlayFab, or Steam providers
  </Card>
</CardGroup>

## [Need help?](#need-help)

If you encounter any issues during migration:

* Check our [Discord community](https://discord.gg/P5w45Vx5Q8) for support
* Review the [Quick Start guide](/quickstart) for additional setup help
* Contact our support team through the dashboard

## [Next steps](#next-steps)

Once your migration is complete, explore PlayFlow Cloud's new features:

<CardGroup>
  <Card title="WebGL Deployments" icon="globe" href="/guides/webgl-deployments">
    Optimize your servers for browser-based games
  </Card>

  <Card title="Unity Modules" icon="unity" href="/guides/unity-modules">
    Simplify deployment directly from Unity Editor
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Server Types" href="/fundamentals/plan-instance-types">
    <Icon icon="server" />
  </Card>

  <Card title="API Integration" href="/fundamentals/api">
    <Icon icon="code" />
  </Card>
</CardGroup>


# Player Authentication
Source: https://docs.playflowcloud.com/guides/player-authentication

Configure player identity verification for lobbies and matchmaking.

PlayFlow supports authenticating players who connect through the Lobby and Matchmaking system. You configure an auth provider for your project via the engine API, and PlayFlow validates player identity tokens before allowing lobby and matchmaking operations.

## Prerequisites

* A PlayFlow project with an API key. Player-token verification only runs for **client keys** (`pfclient_*`, the key you ship in your game build). See [Sending the Player Token](#sending-the-player-token) for why the key type matters.
* A **server key** (`pf_*`) to configure the provider — updating project settings requires a server key (a client key returns `403`).
* If you use a verified provider, a way for your game client to obtain a token (a JWT, PlayFab entity token, or Steam session ticket).

## How It Works

When a player connects to a lobby or enters matchmaking with a client key, their game client sends an identity token in the `x-player-token` header. PlayFlow validates that token against your configured provider, creates or updates a player record, and grants access to the session. When your project uses the default `none` provider, PlayFlow instead trusts the `x-player-id` header verbatim.

```mermaid theme={null}
sequenceDiagram
    participant Client as Game Client
    participant Provider as Auth Provider
    participant PF as PlayFlow
    participant DB as Players Table

    Client->>Provider: Authenticate (login, session, ticket)
    Provider-->>Client: Identity token
    Client->>PF: Lobby/matchmaking request<br/>api-key + x-player-token
    PF->>Provider: Verify token (JWKS / Steam API)
    Provider-->>PF: Verified identity
    PF->>DB: Upsert player record
    DB-->>PF: Player ID
    PF-->>Client: Access granted
```

<Steps>
  <Step title="Configure your auth provider">
    Set the provider on your project with a server key via `POST /api/v3/projects/settings`. See [API Configuration](#api-configuration) below.
  </Step>

  <Step title="Get a token from your auth provider">
    Your game client authenticates with your chosen provider and receives a token -- a JWT, PlayFab entity token, or Steam session ticket.
  </Step>

  <Step title="Send the token with requests">
    Include the token in the `x-player-token` header when your client connects to lobbies or matchmaking.
  </Step>

  <Step title="PlayFlow validates and tracks the player">
    PlayFlow verifies the token, creates or updates a player record with the provider's user ID, and grants access. You can view authenticated players in the **Players** tab on the dashboard.
  </Step>
</Steps>

## Auth Providers

PlayFlow supports four authentication providers. Choose the one that matches your game's identity system.

<Tabs>
  <Tab title="None (Default)">
    No server-side verification. In `none` mode, the player's identity comes from the `x-player-id` header, which PlayFlow trusts verbatim. The `x-player-token` header is not consulted in this mode.

    This is the default for all projects. It is suitable for development and testing but should not be used in production.

    ### Configuration

    No configuration is needed. All new projects start with this provider.

    ```json theme={null}
    {
      "provider": "none"
    }
    ```

    ### Behavior

    * Send the player's unique identifier in the `x-player-id` header on every player-scoped lobby and matchmaking request.
    * The `x-player-id` value is used directly as the player identity — there is no verification.
    * Player-scoped requests without an `x-player-id` header fail with `400 Missing x-player-id header`.
    * `x-player-token` is ignored in `none` mode.

    <Warning>
      None mode performs no verification. Any client can impersonate any player by sending an arbitrary `x-player-id` value. Use a verified provider (Custom JWT, PlayFab, or Steam) before shipping to production.
    </Warning>
  </Tab>

  <Tab title="Custom JWT">
    Validate JWTs from any OIDC-compliant provider using a JWKS (JSON Web Key Set) endpoint. This works with Auth0, Firebase Auth, Supabase Auth, Clerk, and any other provider that publishes a JWKS URL.

    PlayFlow fetches your public keys from the JWKS endpoint, verifies the JWT signature and expiry, and extracts the `sub` claim as the player identifier.

    ### Configuration

    ```json theme={null}
    {
      "provider": "custom_jwt",
      "jwks_url": "https://your-auth-provider.com/.well-known/jwks.json",
      "issuer": "https://your-auth-provider.com",
      "audience": "your-app-id"
    }
    ```

    | Field      | Required | Description                                                              |
    | ---------- | -------- | ------------------------------------------------------------------------ |
    | `jwks_url` | Yes      | The URL where your auth provider publishes its public keys.              |
    | `issuer`   | No       | Expected `iss` claim in the JWT. Rejects tokens from other issuers.      |
    | `audience` | No       | Expected `aud` claim in the JWT. Rejects tokens intended for other apps. |

    ### Common JWKS URLs

    | Provider      | JWKS URL                                                                                    |
    | ------------- | ------------------------------------------------------------------------------------------- |
    | Auth0         | `https://YOUR_DOMAIN.auth0.com/.well-known/jwks.json`                                       |
    | Firebase Auth | `https://www.googleapis.com/service_accounts/v1/jwk/securetoken@system.gserviceaccount.com` |
    | Supabase Auth | `https://YOUR_PROJECT.supabase.co/auth/v1/.well-known/jwks`                                 |
    | Clerk         | `https://YOUR_DOMAIN.clerk.accounts.dev/.well-known/jwks.json`                              |

    <Info>
      JWKS keys are cached in memory and rotated automatically when your provider publishes new keys. You do not need to restart or redeploy after a key rotation.
    </Info>
  </Tab>

  <Tab title="PlayFab">
    Native integration with Microsoft PlayFab. PlayFlow verifies PlayFab entity tokens (JWTs) against PlayFab's published JWKS endpoint and extracts the `eid` (entity ID) claim as the player identifier.

    ### Configuration

    ```json theme={null}
    {
      "provider": "playfab",
      "title_id": "YOUR_TITLE_ID"
    }
    ```

    | Field      | Required | Description                                                |
    | ---------- | -------- | ---------------------------------------------------------- |
    | `title_id` | Yes      | Your PlayFab Title ID (found in the PlayFab Game Manager). |

    PlayFlow automatically constructs the JWKS URL from your Title ID:

    ```
    https://{title_id}.playfabapi.com/jwks
    ```

    ### Getting a PlayFab Entity Token

    In your game client, call `GetEntityToken` after the player logs in:

    ```csharp theme={null}
    PlayFabAuthenticationAPI.GetEntityToken(
        new GetEntityTokenRequest(),
        result => {
            string entityToken = result.EntityToken;
            // Pass this as x-player-token when connecting to PlayFlow
        },
        error => Debug.LogError(error.GenerateErrorReport())
    );
    ```
  </Tab>

  <Tab title="Steam">
    Validates Steam authentication tickets via the Steamworks Web API. Unlike the JWT-based providers, this makes an HTTP call to Steam's servers for each authentication.

    ### Configuration

    ```json theme={null}
    {
      "provider": "steam",
      "app_id": "YOUR_APP_ID",
      "web_api_key": "YOUR_WEB_API_KEY"
    }
    ```

    | Field         | Required | Description                                                                                                           |
    | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
    | `app_id`      | Yes      | Your Steam Application ID.                                                                                            |
    | `web_api_key` | Yes      | Your Steam Web API Key (from the [Steamworks partner site](https://partner.steamgames.com/doc/webapi_overview/auth)). |

    PlayFlow calls the `ISteamUserAuth/AuthenticateUserTicket/v1/` endpoint and extracts the `steamid` as the player identifier.

    ### Getting a Steam Auth Ticket

    In your game client, use the Steamworks API to get a session ticket:

    ```csharp theme={null}
    // Using Steamworks.NET
    byte[] ticketData = new byte[1024];
    uint ticketLength;
    HAuthTicket ticket = SteamUser.GetAuthSessionTicket(ticketData, 1024, out ticketLength);
    string hexTicket = BitConverter.ToString(ticketData, 0, (int)ticketLength).Replace("-", "");
    // Pass hexTicket as x-player-token when connecting to PlayFlow
    ```

    <Warning>
      Your Steam Web API Key is stored in your project's `auth_config`. Set it only with a server key, treat it as a secret, and never expose it in a client build.
    </Warning>
  </Tab>
</Tabs>

## API Configuration

Configure player authentication by writing an `auth_config` to your project settings via the engine API. This is the only supported way to set the provider.

<Warning>
  Updating project settings requires a **server key** (`pf_*`). A client key (`pfclient_*`) returns `403`. Keep your server key server-side — never ship it in a game build.
</Warning>

<CodeGroup>
  ```bash None theme={null}
  curl -X POST https://api.computeflow.cloud/api/v3/projects/settings \
    -H "api-key: YOUR_SERVER_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "auth_config": {
        "provider": "none"
      }
    }'
  ```

  ```bash Custom JWT theme={null}
  curl -X POST https://api.computeflow.cloud/api/v3/projects/settings \
    -H "api-key: YOUR_SERVER_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "auth_config": {
        "provider": "custom_jwt",
        "jwks_url": "https://your-auth.com/.well-known/jwks.json",
        "issuer": "https://your-auth.com",
        "audience": "your-app"
      }
    }'
  ```

  ```bash PlayFab theme={null}
  curl -X POST https://api.computeflow.cloud/api/v3/projects/settings \
    -H "api-key: YOUR_SERVER_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "auth_config": {
        "provider": "playfab",
        "title_id": "YOUR_TITLE_ID"
      }
    }'
  ```

  ```bash Steam theme={null}
  curl -X POST https://api.computeflow.cloud/api/v3/projects/settings \
    -H "api-key: YOUR_SERVER_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "auth_config": {
        "provider": "steam",
        "app_id": "YOUR_APP_ID",
        "web_api_key": "YOUR_WEB_API_KEY"
      }
    }'
  ```
</CodeGroup>

You can verify the current configuration by reading your project settings:

```bash theme={null}
curl https://api.computeflow.cloud/api/v3/projects/settings \
  -H "api-key: YOUR_SERVER_KEY"
```

The response includes your current `auth_config` alongside other project settings. Changes take effect immediately for all new player connections.

## Sending the Player Token

<Info>
  **Token verification only runs for client keys (`pfclient_*`).** Ship a client key in your game build so PlayFlow verifies each player's `x-player-token` against your provider and derives identity from the verified token.

  A **server key (`pf_*`) bypasses verification** even when a provider is configured — it is trusted to assert identity directly via `x-player-id` (for trusted server-side matchmakers and admin tooling). If you test a verified provider with a server key, verification silently passes through and you may wrongly conclude it works.
</Info>

Once your provider is configured, your game client (using a client key) must include the player's identity token in the `x-player-token` header on every player-scoped lobby and matchmaking request. In `none` mode, send `x-player-id` instead (no token).

<Tabs>
  <Tab title="Unity">
    The PlayFlow SDK handles the token header automatically when you set the player token during initialization:

    ```csharp theme={null}
    // After authenticating with your provider, pass the token to PlayFlow
    string playerToken = GetTokenFromYourAuthProvider();

    PlayFlowLobbyManagerV2.Instance.Initialize(playerToken, () => {
        Debug.Log("PlayFlow SDK initialized with authenticated player.");
    });
    ```
  </Tab>

  <Tab title="REST API (verified provider)">
    With a verified provider and a client key, send the token on a player-scoped request. PlayFlow verifies it and derives the player identity — no `x-player-id` needed:

    ```bash theme={null}
    curl -X POST https://api.computeflow.cloud/api/v3/lobbies/default \
      -H "api-key: YOUR_CLIENT_KEY" \
      -H "x-player-token: PLAYER_IDENTITY_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"name": "My Lobby", "maxPlayers": 4}'
    ```
  </Tab>

  <Tab title="REST API (None mode)">
    In `none` mode, identify the player with the `x-player-id` header:

    ```bash theme={null}
    curl -X POST https://api.computeflow.cloud/api/v3/lobbies/default \
      -H "api-key: YOUR_API_KEY" \
      -H "x-player-id: player-123" \
      -H "Content-Type: application/json" \
      -d '{"name": "My Lobby", "maxPlayers": 4}'
    ```
  </Tab>
</Tabs>

## Players Table

Players verified by a provider are automatically tracked in a per-project players table. Each time a player is verified against **Custom JWT, PlayFab, or Steam**, PlayFlow upserts a record with the following fields:

| Field          | Description                                                                                       |
| -------------- | ------------------------------------------------------------------------------------------------- |
| `id`           | Unique player ID (UUID), auto-generated by PlayFlow.                                              |
| `provider`     | The auth provider that verified this player (`custom_jwt`, `playfab`, `steam`).                   |
| `provider_uid` | The player's identifier from the auth provider (e.g., JWT `sub`, PlayFab `eid`, Steam `steamid`). |
| `display_name` | Display name extracted from the token, if available.                                              |
| `metadata`     | Provider-specific metadata (e.g., `owner_steamid` for Steam, `title_id` for PlayFab).             |
| `last_seen_at` | Timestamp of the player's most recent authentication.                                             |

Players are uniquely identified by the combination of `project_id` and `provider_uid`. If the same player authenticates again, their existing record is updated rather than duplicated.

<Info>
  `none`-mode players are **not** written to the players table — no persisted record is created for them. They may appear transiently in a live lobby or match roster, but only verified-provider players are persisted.
</Info>

You can view your authenticated players in the **Players** tab on the project dashboard.

## Choosing a Provider

<CardGroup>
  <Card title="Development / Testing" icon="flask">
    Use **None** to get started quickly without any auth infrastructure. Switch to a verified provider before launching.
  </Card>

  <Card title="Existing Auth System" icon="key">
    Use **Custom JWT** if you already have an auth provider (Auth0, Firebase, Supabase, Clerk, or any OIDC-compliant service).
  </Card>

  <Card title="PlayFab Games" icon="gamepad">
    Use **PlayFab** if your game uses Microsoft PlayFab for player management and you want native integration.
  </Card>

  <Card title="Steam Games" icon="steam">
    Use **Steam** if your game is distributed on Steam and you want to verify player identity through Steam session tickets.
  </Card>
</CardGroup>

## Next Steps

<CardGroup>
  <Card title="Lobby Quick Start" icon="rocket" href="/unity/lobbies">
    Set up lobbies and start using player authentication with the lobby system.
  </Card>

  <Card title="Matchmaking Guide" icon="swords" href="/unity/matchmaking">
    Add skill-based matchmaking with authenticated players.
  </Card>
</CardGroup>


# PlayFab Bridge
Source: https://docs.playflowcloud.com/guides/playfab-bridge

Keep PlayFab for matchmaking and identity while hosting your dedicated game servers on PlayFlow.

This guide shows you how to automatically deploy a PlayFlow game server when players are matched through **PlayFab's matchmaker**, and how clients discover the server through **PlayFab Player Data** — which the server itself updates once it is ready.

It's the same pattern popularized by other hosting providers, mapped onto PlayFlow's API. If you're already invested in PlayFab for matchmaking and identity, this lets you adopt PlayFlow for server hosting without moving off PlayFab.

<Info>
  **PlayFlow also has a native [lobby and matchmaking system](/lobbies/overview).** If you're starting fresh, that path is simpler — no PlayFab required. Use this bridge when you specifically want to keep PlayFab's matchmaker or player identity.
</Info>

Before getting started, we expect that:

* You currently use PlayFab (a title, a matchmaking queue, and some registered players).
* You have a PlayFlow project and a **dedicated Linux server build** ready to upload. See the [Docker builds guide](/guides/docker-builds) or the [Unity quickstart](/quickstart/fishnet) if you don't yet.

## How it works

<Steps>
  <Step title="PlayFab matches players">
    PlayFab's matchmaker fires a `playfab.matchmaking.match_found` event.
  </Step>

  <Step title="A CloudScript rule calls PlayFlow">
    A PlayFab Automation rule runs a CloudScript function that calls `POST /api/v3/servers/start`, passing the PlayFab match ID, title secret, and player list as environment variables.
  </Step>

  <Step title="PlayFlow launches the server">
    PlayFlow allocates the network ports immediately and boots your build. It injects everything the server needs as environment variables (`PLAYFLOW_PORTS`, your custom vars, and API credentials).
  </Step>

  <Step title="The server publishes its address">
    On startup, the server reads its own public `host:port` from `PLAYFLOW_PORTS` and writes it into each matched player's PlayFab Player Data — keyed by the match ID.
  </Step>

  <Step title="Clients connect">
    Each client polls its PlayFab ticket until matched, then reads the connection info from Player Data and connects. Because the server only writes Player Data once it's actually running, clients never get a stale address.
  </Step>
</Steps>

```mermaid theme={null}
sequenceDiagram
    participant C as Game Client
    participant PF as PlayFab
    participant CS as PlayFab CloudScript
    participant PL as PlayFlow API
    participant S as Game Server

    C->>PF: CreateMatchmakingTicket
    PF-->>PF: match_found event
    PF->>CS: Automation rule → StartPlayFlowDeployment
    CS->>PL: POST /api/v3/servers/start (env: match id, secret, players)
    PL->>S: Boot build, inject PLAYFLOW_PORTS + env
    S->>PF: UpdateUserData → "host:port" (keyed by match id)
    C->>PF: Poll ticket → Matched → GetUserData
    PF-->>C: host:port
    C->>S: Connect
```

## Step 1 — Prepare your PlayFlow project

<Steps>
  <Step title="Get a server API key">
    In your PlayFlow dashboard, open your project's **API Keys** and copy a **server key** (`pf_...`). This key can start servers and must stay secret — treat it exactly like your PlayFab Title Secret. Never ship it in a client build.
  </Step>

  <Step title="Upload your server build">
    Upload your dedicated Linux server build and give it a **name** (for example `space-edge`). PlayFlow references builds by this name — the value becomes the `version_tag` you pass when starting a server, and each upload under the same name auto-increments its version. See [Docker builds](/guides/docker-builds) for the upload flow.
  </Step>

  <Step title="Configure a network port">
    In your project settings, add a port config and give it a **name** you'll look up later — this guide uses `game`. Choose `UDP` for most game netcode (for example FishNet's Tugboat transport), or `TCP` (optionally with TLS) for WebSocket-based clients. PlayFlow allocates the public port at launch; your server reads it back from `PLAYFLOW_PORTS`.
  </Step>
</Steps>

## Step 2 — Create the PlayFab CloudScript function

Log in to PlayFab, open your title, and under **Automation → Revisions (Legacy)** deploy a new revision containing the function below. It calls PlayFlow's start endpoint and forwards everything the server will need.

Update the four variables at the top with your own values first. The `PlayFlow_BuildName` must match the build name you uploaded in Step 1.

<Warning>
  Keep this function server-side. It holds your PlayFlow **server key** and PlayFab **Title Secret** — the CloudScript is the trusted interface that keeps both hidden from players.
</Warning>

```javascript theme={null}
var PlayFlow_ApiUrl     = "https://api.computeflow.cloud/api";
var PlayFlow_ApiKey     = "pf_your_server_key";   // PlayFlow server key — keep secret
var PlayFlow_BuildName  = "space-edge";           // the build NAME you uploaded
var PlayFab_TitleSecret = "TITLE_SECRET";

// PlayFlow regions with approximate coordinates, for nearest-region selection.
// Full list: https://docs.playflowcloud.com/fundamentals/regions
var PlayFlow_Regions = [
  { region: "us-east",              lat: 40.7,  lon: -74.0 },
  { region: "us-south",             lat: 32.8,  lon: -96.8 },
  { region: "us-west",              lat: 34.0,  lon: -118.2 },
  { region: "eu-west",              lat: 50.1,  lon: 8.7 },
  { region: "eu-north",             lat: 59.3,  lon: 18.1 },
  { region: "eu-uk",                lat: 51.5,  lon: -0.1 },
  { region: "ap-south",             lat: 19.1,  lon: 72.9 },
  { region: "sea",                  lat: 1.35,  lon: 103.8 },
  { region: "ap-north",             lat: 35.7,  lon: 140.4 },
  { region: "ap-southeast",         lat: -33.9, lon: 151.2 },
  { region: "south-america-brazil", lat: -23.5, lon: -46.6 },
  { region: "south-africa",         lat: -26.2, lon: 28.0 },
];

function nearestRegion(points) {
  // Average the players' locations, then pick the closest PlayFlow region.
  if (!points.length) return "us-east";
  var avgLat = points.reduce(function (s, p) { return s + p.lat; }, 0) / points.length;
  var avgLon = points.reduce(function (s, p) { return s + p.lon; }, 0) / points.length;
  var best = null, bestD = Infinity;
  PlayFlow_Regions.forEach(function (r) {
    var d = Math.pow(r.lat - avgLat, 2) + Math.pow(r.lon - avgLon, 2);
    if (d < bestD) { bestD = d; best = r.region; }
  });
  return best;
}

handlers.StartPlayFlowDeployment = function (args, context) {
  var QueueName = context.playStreamEvent.Payload.QueueName;
  var MatchId   = context.playStreamEvent.Payload.MatchId;

  var members = multiplayer.GetMatch({
    QueueName: QueueName,
    MatchId: MatchId,
    EscapeObject: false,
    ReturnMemberAttributes: false,
  }).Members;

  var locations = [];
  var playerIds = [];

  members.forEach(function (member) {
    var profile = entity.GetProfile({ Entity: member.Entity });
    var masterId = profile.Profile.Lineage.MasterPlayerAccountId;

    var loc = server.GetPlayerProfile({
      PlayFabId: masterId,
      ProfileConstraints: { ShowLocations: true },
    });

    var l = loc.PlayerProfile.Locations && loc.PlayerProfile.Locations[0];
    if (l) locations.push({ lat: l.Latitude, lon: l.Longitude });
    playerIds.push(masterId);
  });

  var region = nearestRegion(locations);

  var response = JSON.parse(
    http.request(
      PlayFlow_ApiUrl + "/v3/servers/start",
      "post",
      JSON.stringify({
        name: "match-" + MatchId.slice(0, 20),
        region: region,
        version_tag: PlayFlow_BuildName,
        environment_variables: {
          PLAYFAB_MATCH_ID: MatchId,
          PLAYFAB_TITLE_SECRET: PlayFab_TitleSecret,
          PLAYFAB_MATCH_PLAYERS_ID_LIST: playerIds.join(","),
        },
      }),
      "application/json",
      { "api-key": PlayFlow_ApiKey }
    )
  );

  log.info("PlayFlow server starting", response);
};
```

<Info>
  PlayFlow returns the `instance_id`, a `status` of `launching`, and the allocated `network_ports` **synchronously** from this call — the ports are reserved before the machine boots. This guide has the *server* publish the address (Step 4) so that connection info appears in Player Data exactly when the server is ready. If you'd rather publish from CloudScript, you can instead poll `GET /api/v3/servers/{instance_id}` until `status` is `running` and read `network_ports` from the response.
</Info>

## Step 3 — Add the automation rule

Under **Automation → Rules**, create a new rule:

* **Event Type**: `playfab.matchmaking.match_found`
* **Action** → **Type**: `Execute Entity CloudScript`
* **CloudScript Function**: `StartPlayFlowDeployment`

Now every completed match automatically launches a dedicated PlayFlow server.

## Step 4 — Publish the address from the server

When PlayFlow starts your server, it injects these environment variables into the container (alongside any `environment_variables` you passed from CloudScript):

| Variable                                | Description                                                                                                                  |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `PLAYFLOW_PORTS`                        | JSON array of the server's public ports: `[{ "name", "internal_port", "external_port", "protocol", "host", "tls_enabled" }]` |
| `PLAYFLOW_INSTANCE_ID`                  | This server's instance ID                                                                                                    |
| `PLAYFLOW_API_KEY` / `PLAYFLOW_API_URL` | Credentials + base URL to call the PlayFlow API back if needed                                                               |
| `PLAYFLOW_REGION`                       | The region the server launched in                                                                                            |
| Your custom vars                        | `PLAYFAB_MATCH_ID`, `PLAYFAB_TITLE_SECRET`, `PLAYFAB_MATCH_PLAYERS_ID_LIST`                                                  |

On startup, read the public address for your named port out of `PLAYFLOW_PORTS`, then write `host:external_port` into each matched player's Player Data, keyed by the match ID.

```csharp PlayerDataUpdateService.cs theme={null}
public class PlayerDataUpdateService : NetworkBehaviour
{
    [SerializeField] private string ServerPortName = "game"; // must match your PlayFlow port config name

    private PlayfabRestApiService _playfab;

    public override void OnStartServer()
    {
        _playfab = FindObjectOfType<PlayfabRestApiService>();

        string matchId      = Environment.GetEnvironmentVariable("PLAYFAB_MATCH_ID");
        string titleSecret  = Environment.GetEnvironmentVariable("PLAYFAB_TITLE_SECRET");
        string[] playerIds  = Environment.GetEnvironmentVariable("PLAYFAB_MATCH_PLAYERS_ID_LIST")?.Split(',');
        string portsJson    = Environment.GetEnvironmentVariable("PLAYFLOW_PORTS");

        if (string.IsNullOrEmpty(portsJson))
        {
            Debug.LogError("PLAYFLOW_PORTS not set — is this running on PlayFlow?");
            return;
        }

        // PLAYFLOW_PORTS is a JSON array; find the port config by name.
        PlayFlowPort[] ports = JsonConvert.DeserializeObject<PlayFlowPort[]>(portsJson);
        PlayFlowPort game = Array.Find(ports, p => p.name == ServerPortName);
        if (game == null)
        {
            Debug.LogError($"No PlayFlow port named '{ServerPortName}'");
            return;
        }

        string connection = $"{game.host}:{game.external_port}";

        foreach (string playerId in playerIds)
        {
            if (!string.IsNullOrEmpty(playerId))
                _playfab.UpdatePlayerData(titleSecret, playerId, matchId, connection);
        }
    }

    [Serializable]
    private class PlayFlowPort
    {
        public string name;
        public int external_port;
        public string host;
        public string protocol;
        public bool tls_enabled;
    }
}
```

The PlayFab write itself is unchanged from any PlayFab server integration — authenticate with the Title Secret and call `Server/UpdateUserData`:

```csharp PlayfabRestApiService.cs (server) theme={null}
public async void UpdatePlayerData(string secretKey, string playerId, string key, string value)
{
    if (!_http.DefaultRequestHeaders.Contains("X-SecretKey"))
        _http.DefaultRequestHeaders.Add("X-SecretKey", secretKey);

    var data = new JObject { [key] = value };
    var body = new JObject { ["PlayFabId"] = playerId, ["Data"] = data };

    var content  = new StringContent(body.ToString(), Encoding.UTF8, "application/json");
    var response = await _http.PostAsync($"https://{TitleID}.playfabapi.com/Server/UpdateUserData", content);

    if (!response.IsSuccessStatusCode)
        Debug.Log($"Could not update Player Data for {playerId}: {(int)response.StatusCode}");
}
```

## Step 5 — Connect from the client

The client side is **pure PlayFab** and identical to any PlayFab matchmaking integration — PlayFlow isn't involved until the client reads the address. The flow:

<Steps>
  <Step title="Log in">
    Authenticate the player with PlayFab (for example `LoginWithCustomID`) and store the entity + session tokens.
  </Step>

  <Step title="Create a ticket">
    Call `Match/CreateMatchmakingTicket` on your queue and keep the returned ticket ID.
  </Step>

  <Step title="Wait for a match">
    Poll `Match/GetMatchmakingTicket` every few seconds until `Status` is `Matched`, then store the `MatchId`.
  </Step>

  <Step title="Read the address & connect">
    Poll `Client/GetUserData` with the `MatchId` as the key until the server has written it, then set your transport's address/port and connect. Retry for a few seconds — the server writes Player Data the moment it boots, which is typically a few seconds after the match.
  </Step>
</Steps>

```csharp Reading the address and connecting (client) theme={null}
private async void StartConnectionAttempt()
{
    var body = new JObject { ["Keys"] = new JArray { _matchId } };
    var content = new StringContent(body.ToString(), Encoding.UTF8, "application/json");

    while (true)
    {
        var res  = await _http.PostAsync($"https://{TitleID}.playfabapi.com/Client/GetUserData", content);
        var json = JObject.Parse(await res.Content.ReadAsStringAsync());
        var data = json["data"]?["Data"];

        var entry = data?[_matchId]?["Value"]?.ToString();
        if (!string.IsNullOrEmpty(entry))
        {
            string address = entry.Split(':')[0];
            if (ushort.TryParse(entry.Split(':')[1], out ushort port))
            {
                InstanceFinder.TransportManager.Transport.SetClientAddress(address);
                InstanceFinder.TransportManager.Transport.SetPort(port);
                InstanceFinder.ClientManager.StartConnection();
            }
            return;
        }

        await Task.Delay(3000); // server not ready yet — retry
    }
}
```

<Tip>
  Have the client remove its match entry from Player Data once connected (`Client/UpdateUserData` with `KeysToRemove`) so stale connection info doesn't accumulate.
</Tip>

## Step 6 — Build, upload, and test

<Steps>
  <Step title="Build a headless Linux server">
    Produce a dedicated Linux server build with your netcode configured to start on headless and listen on the internal port that matches your PlayFlow port config.
  </Step>

  <Step title="Upload it to PlayFlow">
    Upload the build under the same **name** you referenced as `PlayFlow_BuildName` in the CloudScript (`space-edge` here). See [Docker builds](/guides/docker-builds).
  </Step>

  <Step title="Run two clients">
    Launch two PlayFab-authenticated clients and start matchmaking on both. When PlayFab matches them, your rule fires, PlayFlow boots the server, the server publishes its address, and both clients connect to the same deployment.
  </Step>
</Steps>

## Why this works well on PlayFlow

* **The server is handed its own public address.** `PLAYFLOW_PORTS` contains the resolved `host` and `external_port` for every named port — no self-lookup or metadata call required.
* **Readiness is automatic.** Because the server writes Player Data in `OnStartServer`, connection info only appears once the process is actually up. Clients that poll can't grab a dead address.
* **The server can talk back to PlayFlow.** `PLAYFLOW_API_KEY` and `PLAYFLOW_API_URL` are injected too, so the server can stop itself when the match ends (`DELETE /api/v3/servers/{instance_id}`) or update its own metadata — no extra secrets to manage.
* **Set a TTL as a safety net.** Pass a `ttl` (seconds) on `POST /servers/start` so an abandoned match can't leave a server running forever. See the [API reference](/fundamentals/api).

<Info>
  When you're ready to simplify further, PlayFlow's [native matchmaking](/lobbies/matchmaking) removes the PlayFab round-trip entirely — the matchmaker launches the server and hands the connection details straight to your players over a real-time channel.
</Info>


# Pool Servers
Source: https://docs.playflowcloud.com/guides/pool-servers

Pre-warmed game servers to reduce launch latency (upcoming feature).

# Pool Servers

<Warning>
  **Pool servers are not currently available.** This feature is in active development. Today, every server cold-starts on demand — there are no pre-warmed standby servers, no instant claim, and no idle billing discount, regardless of any `pool_config` you set. This page describes how pool servers are intended to work once the feature ships. Nothing on this page functions at runtime yet.
</Warning>

Pool servers are a planned feature: pre-provisioned game servers that sit warm and ready to be claimed, so you can skip the on-demand launch wait when a match is found. This is intended for competitive matchmaking and any game where launch latency matters.

Until pool servers ship, use the standard on-demand [server start](/fundamentals/api) flow — every server is created fresh on each start.

## How Pool Servers Will Work

<Info>
  The flow below describes the intended design. None of these steps run today — the pool system is disabled, so configuration is stored but no standby servers are provisioned or claimed.
</Info>

<Steps>
  <Step title="Configure your pool">
    In your project settings, you define which regions and compute sizes you want pre-provisioned, and how many servers to keep warm in each.
  </Step>

  <Step title="PlayFlow provisions servers">
    PlayFlow launches and maintains the configured number of idle servers. These servers are running and ready to accept players, but are not yet assigned to any game session.
  </Step>

  <Step title="Claim a server">
    When your game needs a server (for example, when matchmaking finds a match), you claim a pool server via the API. The claimed server becomes yours and you receive its connection details in the response, skipping the on-demand launch wait.
  </Step>

  <Step title="Pool replenishes automatically">
    After a server is claimed, PlayFlow launches a replacement to maintain your configured capacity. A reconciliation process keeps the pool at the target size.
  </Step>
</Steps>

<Info>
  Pool servers are designed to use the same infrastructure and runtime environment as on-demand servers. The only difference is that they are pre-launched and waiting.
</Info>

## Configuring Your Pool

Pool configuration is stored via the project settings endpoint. (Storing it has no runtime effect today — no standby servers are provisioned until the feature ships.)

<Info>
  Updating project settings requires a **server key** (`pf_...`). Client keys (`pfclient_...`) receive a `403`. Keep server keys server-side and never ship them in a game build.
</Info>

Use the project settings endpoint to configure your pool programmatically:

```bash theme={null}
curl -X POST https://api.computeflow.cloud/api/v3/projects/settings \
  -H "api-key: pf_YOUR_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pool_config": {
      "enabled": true,
      "regions": {
        "us-east": {
          "small": 3,
          "medium": 2
        },
        "eu-west": {
          "small": 2
        }
      }
    }
  }'
```

### Configuration Reference

The `pool_config` object has the following structure:

| Field                 | Type    | Description                                                        |
| :-------------------- | :------ | :----------------------------------------------------------------- |
| `enabled`             | boolean | Whether pool provisioning is active for this project.              |
| `regions`             | object  | A map of region IDs to compute size configurations.                |
| `regions.<region_id>` | object  | A map of compute size names to the number of servers to keep warm. |

<Tabs>
  <Tab title="Single Region">
    Keep 3 small servers warm in US East:

    ```json theme={null}
    {
      "pool_config": {
        "enabled": true,
        "regions": {
          "us-east": {
            "small": 3
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Multi-Region">
    Spread warm servers across multiple regions for global coverage:

    ```json theme={null}
    {
      "pool_config": {
        "enabled": true,
        "regions": {
          "us-east": {
            "small": 3,
            "medium": 2
          },
          "eu-west": {
            "small": 2
          },
          "ap-north": {
            "small": 1
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Disable Pool">
    To disable the pool and stop provisioning idle servers:

    ```json theme={null}
    {
      "pool_config": {
        "enabled": false,
        "regions": {}
      }
    }
    ```
  </Tab>
</Tabs>

## Claiming a Pool Server

Once pool servers ship, you will start a server exactly as you do today via `POST /api/v3/servers/start`. If a matching pool server is available in the requested region and compute size, PlayFlow will assign it rather than launching a new machine. **Today this always launches a fresh on-demand server** — the request below is the standard start call and works now; the pool fast-path is what will change once the feature is enabled.

`name` and `region` are required. Select a build with `version_tag` (the build **name**) and optional `version`. There is no `build_id` field on server start.

```bash theme={null}
curl -X POST https://api.computeflow.cloud/api/v3/servers/start \
  -H "api-key: pf_YOUR_SERVER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ranked-1",
    "region": "us-east",
    "version_tag": "default",
    "compute_size": "small"
  }'
```

Read the connection details from the response: use the `host` and `external_port` of each entry in `network_ports[]` rather than hardcoding a host or port. The proxy-allocated `external_port` differs from your internal port — never assume `7777` or any fixed value.

When pool servers are eventually claimed, the response will additionally set `pool_claimed_at` and `is_pool_server: true` on the server record.

<Info>
  When pool servers are available and none matches the requested region and size, PlayFlow will fall back to launching a new server on demand. Your game logic does not need to handle this distinction — the API response format is the same either way.
</Info>

## Identifying Pool Servers

Once the feature ships, pool servers will be visible in the server list alongside on-demand servers, identifiable by the `is_pool_server` field:

```bash theme={null}
curl https://api.computeflow.cloud/api/v3/servers \
  -H "api-key: pf_YOUR_SERVER_KEY"
```

<Info>
  While pooling is disabled, these fields stay dormant: every server is a cold-create, so `is_pool_server` is always `false` and `pool_claimed_at` is always `null`.
</Info>

In the response, pool servers will include:

| Field             | Description                                                                              |
| :---------------- | :--------------------------------------------------------------------------------------- |
| `is_pool_server`  | `true` for servers provisioned by the pool system.                                       |
| `pool_claimed_at` | Timestamp when the server was claimed. `null` if the server is still idle and unclaimed. |

## Billing

Because pool servers do not run today, there is no separate pool billing. Every server you launch is an on-demand server billed at the standard rate for its compute size.

The billing model for pooled standby servers has not been finalized and will be documented here when the feature ships.

See [Pricing & Instance Types](/fundamentals/plan-instance-types) for the standard rates by compute size.

## Limits

* **Maximum 10 servers** per region per compute size in the pool configuration
* Pool reconciliation will run automatically to provision or remove servers to match the target count (not active while the feature is disabled)
* Pool servers will follow the same plan limits as on-demand servers (Free plan: max 1 active server; Pro plan: unlimited servers)

## When Pool Servers Will Help

<Tabs>
  <Tab title="Good Fit">
    * **Competitive matchmaking** where fast server availability is critical
    * **High-traffic games** with frequent match starts and predictable demand
    * **Tournament or event systems** where matches need to start promptly
    * **Games with short session times** where launch latency is a significant fraction of playtime
  </Tab>

  <Tab title="May Not Need">
    * **Low-traffic games** where the on-demand launch wait is acceptable
    * **Development and testing** where launch speed is not a priority
    * **Long-session games** (e.g., survival or sandbox) where the initial startup time is negligible relative to session length
  </Tab>
</Tabs>

***

## Next Steps

<CardGroup>
  <Card title="Server Regions" icon="globe" href="/fundamentals/regions">
    Choose regions for your pool based on where your players are located.
  </Card>

  <Card title="Pricing & Instance Types" icon="credit-card" href="/fundamentals/plan-instance-types">
    Review compute sizes and pricing to plan your pool configuration.
  </Card>
</CardGroup>


# Deploy from Unity Matchmaker
Source: https://docs.playflowcloud.com/guides/ugs-matchmaker

Keep your Unity Game Services (UGS) Matchmaker and deploy the match servers to PlayFlow via a custom allocator.

Follow this guide if you want to keep the **Unity Game Services (UGS) Matchmaker** and use **PlayFlow** as your server host. When the matchmaker assembles a match, a small Cloud Code **allocator** you deploy calls PlayFlow to start a server and returns the connection details to the matched players.

<Info>
  Prefer an all-in-one path? PlayFlow has native [matchmaking](/lobbies/matchmaking) with [Unity SDK support](/unity/matchmaking) — no UGS required. Use this guide when you specifically want to keep the Unity Matchmaker.
</Info>

Before getting started, we expect that:

* You have a working UGS Matchmaker setup. Refer to [Unity's Matchmaker documentation](https://docs.unity.com/ugs/manual/matchmaker/manual/matchmaker-overview) for matchmaking topics.
* You have a PlayFlow project and an uploaded **dedicated Linux server build**. See [Docker builds](/guides/docker-builds).

<Warning>
  Unlike Multiplay, there is no pre-built "PlayFlow allocator" in Unity's hosting-providers repo — you author a small Cloud Code allocator (below). It's just an HTTP call to PlayFlow, so this stays a lightweight, fully custom integration.
</Warning>

## How it works

<Steps>
  <Step title="Matchmaker assembles a match">
    UGS Matchmaker groups players and invokes your allocator Cloud Code function with the matched player list.
  </Step>

  <Step title="Allocator starts a PlayFlow server">
    Your allocator calls `POST /api/v3/servers/start`. PlayFlow reserves the ports immediately and returns the `instance_id` and `network_ports`.
  </Step>

  <Step title="Allocator publishes the assignment">
    The allocator waits for the server to reach `running`, then stores the `host:port` for the match (in UGS Cloud Save / your game data) keyed so the matched players can find it.
  </Step>

  <Step title="Clients connect">
    Each client retrieves its assignment and connects.
  </Step>
</Steps>

## Step 1 — Store your PlayFlow key as a UGS secret

In the [Unity Cloud dashboard](https://cloud.unity.com/), under **Administration → Secrets**, add:

* `PLAYFLOW_API_KEY` — a PlayFlow **server key** (`pf_...`) from your project's API Keys.

The allocator runs in Cloud Code (server-side), so the key is never exposed to clients.

## Step 2 — Region selection

Edgegap places servers from player IP addresses; **PlayFlow takes an explicit `region`** instead (one of [13](/fundamentals/regions)) — there is no IP-based placement.

Have each player attach a coarse location or preferred region as **matchmaking ticket custom data**, then pick a region in the allocator:

```csharp Attach region hint to the ticket theme={null}
var ticketOptions = new CreateTicketOptions(
    queueName: "my-queue",
    attributes: new Dictionary<string, object>
    {
        { "region_hint", "us-east" } // or a lat/long your allocator maps to a region
    }
);
```

<Info>
  If you send lat/long instead of a region name, reuse the `nearestRegion()` helper from the [PlayFab Bridge guide](/guides/playfab-bridge) to map the match's average location to one of PlayFlow's regions.
</Info>

## Step 3 — The allocator

Deploy a Cloud Code function that the matchmaker calls when a match is assembled. Its PlayFlow responsibilities are:

1. Start a server with the matched players and chosen region.
2. Wait until the server is `running`.
3. Store the connection details so clients can look them up.

The PlayFlow calls are identical to any REST client:

```javascript Allocator (Cloud Code) — PlayFlow calls theme={null}
const PLAYFLOW_API = "https://api.computeflow.cloud/api";

async function startPlayFlowServer({ apiKey, region, buildName, matchId, playerIds }) {
  // 1. Start the server
  const start = await fetch(`${PLAYFLOW_API}/v3/servers/start`, {
    method: "POST",
    headers: { "api-key": apiKey, "Content-Type": "application/json" },
    body: JSON.stringify({
      name: `match-${matchId}`,
      region,
      version_tag: buildName,          // the build NAME you uploaded
      ttl: 3600,                       // safety net
      environment_variables: {
        UGS_MATCH_ID: matchId,
        UGS_PLAYER_IDS: playerIds.join(","),
      },
    }),
  }).then((r) => r.json());

  // 2. Wait for the server to be ready
  let instance = start;
  while (instance.status !== "running") {
    await new Promise((res) => setTimeout(res, 2000));
    instance = await fetch(`${PLAYFLOW_API}/v3/servers/${start.instance_id}`, {
      headers: { "api-key": apiKey },
    }).then((r) => r.json());
    if (instance.status === "stopped") throw new Error("Server failed to start");
  }

  // 3. Return the public address of the "game" port
  const game = instance.network_ports.find((p) => p.name === "game");
  return {
    instanceId: instance.instance_id,
    host: game.host,
    port: game.external_port,
  };
}
```

<Tip>
  Because PlayFlow returns `network_ports` **synchronously** from the start call, you don't need Edgegap's deployment-id-plus-webhook dance. The only wait is for `status` to flip to `running`. For very high match rates, kick off the poll asynchronously and store the assignment when it completes rather than blocking the allocator.
</Tip>

Store `{ host, port, instanceId }` against the match (UGS Cloud Save, a database, or the matchmaker's assignment results) so the matched players — looked up by `UGS_PLAYER_IDS` — can retrieve it.

<Info>
  For the **UGS-side contract** — how your allocator is registered, invoked by the matchmaker, and how assignment results are returned to clients — follow Unity's official [hosting-providers allocator template](https://github.com/Unity-Technologies/matchmaker-hosting-providers). This guide only covers the PlayFlow calls that go inside it.
</Info>

## Step 4 — Retrieve the assignment on the client

Clients fetch their assignment (via the matchmaker's standard assignment flow or by reading the game data your allocator wrote), then connect their transport to `host:port`:

```csharp Connect once assigned theme={null}
InstanceFinder.TransportManager.Transport.SetClientAddress(host);
InstanceFinder.TransportManager.Transport.SetPort(port);
InstanceFinder.ClientManager.StartConnection();
```

## Step 5 — Clean up

When the match ends, terminate the server so you stop paying for it:

```bash Terminate the server theme={null}
curl -X DELETE "https://api.computeflow.cloud/api/v3/servers/<instance_id>?shutdown_reason=MATCH_ENDED" \
  -H "api-key: pf_your_server_key"
```

The server can also stop itself — PlayFlow injects `PLAYFLOW_API_KEY`, `PLAYFLOW_API_URL`, and `PLAYFLOW_INSTANCE_ID` into the container, so your headless build can call `DELETE /v3/servers/$PLAYFLOW_INSTANCE_ID` when the last player disconnects. Setting a `ttl` at start time guarantees cleanup even if nothing calls delete.


# Unity Modules Setup
Source: https://docs.playflowcloud.com/guides/unity-modules

Install the required Unity modules to build dedicated servers for PlayFlow.

# Unity Modules Setup

To build **Unity dedicated servers** for PlayFlow, you need to install specific Linux build modules. PlayFlow deploys servers on Linux infrastructure, so these modules are essential for creating compatible server builds.

<Warning>
  Without the proper Linux modules installed, Unity will not be able to build dedicated servers for PlayFlow deployment.
</Warning>

## Prerequisites

* **Unity Hub** installed, so you can add build modules to your Unity installation.
* The **PlayFlow Unity SDK** installed in your project (see below).

## Install the PlayFlow Unity SDK

First, make sure you have the PlayFlow Unity SDK installed. The recommended method is the Unity Package Manager Git URL:

```
https://github.com/PlayFlowCloud/PlayFlow-Multiplayer-Unity-SDK.git
```

<CardGroup>
  <Card title="Installation Guide" icon="download" href="/guides/installation">
    Step-by-step instructions for installing the PlayFlow Unity SDK via the Package Manager Git URL
  </Card>
</CardGroup>

## Required Unity Modules by Version

The modules you need depend on your Unity version. Install the appropriate Linux build support modules:

### Unity 2021.2 and Above

For Unity 2021.2+, install these modules through Unity Hub:

<img alt="Unity 2021.2+ Linux Modules" />

**Required Modules:**

* **Linux Build Support (IL2CPP)** - Essential for Linux server builds
* **Linux Build Support (Mono)** - Alternative scripting backend support

### Unity 2020.x and Earlier

For Unity versions older than 2021.2, install these modules:

<img alt="Unity 2020 Linux Modules" />

**Required Modules:**

* **Linux Build Support** - Core Linux build capability
* **Linux Build Support (IL2CPP)** - IL2CPP scripting backend
* **Linux Build Support (Mono)** - Mono scripting backend

<Note>
  Unity versions older than 2021.2 have different module names but serve the same purpose for Linux server builds.
</Note>

## How to Install Unity Modules

### Via Unity Hub

1. Open **Unity Hub**
2. Go to **Installs** tab
3. Click the **gear icon** next to your Unity version
4. Select **Add Modules**
5. Check the **Linux Build Support** options shown above
6. Click **Install**

### Via Unity Editor

1. Open Unity Editor
2. Go to **File → Build Settings**
3. Select **Linux** as target platform
4. If modules are missing, Unity will prompt you to install them
5. Click **Install with Unity Hub**

## Verify Installation

To confirm your modules are installed correctly:

1. Open **File → Build Settings**
2. You should see **Linux** available in the Platform list
3. Select Linux and click **Switch Platform**
4. If successful, you're ready to build dedicated servers

***

## Next Steps

Once your Unity modules are properly installed, you're ready to build and deploy your first server:

<CardGroup>
  <Card title="Quick Start Guide" icon="rocket" href="/quickstart/index">
    Build and deploy your first dedicated server with PlayFlow
  </Card>
</CardGroup>

<CardGroup>
  <Card title="Installation Guide" icon="download" href="/guides/installation">
    Complete PlayFlow setup instructions
  </Card>
</CardGroup>

<CardGroup>
  <Card title="WebGL Deployments" icon="globe" href="/guides/webgl-deployments">
    Deploy browser-based multiplayer games
  </Card>

  <Card title="What's New in PlayFlow 2" icon="sparkles" href="/guides/whats-new-playflow-2">
    Explore new features and improvements
  </Card>
</CardGroup>


# WebGL Deployments
Source: https://docs.playflowcloud.com/guides/webgl-deployments

Learn how to configure your servers to accept connections from WebGL clients.

# WebGL Deployments

To allow players to connect to your game servers from web-based games (WebGL), you must configure your server's network port to accept secure connections. The process is simple and only requires enabling one extra setting.

<Info>
  **Prerequisites**

  * A PlayFlow project with a build uploaded and ready
  * Access to the project **Settings** page in the dashboard
  * A WebGL client that connects over WebSockets
</Info>

## The Key Requirement: TCP with TLS

Web browsers require secure WebSocket connections (`wss://`) for WebGL games. To enable this, set your game server's port to use the **TCP** protocol and turn on the separate **TLS** option for that port.

<Warning>
  If your port uses `UDP`, or uses `TCP` without TLS enabled, WebGL clients will not be able to connect over `wss://`.
</Warning>

## How to Configure Your Server for WebGL

Follow these steps in your PlayFlow project dashboard:

<Steps>
  <Step title="Open Network Ports">
    Open the project **Settings** page in your dashboard and find the **Network Ports** section (under **Configuration**).
  </Step>

  <Step title="Set the protocol to TCP">
    For the port your game server uses, set the **Protocol** to **TCP**. The protocol control is a toggle between **UDP** and **TCP**.
  </Step>

  <Step title="Enable TLS">
    With TCP selected, a separate **TLS** checkbox appears for that port. Enable it.

    For example, if your server listens on port `8080`, your configuration should be:

    * **Port:** `8080`
    * **Protocol:** `TCP`
    * **TLS:** enabled
  </Step>

  <Step title="Save and Deploy">
    Save your configuration. Any new servers you deploy for this project will now support WebGL connections.
  </Step>
</Steps>

## How It Works

You don't need to change your server code. Your game server can continue to listen for unencrypted TCP traffic on its port. PlayFlow automatically handles the TLS encryption and termination at our infrastructure level.

* **Your WebGL Client:** Connects to a secure `wss://` address.
* **PlayFlow Infrastructure:** Receives the secure connection, handles the TLS, and forwards the traffic to your server as standard TCP.
* **Your Game Server:** Receives standard TCP traffic, no TLS implementation needed.

## Client-Side Connection

PlayFlow does not hand you a ready-made `wss://` URL — you build it from the connection details of your running server.

Read the connection host and port from the server's API response (`GET /api/v3/servers/{id}`), from the `network_ports[]` array. Each entry includes the public `host` and the proxy-allocated `external_port`. These values are also shown on the server's detail page in the dashboard as a copyable `host:port` value, with a shield indicator when TLS is enabled.

<Warning>
  The external port is allocated by the proxy and differs from the internal port your server listens on. Never hardcode a port — always read `external_port` from the response.
</Warning>

Construct your WebGL client's connection URL as:

```text theme={null}
wss://<host>:<external_port>
```

***

## Next Steps

<CardGroup>
  <Card title="Quick Start Guide" icon="rocket" href="../quickstart">
    Deploy your first game server.
  </Card>

  <Card title="Installation Guide" icon="download" href="installation">
    Review the setup and installation process.
  </Card>
</CardGroup>


# What's New in PlayFlow 2
Source: https://docs.playflowcloud.com/guides/whats-new-playflow-2

Discover the powerful new features and improvements in PlayFlow 2 that make multiplayer game development easier than ever.

# What's New in PlayFlow 2

PlayFlow 2 represents a major leap forward in multiplayer game server management. We've rebuilt our platform from the ground up to deliver better performance, more features, and an even simpler developer experience.

## [Lobby & Matchmaking](#lobby-matchmaking-sdk)

PlayFlow 2 introduces **built-in lobbies and matchmaking** - the feature game developers have been asking for most. It's a backend feature you access through the v3 REST API, and (for Unity projects) through the first-class Unity SDK.

<CardGroup>
  <Card title="Built-in Matchmaking" icon="target">
    Configurable matchmaking with rule-based player matching (difference, equals, not\_equals, region, and expression rules)
  </Card>

  <Card title="Player Authentication" icon="shield-check">
    Verified player identity via custom JWT, PlayFab, or Steam providers
  </Card>
</CardGroup>

### What you get

The lobby and matchmaking system provides:

* **Lobby management** for player groups and game sessions, with public and invite-code private lobbies
* **Rule-based matchmaking** with configurable rules and regions
* **Player authentication** with custom JWT, PlayFab, and Steam providers
* **Real-time lobby state** streamed to clients over a one-way SSE event stream
* **Automatic server allocation** when a match is ready

<Note>
  The backend is engine-agnostic REST, so any client that can speak HTTP can use it. Unity is the first-class SDK; other engines integrate directly against the REST API. See the [lobby & matchmaking guide](/lobbies/matchmaking) and the [API reference](/fundamentals/api).
</Note>

## [Enhanced Performance & Infrastructure](#enhanced-performance-infrastructure)

PlayFlow 2 delivers significantly better performance without increasing costs.

<CardGroup>
  <Card title="Faster Compute Instances" icon="zap">
    Access to upgraded server hardware with better CPU performance and memory
  </Card>

  <Card title="Same Great Pricing" icon="dollar-sign">
    All performance improvements come at no additional cost to you
  </Card>
</CardGroup>

### New Orchestrator Technology

Our **brand new orchestrator** has been built from the ground up to provide:

* **Global deployment** across 13 regions worldwide, from us-east and eu-west to ap-south and south-america-brazil
* **On-demand provisioning** — servers launch when you call the API and shut down on their TTL, so you only pay for what you run
* **Improved reliability** with better error handling and recovery

<Warning>
  `region` is required when you start a server. Choose the region closest to your players for the lowest latency. See [Instance Types](/fundamentals/plan-instance-types) for the full region and compute-size list.
</Warning>

## [Built-in Monitoring & Logging](#built-in-monitoring-logging)

No more juggling multiple tools. PlayFlow 2 includes comprehensive monitoring and logging right out of the box.

<CardGroup>
  <Card title="Centralized Logging" icon="file-text">
    All server logs are automatically collected and searchable from your dashboard
  </Card>

  <Card title="Performance Monitoring" icon="activity">
    Real-time metrics and performance dashboards for all your servers
  </Card>
</CardGroup>

Monitor everything in one place:

* **Server performance metrics** (CPU, memory, network)
* **Player connection statistics** and session data
* **Error tracking** and debugging information
* **Custom logging** from your game server applications

## [Unlimited Projects & Build Management](#unlimited-projects-build-management)

Say goodbye to project limitations. PlayFlow 2 lets you create **unlimited projects** to organize your games exactly how you want.

<CardGroup>
  <Card title="Unlimited Projects" icon="folder">
    Create as many projects as you need to categorize your different games and experiments
  </Card>

  <Card title="Build Preservation" icon="archive">
    All your builds are automatically preserved with full version history
  </Card>
</CardGroup>

Perfect for:

* **Multiple game titles** under one organization
* **Experimental projects** and prototypes
* **Different game versions** (mobile, PC, console)
* **Build archiving** for long-term project maintenance

## [Organizations & Team Collaboration](#organizations-team-collaboration)

PlayFlow 2 introduces **Organizations** - a powerful way to manage your game development teams and projects.

<CardGroup>
  <Card title="Team Management" icon="users">
    Easily add and remove team members from your organization with role-based access control
  </Card>

  <Card title="Collaborative Development" icon="handshake">
    All team members can access and contribute to projects within your organization
  </Card>
</CardGroup>

With organizations, you can:

* **Invite team members** by email and manage their access
* **Share projects** across your entire development team
* **Centralize billing** and resource management
* **Maintain consistent workflows** across all your game projects

<Note>
  Organizations make it easy to scale your team from solo development to large studios, all while maintaining security and access control.
</Note>

## [Designed for Scale](#designed-for-scale)

Whether you're running a single test server or managing thousands of concurrent game sessions, PlayFlow 2 scales with your needs.

<CardGroup>
  <Card title="Solo Developers" icon="user">
    Perfect for indie developers just getting started with multiplayer
  </Card>

  <Card title="Growing Studios" icon="trending-up">
    Seamlessly scales as your player base and team expand
  </Card>

  <Card title="Enterprise Gaming" icon="building">
    Launch as many servers as you need on demand — start each one with a single API call
  </Card>
</CardGroup>

<Info>
  You launch and stop game servers on demand through the API (or dashboard) — there is no fleet autoscaler to configure. Your game or backend decides when to start a server and when to shut it down.
</Info>

### Simplified Experience

Despite all these powerful features, PlayFlow 2 remains the **easiest way to get started** with multiplayer game development:

* **Start servers with a single API call** and have them running in minutes
* **Intelligent defaults** handle complex configuration for you (`compute_size` defaults to `small`)
* **Clear documentation** and examples for every feature
* **Intuitive dashboard** that grows with your expertise

## [Migration from Previous Versions](#migration-from-previous-versions)

Existing PlayFlow users can easily migrate to take advantage of all these new features:

<CardGroup>
  <Card title="Migration Guide" icon="arrow-right" href="/guides/migration-guide">
    Follow the step-by-step guide to move your builds and configurations to PlayFlow 2
  </Card>

  <Card title="Zero Downtime" icon="clock">
    Migrate your servers without interrupting your players
  </Card>
</CardGroup>

## [Get Started with PlayFlow 2](#get-started-with-playflow-2)

Ready to experience the future of multiplayer game development?

<CardGroup>
  <Card title="Quick Start Guide" icon="rocket" href="/quickstart">
    Deploy your first PlayFlow 2 server in under 10 minutes
  </Card>

  <Card title="Join Our Community" icon="message-circle" href="https://discord.gg/P5w45Vx5Q8">
    Connect with other developers and get support on Discord
  </Card>
</CardGroup>

<CardGroup>
  <Card title="API Documentation" href="/fundamentals/api">
    <Icon icon="code" />
  </Card>

  <Card title="Unity Integration" href="/guides/unity-modules">
    <Icon icon="unity" />
  </Card>

  <Card title="Instance Types" href="/fundamentals/plan-instance-types">
    <Icon icon="server" />
  </Card>
</CardGroup>

***

**PlayFlow 2** - Building the future of multiplayer gaming, one server at a time.


# PlayFlow Documentation
Source: https://docs.playflowcloud.com/index

Deploy, manage, and scale multiplayer game servers globally with PlayFlow.

<div>
  <div>
    <h1>
      Welcome to PlayFlow 👋
    </h1>

    <p>
      Welcome to the official documentation for PlayFlow, the easiest way to build, deploy, and scale multiplayer games globally. Learn how to create engaging multiplayer experiences and bring your game ideas to life.
    </p>
  </div>

  <div>
    <img alt="PlayFlow Logo" />
  </div>
</div>

***

<CardGroup>
  <Card href="/quickstart" icon="rocket">
    <h3>Get Started</h3>
    <p>Make your first server deployment in minutes.</p>
  </Card>

  <Card href="/api-reference/introduction" icon="code">
    <h3>API Reference</h3>
    <p>Integrate and scale using our API and SDKs.</p>
  </Card>

  <Card href="https://app.playflowcloud.com" icon="layout-grid">
    <h3>Dashboard</h3>
    <p>Manage servers and monitor players directly in your browser.</p>
  </Card>

  <Card href="/guides/whats-new-playflow-2" icon="star">
    <h3>What's New</h3>
    <p>Learn about changes and new features in PlayFlow.</p>
  </Card>

  <Card href="/guides/migration-guide" icon="git-branch">
    <h3>Migration Guide</h3>
    <p>Upgrade to the latest version of the PlayFlow SDK.</p>
  </Card>

  <Card href="/unity/index" icon="cuboid">
    <h3>Unity SDK</h3>
    <p>Explore the features and capabilities now available in PlayFlow.</p>
  </Card>
</CardGroup>

<div>
  <h3>Join thousands of developers building on PlayFlow</h3>

  <p>
    Get help, share your games, and connect with other multiplayer developers
  </p>

  <a href="https://discord.gg/P5w45Vx5Q8">
    <Icon icon="discord" /> Join our Discord Community
  </a>
</div>


# Introduction
Source: https://docs.playflowcloud.com/introduction

The easiest way to host and scale dedicated servers for your multiplayer game. Any engine, any networking library.

# Multiplayer Servers, Made Simple.

**You build the game. PlayFlow runs the servers.**

Stop wrestling with complex infrastructure. PlayFlow is a platform that automatically hosts and scales your game's dedicated servers, letting you turn any game into a global multiplayer hit.

<CardGroup>
  <Card title="Any Game Engine" icon="gamepad-2">
    A first-class Unity SDK, plus any engine — Godot, Unreal, or your own — via the REST API.
  </Card>

  <Card title="Any Networking" icon="network">
    Use FishNet, Mirror, Netcode, or any transport with a dedicated Linux server build.
  </Card>

  <Card title="Global & Scalable" icon="globe">
    Deploy across 13 regions on 6 continents and scale from 10 to 100,000+ players.
  </Card>
</CardGroup>

## What PlayFlow Does For You

PlayFlow provides the essential backend services that every multiplayer game needs, right out of the box.

<CardGroup>
  <Card title="On-Demand Server Deployment" icon="server">
    Upload your game build, and we handle the rest. Launch servers on demand, close to your players.
  </Card>

  <Card title="Launch Per Match" icon="trending-up">
    Spin up servers exactly when you need them — one per match via matchmaking, or programmatically via the API — with no idle capacity to manage.
  </Card>

  <Card title="Lobbies & Matchmaking" icon="users">
    Use our pre-built, customizable system to let players group up and find fair, low-latency matches.
  </Card>

  <Card title="Persistent Worlds" icon="castle">
    Run your servers 24/7 for MMOs, survival games, or any always-online experience.
  </Card>
</CardGroup>

<Info>
  **Bring Your Own Netcode.** PlayFlow is not a networking library. It's a hosting platform that works with the tools you already know and love. You have full control over your game's code.
</Info>

## Ready to Get Started?

<CardGroup>
  <Card title="Quick Start Guide" icon="play" href="/quickstart">
    Deploy your first server in under 10 minutes and see how simple it is.
  </Card>

  <Card title="Join Our Community" icon="discord" href="https://discord.gg/P5w45Vx5Q8">
    Connect with thousands of developers, from hobbyists to studio teams.
  </Card>
</CardGroup>


# Backfill
Source: https://docs.playflowcloud.com/lobbies/backfill

Route newly-queued players into a running match with open slots instead of always launching a new server — engine-managed, with an authoritative roster your game server polls to admit players.

Backfill routes a newly-queued lobby into an **already-running match that has open slots** instead of always spinning up a fresh server. Players skip the launch wait and drop straight into a game in progress — ideal for battle royale late-join, persistent arenas, drop-in co-op, and any mode where a half-full match is better filled than a new one is started.

<Info>
  **A match is a group of lobbies sharing one server.** Backfill adds *more* lobbies to that same `matchId` and the same running server, up to the match's capacity (`teams × playersPerTeam`).
</Info>

***

## The engine-authoritative hybrid model

PlayFlow runs backfill as an **engine-authoritative hybrid**:

* **The engine owns backfill by default.** When a lobby queues for a backfill-enabled mode, the matcher first looks for a compatible open match. If it finds one, the lobby joins that running server; if not, it forms a fresh match as usual. The engine tracks capacity, per-team slots, the skill band, and the backfill window — you don't have to.
* **Your game server admits players from an authoritative roster.** The engine maintains the single source of truth for who belongs in the match. Your server polls `GET /v3/servers/{instance_id}/roster` and admits connecting players against it. This is what fixes reconnect / "denied by proxy" edge cases — the roster, not the server's local memory, decides admission.
* **Advanced servers can optionally take control.** A server that knows better when it can accept joiners (e.g., only between rounds) can open, close, or re-scope backfill itself via `PATCH /v3/servers/{instance_id}/backfill` and `POST /v3/servers/{instance_id}/backfill/lock`.

You get real backfill for free by flipping one config flag. You reach for the server-authoritative controls only when you need them.

***

## Enabling backfill

Backfill is configured per matchmaking mode in your **lobby config**. Add a `backfill` object to the mode:

```json theme={null}
{
  "matchmaking": {
    "modes": {
      "5v5": {
        "teams": 2,
        "playersPerTeam": 5,
        "minPlayersPerTeam": 3,
        "timeout": 120,
        "maxPartySize": 5,
        "backfill": {
          "enabled": true,
          "windowSeconds": 300,
          "closeWhenFull": true,
          "skill": { "field": "mmr", "maxDifference": 150 }
        }
      }
    }
  }
}
```

### `backfill` fields

| Field           | Type        | Default | Description                                                                                                                       |
| :-------------- | :---------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`       | boolean     | —       | Master switch. When `true`, newly-queued lobbies can join an open match before a fresh server is launched.                        |
| `windowSeconds` | integer ≥ 1 | `300`   | How long after a match forms it stays open to joiners. After this window the match closes to backfill.                            |
| `closeWhenFull` | boolean     | `true`  | Close backfill automatically once the match reaches capacity.                                                                     |
| `skill`         | object      | `null`  | Optional skill gate. A joining lobby's average value on `field` must be within `maxDifference` of the running match's skill band. |

<Warning>
  Backfill only runs for modes where `enabled` is `true`. Modes without a `backfill` object behave **exactly as before** — no backfill path executes for them.
</Warning>

### Deprecated: `allowBackfill`

The old boolean flag still works and is treated as a shorthand:

```json theme={null}
{ "allowBackfill": true }
```

is equivalent to:

```json theme={null}
{ "backfill": { "enabled": true, "windowSeconds": 300, "closeWhenFull": true } }
```

The structured `backfill` object **takes precedence** if both are present. Prefer `backfill` for new configs — the dashboard drops `allowBackfill` on the next edit. Existing projects on `allowBackfill: true` keep working unchanged and now get real backfill (not just candidate discovery).

***

## What happens when a lobby queues

For a backfill-enabled mode, the matcher tries to backfill **before** forming a fresh match:

<Steps>
  <Step title="Search for an open match">
    The engine looks for a running match in the same project, lobby config, and mode with `status: in_game` and `backfill_open: true`, whose backfill window hasn't expired.
  </Step>

  <Step title="Check compatibility">
    The candidate match must be region-compatible, have remaining capacity ≥ the joining lobby's eligible players, and (if a skill gate is set) the lobby's average skill must fall inside the match's band.
  </Step>

  <Step title="Claim the slots">
    The engine atomically claims the open slots (assigning players to the teams with the largest deficit) and transitions the lobby to `in_game` with the running match's `matchId` and `server` connection info.
  </Step>

  <Step title="Players connect to the running server">
    The joined lobby receives the same `server.network_ports[]` as everyone already in the match — over the existing SSE stream — and connects immediately. No launch wait.
  </Step>

  <Step title="No open match? Fresh formation.">
    If there's no compatible open match, or another queue racer claims the last slots first, the lobby falls through to normal fresh match formation — a new server launches as usual.
  </Step>
</Steps>

When a match forms with backfill enabled, it opens to joiners for `windowSeconds` (or until it fills, when `closeWhenFull` is true). Players who **leave** during a match free their slots, and the engine reopens backfill if the match is still under capacity and inside its window.

***

## Server integration: admitting players

Your game server is the authority on gameplay, but the **engine is the authority on the roster**. Your server should admit connecting players against the roster it polls from the engine — not against whatever it happened to see at launch. This is the single change that makes backfill (and reliable reconnects) work.

### Poll the roster

```
GET /api/v3/servers/{instance_id}/roster
api-key: pf_your_server_key
```

Authenticate with your **project server API key** (`pf_...`) and use the server's own instance ID. At launch the platform injects these environment variables into your server container — read them rather than hardcoding:

| Env var                | Value                                                            |
| :--------------------- | :--------------------------------------------------------------- |
| `PLAYFLOW_INSTANCE_ID` | The server's own `instance_id` (use it to build the roster URL). |
| `PLAYFLOW_API_KEY`     | The project server API key (`pf_...`).                           |
| `PLAYFLOW_API_URL`     | The API base (e.g. `https://api.computeflow.cloud/api`).         |
| `PLAYFLOW_MATCH_ID`    | The match this server is hosting.                                |

Poll on an interval — every few seconds is plenty.

**Response (200):**

```json theme={null}
{
  "match_id": "match-abc",
  "instance_id": "srv-xyz",
  "status": "in_game",
  "capacity": 10,
  "current_players": 7,
  "backfill_open": true,
  "backfill_deadline": "2026-07-11T20:35:00Z",
  "roster_version": 4,
  "teams": {
    "team_1": {
      "capacity": 5,
      "players": [
        { "playerId": "p1", "lobbyId": "lob-1" },
        { "playerId": "p2", "lobbyId": "lob-1" }
      ]
    },
    "team_2": {
      "capacity": 5,
      "players": [ { "playerId": "p9", "lobbyId": "lob-4" } ]
    }
  },
  "roster": [
    { "playerId": "p1", "team": "team_1", "lobbyId": "lob-1", "joinedAt": "2026-07-11T20:30:00Z" },
    { "playerId": "p2", "team": "team_1", "lobbyId": "lob-1", "joinedAt": "2026-07-11T20:30:00Z" },
    { "playerId": "p9", "team": "team_2", "lobbyId": "lob-4", "joinedAt": "2026-07-11T20:31:12Z" }
  ]
}
```

<Info>
  `status` is one of `in_game`, `locked`, or `completed`. Keep admitting while it's `in_game`; once it's `locked` or `completed`, backfill is closed — stop admitting new joiners and treat the match as sealed.
</Info>

### `roster_version` — cheap change detection

`roster_version` is a monotonically increasing counter bumped on **every** roster change (a backfill joiner admitted, a player released, a backfill state toggle). Store the last version you saw and only re-diff your admission list when it changes:

* Version unchanged → nothing to do.
* Version increased → a backfill joiner arrived (or a player left). Reconcile your local player list with `roster`.

### Admission rule

When a player connects (or **reconnects**), check whether their `playerId` is in `roster`:

* **In the roster** → admit them, and place them on their assigned `team`.
* **Not in the roster** → reject the connection.

Because the roster is authoritative and refreshed on every change, a player who was admitted, dropped, and reconnects is still on the roster — so your server admits them instead of denying them at the proxy. Backfill and reconnect resilience are the same mechanism.

<Tabs>
  <Tab title="Unity (C#)">
    ```csharp theme={null}
    using System.Collections;
    using System.Collections.Generic;
    using UnityEngine;
    using UnityEngine.Networking;

    // Runs on the DEDICATED SERVER build. Polls the authoritative roster and
    // keeps a local admit-set the connection handler checks against.
    public class BackfillRoster : MonoBehaviour
    {
        // All injected into the server container at launch.
        string apiBase    = System.Environment.GetEnvironmentVariable("PLAYFLOW_API_URL")
                            ?? "https://api.computeflow.cloud/api";
        string instanceId = System.Environment.GetEnvironmentVariable("PLAYFLOW_INSTANCE_ID");
        string serverKey  = System.Environment.GetEnvironmentVariable("PLAYFLOW_API_KEY"); // pf_...

        long lastVersion = -1;
        readonly Dictionary<string, string> playerTeam = new(); // playerId -> team

        void Start() => StartCoroutine(PollLoop());

        IEnumerator PollLoop()
        {
            var wait = new WaitForSeconds(3f);
            while (true)
            {
                using var req = UnityWebRequest.Get($"{apiBase}/v3/servers/{instanceId}/roster");
                req.SetRequestHeader("api-key", serverKey);
                yield return req.SendWebRequest();

                if (req.result == UnityWebRequest.Result.Success)
                {
                    var roster = JsonUtility.FromJson<RosterResponse>(req.downloadHandler.text);
                    if (roster.roster_version != lastVersion)
                    {
                        lastVersion = roster.roster_version;
                        playerTeam.Clear();
                        foreach (var e in roster.roster) playerTeam[e.playerId] = e.team;
                        Debug.Log($"Roster v{lastVersion}: {playerTeam.Count}/{roster.capacity} players");
                    }
                }
                yield return wait;
            }
        }

        // Call this from your transport's connection-approval callback.
        public bool IsAdmitted(string playerId, out string team) =>
            playerTeam.TryGetValue(playerId, out team);
    }

    [System.Serializable] public class RosterEntry { public string playerId; public string team; public string lobbyId; public string joinedAt; }
    [System.Serializable] public class RosterResponse { public string match_id; public int capacity; public int current_players; public long roster_version; public RosterEntry[] roster; }
    ```
  </Tab>

  <Tab title="Godot (GDScript)">
    ```gdscript theme={null}
    # Autoload on the DEDICATED SERVER. Polls the authoritative roster and keeps
    # a player -> team map the connection handler checks before admitting.
    extends Node

    # All injected into the server container at launch.
    var api_base := OS.get_environment("PLAYFLOW_API_URL")
    var instance_id := OS.get_environment("PLAYFLOW_INSTANCE_ID")
    var server_key  := OS.get_environment("PLAYFLOW_API_KEY") # pf_...

    var _last_version := -1
    var _player_team := {} # playerId -> team
    var _http := HTTPRequest.new()

    func _ready() -> void:
        if api_base == "":
            api_base = "https://api.computeflow.cloud/api"
        add_child(_http)
        _http.request_completed.connect(_on_roster)
        var timer := Timer.new()
        timer.wait_time = 3.0
        timer.timeout.connect(_poll)
        add_child(timer)
        timer.start()

    func _poll() -> void:
        _http.request("%s/v3/servers/%s/roster" % [api_base, instance_id],
            PackedStringArray(["api-key: " + server_key]))

    func _on_roster(_r, code, _h, body: PackedByteArray) -> void:
        if code != 200: return
        var data: Dictionary = JSON.parse_string(body.get_string_from_utf8())
        if data.roster_version == _last_version: return
        _last_version = data.roster_version
        _player_team.clear()
        for e in data.roster:
            _player_team[e.playerId] = e.team

    # Call from your peer-connected / auth handler.
    func is_admitted(player_id: String) -> bool:
        return _player_team.has(player_id)
    ```
  </Tab>
</Tabs>

<Tip>
  Pull is primary. The engine also best-effort mirrors the roster onto your instance so the endpoint is fast, but your server should treat `GET /roster` as the source of truth and poll it — don't rely on a push you might miss.
</Tip>

***

## Optional: server-authoritative control

Most games never need this — the engine opens and closes backfill for you based on the window and capacity. But if your server has better knowledge of when it can accept joiners (e.g., only between rounds, or once a boss phase starts), it can take control.

<Warning>
  These endpoints require a **server API key** (`pf_...`). Client keys (`pfclient_...`) are allowed **unless** the project's `client_key_server_control` setting is `false`, in which case they are rejected with `403`. The read-only `GET /roster` endpoint accepts either key.
</Warning>

### Open or close backfill (and re-scope skill)

```
PATCH /api/v3/servers/{instance_id}/backfill
api-key: pf_your_server_key
Content-Type: application/json

{
  "accepting": true,
  "skillBand": { "field": "mmr", "min": 1400, "max": 1600 }
}
```

| Field       | Type           | Description                                                                                                                           |
| :---------- | :------------- | :------------------------------------------------------------------------------------------------------------------------------------ |
| `accepting` | boolean        | `true` opens backfill; `false` closes it.                                                                                             |
| `skillBand` | object \| null | Optional. Replace the match's skill band for joiners: `{ field, min, max }`. Omit or send `null` to leave the current band unchanged. |

**Response (200):**

```json theme={null}
{
  "match_id": "match-abc",
  "instance_id": "srv-xyz",
  "status": "in_game",
  "backfill_open": true,
  "backfill_deadline": "2026-07-11T20:35:00Z",
  "skill_band": { "field": "mmr", "min": 1400, "max": 1600 },
  "roster_version": 5
}
```

### Close backfill (shorthand)

Close the match to further joiners — a convenience shorthand for `PATCH ... { "accepting": false }`:

```
POST /api/v3/servers/{instance_id}/backfill/lock
api-key: pf_your_server_key
```

Returns the same `ServerBackfillState` shape as `PATCH`. Both bump `roster_version`, so a polling server sees the change on its next `GET /roster`.

***

## Behavior reference

| Situation                                  | Outcome                                                              |
| :----------------------------------------- | :------------------------------------------------------------------- |
| Lobby queues, compatible open match exists | Lobby joins the running server; no new server launches               |
| No open match / lost the claim race        | Falls through to fresh match formation                               |
| Match fills and `closeWhenFull` is true    | Backfill closes automatically                                        |
| Backfill window (`windowSeconds`) elapses  | Match closes to joiners                                              |
| Player leaves mid-match                    | Slot freed; backfill reopens if under capacity and inside the window |
| Mode has no `backfill` / `enabled: false`  | Backfill path never runs — behaves exactly as before                 |

***

<CardGroup>
  <Card title="Matchmaking" icon="swords" href="/lobbies/matchmaking">
    Modes, teams, skill rules, and how matches form.
  </Card>

  <Card title="Real-time Events" icon="bolt" href="/lobbies/real-time">
    Stream the `in_game` transition and server connection info via SSE.
  </Card>
</CardGroup>


# Lobby Lifecycle
Source: https://docs.playflowcloud.com/lobbies/lifecycle

The complete lifecycle of a PlayFlow lobby — from creation to cleanup. Creating, joining, leaving, host actions, and every edge case.

A lobby progresses through several states during its lifetime. Understanding the lifecycle helps you design your game's UI and handle every edge case cleanly.

## Status Flow

Lobbies never dead-end. They either stay alive (rematch-ready) or get deleted entirely. There's no "completed" terminal state.

```text theme={null}
waiting ─────→ in_queue ─────→ matched ─────→ in_game ─────→ waiting
    │             │                  │              ↑         (rematch-ready)
    │             │                  │              │
    │             │                  └──→ match_found (if matchConfirmation enabled)
    │             │                         │
    │             │                         └──→ in_game (all confirm)
    │             │                         └──→ waiting  (decline / timeout)
    │             │
    │             └──→ waiting (timeout / cancel / no opponents)
    │
    └──→ starting ─────→ in_game (host started game directly)
              │
              └──→ waiting (server create failed)
```

| Status        | Meaning                                                                                           |
| :------------ | :------------------------------------------------------------------------------------------------ |
| `waiting`     | Open lobby, accepting players. The default resting state.                                         |
| `in_queue`    | Matchmaking active, searching for opponents                                                       |
| `starting`    | Host triggered direct start, server provisioning                                                  |
| `matched`     | Claimed for a match, server being created                                                         |
| `match_found` | Match proposed, waiting for player `POST /me/confirm-match` (only if `matchConfirmation.enabled`) |
| `in_game`     | Game server running, players connected                                                            |

<Info>
  **Self-healing lobbies.** When the game server stops — whether the host clicks "End Match", the server crashes, or its TTL expires — the lobby automatically returns to `waiting` with all players retained. There is no `completed` status. Players can queue or start another match immediately.
</Info>

***

## Creating a Lobby

```bash theme={null}
POST /v3/lobbies/{config}
x-player-id: host_player
Content-Type: application/json

{
  "name": "Friday Night CTF",
  "maxPlayers": 8,
  "region": "us-east",
  "isPrivate": false,
  "allowLateJoin": true,
  "settings": { "map": "forest", "mode": "ctf" },
  "state": { "ready": true }
}
```

The creator becomes the **host**. An invite code is generated automatically (even for public lobbies, so friends can share it).

| Field           | Required | Default   | Notes                                       |
| :-------------- | :------- | :-------- | :------------------------------------------ |
| `name`          | Yes      | -         | Display name                                |
| `maxPlayers`    | No       | `2`       | 1–100                                       |
| `region`        | No       | `us-east` | Game server region                          |
| `isPrivate`     | No       | `false`   | Hide from `GET /v3/lobbies/{config}` browse |
| `allowLateJoin` | No       | `true`    | Can players join after game starts?         |
| `settings`      | No       | `{}`      | Game-specific data passed to the server     |
| `state`         | No       | `null`    | Host's initial player state                 |

<Warning>
  The host can only be in **one lobby at a time** per config. Trying to create a second returns `409 Player is already in a lobby`.
</Warning>

### Fresh lobby on reconnect

Set `forceFresh: true` on create to atomically replace a lobby the caller already **hosts** in this config. The backend deletes the old lobby (stopping its game server best-effort) and then creates the new one — all in a single call. It's a no-op when the player has no prior lobby, so it's safe to always pass on reconnect. This replaces the old 3-call workaround (`TryReconnect` → detect stale host lobby → `DeleteLobby` → `CreateLobby`) with one request.

```bash theme={null}
POST /v3/lobbies/{config}
x-player-id: host_player
Content-Type: application/json

{
  "name": "Friday Night CTF",
  "maxPlayers": 8,
  "forceFresh": true
}
```

Only lobbies the caller **hosts** are force-deleted. If the caller is merely a guest in someone else's lobby, the create still returns `409 Player is already in a lobby` — they need to leave that one first.

***

## Joining a Lobby

Two ways: by **invite code** or by **lobby ID**.

<Tabs>
  <Tab title="By Invite Code">
    ```bash theme={null}
    POST /v3/lobbies/{config}/join
    x-player-id: new_player

    {
      "code": "MEOW-42",
      "state": { "team": "blue" }
    }
    ```

    Best for "friend shares a code" flow. Works for both public and private lobbies.
  </Tab>

  <Tab title="By Lobby ID">
    ```bash theme={null}
    POST /v3/lobbies/{config}/join
    x-player-id: new_player

    {
      "lobbyId": "a1b2c3d4-...",
      "state": { "team": "blue" }
    }
    ```

    Best when the player browsed public lobbies and clicked one.
  </Tab>
</Tabs>

### Join Errors

| Status | Error                            | Cause                                             |
| :----- | :------------------------------- | :------------------------------------------------ |
| `404`  | `Lobby not found`                | Wrong ID/code                                     |
| `400`  | `Lobby is full`                  | `currentPlayers >= maxPlayers`                    |
| `400`  | `Lobby is not accepting players` | `status: in_game` and `allowLateJoin: false`      |
| `409`  | `Player is already in a lobby`   | Player is in a different lobby in the same config |

<Tip>
  Joining is **idempotent** — if the player is already in the lobby, it returns the lobby unchanged (no error).
</Tip>

***

## Updating Player State

Every player can update their own state. Use `PATCH /me`:

```bash theme={null}
PATCH /v3/lobbies/{config}/me
x-player-id: my_player

{
  "state": {
    "ready": true,
    "character": "wizard",
    "mmr": 1450
  }
}
```

<Info>
  **State merges, not replaces.** Existing keys are preserved unless your update overwrites them. To clear a key, set it to `null`.
</Info>

State flows automatically into `matchmaking_data` when the lobby queues, so fields like `mmr` are used by matchmaking rules.

***

## Host Actions

Only the **host** can perform these actions. Non-hosts get `403 Only the host can perform this action`.

### Update Lobby Settings

```bash theme={null}
PATCH /v3/lobbies/{config}/me/settings
x-player-id: host_player

{
  "name": "New Name",
  "maxPlayers": 16,
  "isPrivate": true,
  "region": "eu-west",
  "settings": { "map": "desert" }
}
```

Every field is optional — only include what you want to change.

### Kick a Player

```bash theme={null}
DELETE /v3/lobbies/{config}/me/players/{playerId}
x-player-id: host_player
```

The kicker is the host (from `x-player-id`). The `{playerId}` in the path is the target.

<Warning>
  Hosts can't kick themselves. Use `DELETE /me` to leave (which auto-transfers host).
</Warning>

### Start the Game Directly

Skip matchmaking and launch a server immediately with the current players:

```bash theme={null}
POST /v3/lobbies/{config}/me/start
x-player-id: host_player
```

The response has `server.status: "launching"`. Within \~10-30s status transitions to `running` and clients can connect. Read the connection host and port from the server response's `network_ports[]` array — the external port is proxy-allocated and differs from your internal port.

<Info>
  **`playflow.json` parity with matchmaking:** a directly-started server receives
  the same `custom_data` shape a matchmaker-launched one does — `mode`, `teams`
  (grouped from each player's `state.team`), `players`, `lobby_id`, `match_id`,
  and `version`. A directly-created lobby never enters the queue, so declare the
  mode yourself in lobby **`settings.mode`** (at create time, or later with
  `PATCH /me/settings`) and your game server reads it from `playflow.json` as
  `custom_data.mode`. If the lobby did queue at some point, the active
  matchmaking mode wins.
</Info>

### End the Match (Rematch)

```bash theme={null}
POST /v3/lobbies/{config}/me/end-match
x-player-id: host_player
```

The server stops, the lobby returns to `waiting`, and all players stay in the lobby with the same invite code and settings. Great for "Play Again" buttons.

<Info>
  If the game server stops on its own (crashes, hits TTL, or your game logic exits cleanly), the lobby **auto-heals** to `waiting` with the same effect — no call needed. `POST /me/end-match` is just the explicit, host-triggered version.
</Info>

***

## Leaving

Any player can leave at any time:

```bash theme={null}
DELETE /v3/lobbies/{config}/me
x-player-id: my_player
```

**What happens depends on who leaves:**

| Scenario                            | Behavior                                                |
| :---------------------------------- | :------------------------------------------------------ |
| Regular player leaves               | Removed from `players`, `currentPlayers` decrements     |
| Host leaves (with others remaining) | Host auto-transfers to next player (default)            |
| Last player leaves                  | Lobby is deleted, returns `{"status": "lobby_deleted"}` |
| Player leaves during matchmaking    | Matchmaking auto-cancels, lobby returns to `waiting`    |

### Host leave behavior

What happens when the host leaves is controlled per lobby config via `hostLeaveBehavior`:

| Value                 | Behavior                                                                                                                                        |
| :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------- |
| `"promote"` (default) | The next player in the lobby becomes the new host. Remaining players stay put with the same invite code, settings, and state.                   |
| `"delete"`            | The entire lobby is destroyed. Every remaining player receives a `lobby_deleted` SSE event on `/me/events` and must create or join a new lobby. |

**When to use each:**

* **`"promote"`** — persistent rooms, squad play, party-based games where the lobby should survive individual churn. This is the default for every lobby config.
* **`"delete"`** — one-shot private rooms, pickup games, host-authored sessions where the host's presence IS the room. Pairs well with `isPrivate: true` invite-only lobbies.

Non-host players leaving never triggers delete — only the host walking out can collapse the lobby under `"delete"`.

Example config JSON:

```json theme={null}
{
  "id": "private-squad",
  "name": "Private Squad Room",
  "enabled": true,
  "timeout": 300,
  "hostLeaveBehavior": "delete",
  "inviteCodeConfig": {
    "type": "alphanumeric",
    "length": 6,
    "prefix": "SQD-"
  },
  "serverSettings": { "serverSize": "small" }
}
```

<Info>
  When `hostLeaveBehavior: "delete"` fires, any game server associated with the lobby is stopped best-effort — same cleanup path as the admin delete endpoint.
</Info>

***

## Browsing Lobbies

Anyone (even without a player-id) can browse public lobbies in a config:

```bash theme={null}
GET /v3/lobbies/{config}?region=us-east&status=waiting&limit=20
```

Returns a paginated list. Private lobbies (`isPrivate: true`) are excluded automatically.

Query params:

| Param    | Purpose                         |
| :------- | :------------------------------ |
| `region` | Filter by region                |
| `status` | Filter by lobby status          |
| `limit`  | Page size (default 50, max 100) |
| `offset` | Pagination offset               |

***

## Cleanup & Timeouts

Lobbies don't stick around forever. The PlayFlow `lobby-sweep` cron runs continuously and handles:

* **Expired waiting lobbies** — deleted after `timeout` seconds (default 5 min) with no activity
* **Stale in-game lobbies** — in-game lobbies past 2 hours are cleaned up
* **Heartbeat expiry** — if `heartbeat: true` is enabled in config, players that stop sending heartbeats are removed
* **Matchmaking timeout** — lobbies in `in_queue` past the mode's timeout drop back to `waiting`

<Tip>
  For most games, **you don't need to send heartbeats**. The SSE connection itself is the heartbeat — as long as the player is connected to `/me/events`, they're alive. Only enable heartbeat in config if your players use HTTP polling instead of SSE.
</Tip>

***

## Heartbeat

Set `heartbeat: true` on a lobby config to require connected players to ping the server periodically. Players who go silent get evicted by the `lobby-sweep` cron.

```json theme={null}
{
  "heartbeat": true,
  "heartbeatTimeout": 30
}
```

* `heartbeat` — when `true`, every player must send heartbeats
* `heartbeatTimeout` — seconds before a player is considered stale. Any player whose last heartbeat is older than this is removed on the next sweep.

**When you need it:** HTTP-polling clients where the SSE connection at `/me/events` isn't available. Mobile background states, low-resource IoT clients, or environments that block long-lived connections.

<Tip>
  SSE is the better alternative. If your client can open `/me/events`, the stream itself is the liveness signal — see [Real-time Events](/lobbies/real-time) — and you can leave `heartbeat` off.
</Tip>

***

## Admin Delete

Force-delete any lobby by ID. Removes all players and cancels any active matchmaking — regardless of who created the lobby.

```bash theme={null}
curl -X DELETE https://api.computeflow.cloud/api/v3/lobbies/{config}/{id} \
  -H "api-key: pf_your_server_key"
```

* No `x-player-id` required. This is a server-side admin operation.
* `{config}` — the lobby config name (e.g. `"ranked_2v2"`).
* `{id}` — the lobby UUID to delete.

**Response (200):**

```json theme={null}
{ "status": "lobby_deleted", "id": "a3f1…-e8c2" }
```

**404** if no lobby with that ID exists in your project.

<Warning>
  Connected SDK clients in that lobby receive a `lobby_deleted` SSE event and disconnect cleanly. In contrast, `DELETE /{config}/me` is "leave lobby" — it only removes the caller, and when the caller is the host a new host is promoted automatically. Use admin delete when you actually mean destroy.
</Warning>

Good uses: dashboard admin actions, anti-cheat or moderation tooling, periodic cleanup for lobbies your app determines are abandoned.

***

## Invite Codes

`inviteCodeConfig` on a lobby config controls the codes PlayFlow generates when a lobby is created. Every new lobby (public **and** private) gets a code so friends can join by sharing it.

```json theme={null}
{
  "inviteCodeConfig": {
    "type": "alphanumeric",
    "length": 6,
    "prefix": "PLAY-"
  }
}
```

| Field    | Values                                  | Notes                                               |
| :------- | :-------------------------------------- | :-------------------------------------------------- |
| `type`   | `numeric`, `alphanumeric`, `alphabetic` | Character set for the generated suffix              |
| `length` | 1–16                                    | Length of the generated suffix (excluding prefix)   |
| `prefix` | any string                              | Optional. Prepended verbatim to the generated code. |

With the example above a lobby might get the code `PLAY-K7Q2F1`. Players then join with:

```bash theme={null}
POST /v3/lobbies/{config}/join
{ "code": "PLAY-K7Q2F1" }
```

***

## Error Codes

Every lobby error returns the same JSON shape — a human-readable `error` message, a `detail` (the same message), and the HTTP `status`:

```json theme={null}
{
  "error": "Lobby is full",
  "detail": "Lobby is full",
  "status": 400
}
```

<Warning>
  There is **no** machine-readable error-code enum. Branch on the HTTP `status` (and, if you must, the exact `error` string) — do not hard-code a `code` field, because the API never emits one.
</Warning>

The messages you can expect, by status:

| HTTP  | `error` message                                    | Meaning                                            |
| :---- | :------------------------------------------------- | :------------------------------------------------- |
| `400` | `Lobby is full`                                    | Capacity exceeded (`currentPlayers >= maxPlayers`) |
| `400` | `Lobby is not accepting players`                   | In-game with no late-join                          |
| `400` | `Invalid action for current lobby state`           | E.g., host trying to self-kick                     |
| `403` | `Only the host can perform this action`            | Non-host tried a host-only action                  |
| `403` | `This lobby is private; join with its invite code` | Tried to join a private lobby by ID                |
| `404` | `Lobby not found`                                  | Lobby doesn't exist                                |
| `404` | `Player not found in lobby`                        | Player isn't in the lobby                          |
| `409` | `Player is already in a lobby`                     | Player is already in another lobby in this config  |
| `409` | `Game is already running`                          | Started a game that's already in progress          |
| `409` | `Invalid lobby state transition`                   | Wrong status for this operation                    |


# Matchmaking
Source: https://docs.playflowcloud.com/lobbies/matchmaking

Skill-based matchmaking, asymmetric teams, auto-expanding MMR buckets, queue stats, and region selection — all through one endpoint.

PlayFlow's matchmaking system finds compatible opponents for your players and launches a shared game server. It supports symmetric teams, asymmetric roles, skill-based filtering, region preferences, and handles concurrency safely.

**A matchmaking game is just a group of lobbies pointing to the same server.** When two lobbies match, they both transition to `in_game` with the same `matchId` and the same `server` connection info.

<Info>
  **Prerequisites.** Authenticate every request with the `api-key` header (a client key `pfclient_...` is safe to ship in game builds). The examples below use a raw `x-player-id` header, which only works when your project has no player-auth provider configured. If you enable JWT, PlayFab, or Steam player auth, client keys must send a verified `x-player-token` instead — otherwise these calls return `401`. See [Player authentication](/guides/player-authentication) for setup.
</Info>

## The Full Flow

<Steps>
  <Step title="Players group up in a lobby">
    One or more players join a lobby (as a party).
  </Step>

  <Step title="Host starts matchmaking">
    `POST /v3/lobbies/{config}/me/matchmaking` with a `mode` name.

    Lobby status → `in_queue`. `matchmaking.mode` populates. Queue stats begin streaming via SSE.
  </Step>

  <Step title="System searches for compatible lobbies">
    Other lobbies in the same config + mode are evaluated. Rules applied (MMR, region, party size). Candidates sorted by wait time.
  </Step>

  <Step title="Match formed">
    All matched lobbies atomically claim each other. Status → `matched`.
  </Step>

  <Step title="Game server launches">
    One dedicated server starts. All matched lobbies get the same `matchId` and `server.network_ports[]`.
  </Step>

  <Step title="Players connect">
    Clients read `server.network_ports[0].host:external_port` from their lobby and connect to the game server.
  </Step>
</Steps>

***

## Configuring Matchmaking

Matchmaking modes are defined in your **lobby config** in the PlayFlow dashboard. Each config can have multiple modes:

```json theme={null}
{
  "id": "ranked",
  "name": "ranked",
  "enabled": true,
  "timeout": 300,
  "serverSettings": {
    "serverSize": "small",
    "gameBuild": "default"
  },
  "matchmaking": {
    "modes": {
      "1v1": {
        "teams": 2,
        "playersPerTeam": 1,
        "minPlayersPerTeam": 1,
        "timeout": 60,
        "maxPartySize": 1,
        "allowBackfill": false,
        "rules": [
          { "type": "difference", "field": "mmr", "maxDifference": 100 }
        ]
      },
      "5v5": {
        "teams": 2,
        "playersPerTeam": 5,
        "minPlayersPerTeam": 3,
        "timeout": 120,
        "maxPartySize": 5,
        "allowBackfill": true
      }
    }
  }
}
```

<Info>
  **No config? No problem.** If you don't set up matchmaking in the dashboard, the `/me/matchmaking` endpoint returns a `400` asking you to configure modes. All *lobby* operations still work without config (they use defaults).
</Info>

***

## Starting Matchmaking

```bash theme={null}
POST /v3/lobbies/ranked/me/matchmaking
x-player-id: host_player
Content-Type: application/json

{
  "mode": "5v5"
}
```

**Response** — lobby transitions to `in_queue` with queue stats:

```json theme={null}
{
  "status": "in_queue",
  "matchmaking": {
    "mode": "5v5",
    "startedAt": "2026-04-08T20:30:00Z",
    "queueStats": {
      "playersSearching": 42,
      "lobbiesInQueue": 8,
      "avgWaitSeconds": 12.3
    }
  },
  ...
}
```

<Warning>
  Only the **host** can start matchmaking. Non-hosts get `403 Not host`.
</Warning>

### When a Match Is Found

When the system matches your lobby with others, the SSE stream emits an update:

```
event: lobby_updated
data: {
  "status": "in_game",
  "matchId": "abc-123",
  "server": {
    "instance_id": "srv-xyz",
    "status": "launching",
    "region": "us-east",
    "network_ports": [{"name":"game_udp","host":"203.0.113.42","external_port":30234,"internal_port":7770,"protocol":"udp","tls_enabled":false}]
  },
  ...
}
```

All matched lobbies get the **same** `matchId` and **same** `server`. Clients connect to `server.network_ports[0].host:external_port`. The `server` block is the same shape as `GET /v3/servers/{instance_id}` — server is a primitive the lobby wraps around.

### Cancel Matchmaking

```bash theme={null}
DELETE /v3/lobbies/ranked/me/matchmaking
x-player-id: host_player
```

Lobby returns to `waiting`.

***

## Match Confirmation

CS2-style "Accept Match" flow. For ranked or competitive modes, you often want players to accept a match before the server launches. PlayFlow supports this natively — add `matchConfirmation` to the mode:

```json theme={null}
{
  "mode": "ranked_5v5",
  "matchConfirmation": {
    "enabled": true,
    "timeoutSeconds": 10
  }
}
```

### How it works

1. Matchmaker finds a match → all lobbies transition `in_queue` → **`match_found`**. **Server is NOT launched yet.**
2. Each lobby's response now includes a confirmation block:
   ```json theme={null}
   {
     "status": "match_found",
     "matchmaking": {
       "confirmation": {
         "deadline": "2026-04-18T15:30:00Z",
         "confirmed": false
       }
     }
   }
   ```
3. Players accept or decline:
   * **Accept:** `POST /v3/lobbies/{config}/me/confirm-match`
   * **Decline:** `DELETE /v3/lobbies/{config}/me/confirm-match`
4. When **every** matched lobby accepts → server launches → `in_game`.
5. If **any** lobby declines OR the deadline passes → **all participating lobbies return to `waiting`** (matchmaking state cleared). Players re-queue when ready.

<Info>
  **Who confirms?** Any player in a lobby can accept or decline on behalf of their party. Parties confirm as a unit (one click per party, not per player).
</Info>

<Warning>
  Declining or timing out moves players to `waiting`, not back to `in_queue`. This prevents accidental re-matching. Players must explicitly press matchmake again.
</Warning>

### Full flow over SSE

The client sees the whole flow in real-time:

```
# 1. Match found, awaiting acceptance
event: lobby_updated
data: { "status": "match_found", "matchmaking": {
  "confirmation": { "deadline": "...", "confirmed": false }
}}

# 2. This player accepts
event: lobby_updated
data: { "status": "match_found", "matchmaking": {
  "confirmation": { "deadline": "...", "confirmed": true }
}}

# 3. Last player accepts → server launches
event: lobby_updated
data: { "status": "in_game", "server": { "status": "launching", "network_ports": [] }}
```

***

## Rematch (keep the same lobby)

When a match ends, the host can recycle the lobby for another round instead of making players re-queue:

```bash theme={null}
POST /v3/lobbies/ranked/me/end-match
x-player-id: host_player
```

This:

* Transitions lobby from `in_game` → `waiting`
* Stops the current game server
* Keeps all players, invite code, and settings
* Ready for `/me/start` or `/me/matchmaking` again

If the game server naturally shuts down (TTL or crash), the lobby **automatically self-heals** to `waiting` the same way — no manual call needed.

***

## Team Modes

### Symmetric teams

Traditional team structure — most competitive games. N teams of M players, everyone equal.

```json theme={null}
{
  "teams": 2,
  "playersPerTeam": 5,
  "minPlayersPerTeam": 3
}
```

* `teams` — how many teams to form
* `playersPerTeam` — target size (matchmaker tries to fill to this)
* `minPlayersPerTeam` — minimum required to start (for partial matches)

**Examples:**

| Mode                   | Config                                                 |
| :--------------------- | :----------------------------------------------------- |
| 1v1 ranked             | `teams: 2, playersPerTeam: 1`                          |
| 2v2 duos               | `teams: 2, playersPerTeam: 2`                          |
| 5v5 competitive        | `teams: 2, playersPerTeam: 5`                          |
| 100-player FFA         | `teams: 1, playersPerTeam: 100, minPlayersPerTeam: 20` |
| 50-squad battle royale | `teams: 50, playersPerTeam: 2, minTeams: 10`           |

### Asymmetric teams

Role-based team structure for games like *Dead by Daylight* (1 killer vs 4 survivors) or *Evolve* (1 monster vs 4 hunters):

```json theme={null}
{
  "teams": 2,
  "playersPerTeam": 3,
  "minPlayersPerTeam": 2,
  "teamComposition": {
    "monsters": { "boss": 1 },
    "hunters": { "medic": 1, "assault": 2, "support": 1 }
  },
  "excludedFromQueue": ["spectator"]
}
```

Players specify their role in `state.role`:

```bash theme={null}
PATCH /v3/lobbies/hunt/me
x-player-id: p1

{ "state": { "role": "boss" } }
```

Or a preference list (higher priority first):

```bash theme={null}
{ "state": { "role": ["medic", "support", "fill"] } }
```

The matchmaker:

* Places players with the most specific role first (`boss` before `fill`)
* Keeps party members together on the same team
* Uses `"fill"` as a wildcard (assigns wherever there's an open slot)
* Excludes spectators (or any role in `excludedFromQueue`)

***

## Matchmaking Rules

Rules decide which lobbies are allowed to match with each other. Add them to a mode under `rules`:

```json theme={null}
{
  "mode": "ranked_2v2",
  "rules": [
    { "type": "difference", "field": "mmr", "maxDifference": 100 }
  ]
}
```

**All rules must pass** for two lobbies to match. If any rule rejects, the matcher keeps looking.

Numeric state fields are averaged across party members. So a party with players at MMR 1400 and 1600 shows up as 1500 to the matcher. String fields (e.g. `gameVersion`) are propagated only if all party members agree on the same value.

### The 5 rule types

<CardGroup>
  <Card title="difference" icon="scale-balanced">
    Numeric tolerance with auto-expanding buckets. Skill matching.
  </Card>

  <Card title="equals" icon="equals">
    Both sides must share a field value (version, map).
  </Card>

  <Card title="not_equals" icon="not-equal">
    Values must differ (anti-rematch).
  </Card>

  <Card title="region" icon="globe">
    Acceptable-region overlap (≥ N shared).
  </Card>

  <Card title="expression" icon="code">
    CEL escape hatch for custom logic.
  </Card>
</CardGroup>

### Skill matching

The `difference` rule pairs players whose state differs by no more than a threshold, with buckets that widen over time.

```json theme={null}
{ "type": "difference", "field": "mmr", "maxDifference": 100 }
```

Matches when `|lobbyA.mmr - lobbyB.mmr| <= maxDifference`. **Works with any numeric field**: `mmr`, `elo`, `level`, `rank`, `kd_ratio`.

**The magic**: as players wait longer, the bucket grows automatically. No extra config.

Formula: `effectiveMax = maxDifference × (1 + longestWaitTime / modeTimeout)`

Using `maxDifference: 100, timeout: 60s`:

| Wait time | Effective range   |
| :-------- | :---------------- |
| 0s        | ±100 MMR (strict) |
| 30s       | ±150 MMR          |
| 60s       | ±200 MMR          |
| 120s      | ±300 MMR          |

This is how Riot, Valve, and Blizzard all do it — they just never made you configure it.

### Equals rule

The `equals` rule pairs players only when a specific state field matches exactly on both sides.

```json theme={null}
{ "type": "equals", "field": "gameVersion" }
```

Matches only if `lobbyA.gameVersion == lobbyB.gameVersion`. Use for: game version pinning, map selection, platform gating.

### Not-equals rule

The `not_equals` rule pairs players only when a state field has different values on each side.

```json theme={null}
{ "type": "not_equals", "field": "lastOpponent" }
```

Matches only when the field values differ. Use for: anti-rematch (last two opponents shouldn't be the same), team-mixing, forced rotation.

### Region rule

The `region` rule pairs lobbies only when their acceptable-region lists overlap by at least `minOverlap` entries.

```json theme={null}
{ "type": "region", "minOverlap": 1 }
```

Matches only if both lobbies share at least `minOverlap` entries in their `acceptableRegions` list. Players set regions via their state:

```bash theme={null}
PATCH /v3/lobbies/ranked/me
{ "state": { "regions": ["us-east", "us-west"] } }
```

If `acceptableRegions` is empty, the lobby is "open to any region" (wildcard — always passes).

### Expression rule

The `expression` rule is a CEL escape hatch for logic the other four primitives don't cover. Uses [CEL](https://cel.dev/) (Common Expression Language).

```json theme={null}
{
  "type": "expression",
  "cel": "a.state.mmr > 1000 && b.state.mmr > 1000"
}
```

**Scope:** you have `a` and `b` (the two lobby tickets) and `ctx` (mode config). Each ticket exposes `id`, `partySize`, `waitSeconds`, `region`, `acceptableRegions`, `state`, `metadata`.

**More CEL examples:**

```json theme={null}
// High-tier games only (hidden MMR gating)
{ "type": "expression", "cel": "a.state.rank == b.state.rank && a.state.mmr > 2000" }

// Anti-smurf: only match if both accounts are at least a week old
{ "type": "expression", "cel": "a.state.accountAgeDays >= 7 && b.state.accountAgeDays >= 7" }

// Prefer opponents who have waited longer (priority boost)
{ "type": "expression", "cel": "a.waitSeconds + b.waitSeconds > 30" }
```

### Multiple rules — all must pass

Stack rules together:

```json theme={null}
{
  "rules": [
    { "type": "difference", "field": "mmr", "maxDifference": 100 },
    { "type": "equals",     "field": "gameVersion" },
    { "type": "region",     "minOverlap": 1 }
  ]
}
```

A candidate pair must satisfy **every** rule to match.

***

## Dynamic Version Selection

Shipping a new game version usually means a rolling update — stop old matches, cut the fleet over to the new build, and hope nothing breaks for players mid-session. That's infrastructure overhead you pay on every release.

Set `useVersionFromState: "gameVersion"` on a mode. Your client sends `gameVersion` in its player state when queueing, an `equals` rule on the same field keeps matched players on the same version, and the matchmaker launches whichever build has that `name`. No rolling updates, multiple versions live simultaneously in the same project.

### Config

```json theme={null}
{
  "id": "ranked",
  "name": "ranked",
  "enabled": true,
  "serverSettings": {
    "serverSize": "small",
    "gameBuild": "1.2.3"
  },
  "matchmaking": {
    "modes": {
      "5v5": {
        "teams": 2,
        "playersPerTeam": 5,
        "useVersionFromState": "gameVersion",
        "rules": [
          { "type": "equals",     "field": "gameVersion" },
          { "type": "difference", "field": "mmr", "maxDifference": 100 }
        ]
      }
    }
  }
}
```

`useVersionFromState` maps to a build's `name` (e.g. `1.2.3`), not its numeric version. `serverSettings.gameBuild` acts as the fallback when the field is missing from every matched player's state.

### Unity SDK

Send the version in player state before you queue:

```csharp theme={null}
using System.Collections.Generic;
using PlayFlow;
using UnityEngine;

public class VersionedMatchmaking : MonoBehaviour
{
    public void SetMatchmakingState(int playerMMR)
    {
        var matchmakingData = new Dictionary<string, object>
        {
            { "gameVersion", Application.version }, // e.g. "1.2.3"
            { "mmr", playerMMR },
            { "regions", new List<string> { "us-east", "us-west" } }
        };

        PlayFlowLobbyManagerV2.Instance.UpdatePlayerState(matchmakingData,
            onSuccess: (lobby) => Debug.Log($"Queueing as v{Application.version}"),
            onError: (error) => Debug.LogError($"State update failed: {error}")
        );
    }
}
```

### Prerequisites

* A build whose `name` matches the state value must exist and be `ready`
* Every matched player must send the field in their state — add a client-side check with a sensible fallback
* An `equals` rule on the same field is required (the dashboard and API reject the config otherwise)

### Failure modes

| Condition                                             | Outcome                                  |
| :---------------------------------------------------- | :--------------------------------------- |
| Field missing from state                              | Match fails, players return to `waiting` |
| Build with that `name` doesn't exist or isn't `ready` | Match fails, players return to `waiting` |
| No `equals` rule on the same field                    | Config save rejected (`400`)             |

<Tip>
  Gate access to old versions by deleting (or unpublishing) the old build once your player base has upgraded. The matchmaker will refuse matches that resolve to missing builds, forcing clients onto a supported version.
</Tip>

***

## Region Matching

Players specify their acceptable regions in state (or PlayFlow falls back to the lobby's region):

```bash theme={null}
PATCH /v3/lobbies/ranked/me

{ "state": { "regions": ["us-east", "us-west"] } }
```

The matchmaker:

1. Intersects all matched lobbies' region lists
2. Within the intersection, counts weighted votes (1/(index+1) by preference order)
3. Picks the highest-voted region for the server

If lobbies have no overlap, the match doesn't form — they're considered incompatible.

***

## Queue Stats

While in `in_queue`, your lobby response includes live queue stats:

```json theme={null}
{
  "matchmaking": {
    "mode": "5v5",
    "startedAt": "...",
    "queueStats": {
      "playersSearching": 42,
      "lobbiesInQueue": 8,
      "avgWaitSeconds": 12.3
    }
  }
}
```

Via **SSE**, you get push updates every 10 seconds:

```
event: queue_stats
data: { "playersSearching": 45, "lobbiesInQueue": 9, "avgWaitSeconds": 11.8 }
```

Use this to show your players "12s estimated wait" or "42 searching now" in your UI.

***

## Backfill

For long-running persistent games (e.g., battle royale with late-join), enable backfill so newly-queued lobbies join an **already-running match with open slots** instead of always launching a new server:

```json theme={null}
{
  "backfill": {
    "enabled": true,
    "windowSeconds": 300,
    "closeWhenFull": true,
    "skill": { "field": "mmr", "maxDifference": 150 }
  }
}
```

When backfill is enabled, the matchmaker adds new lobbies to **existing in-progress games** that have open slots — not just create new matches. Players join the running server and jump straight into the action. Your game server admits them from an authoritative roster it polls from the engine (which also fixes reconnect / "denied by proxy" edge cases).

The older `"allowBackfill": true` flag still works as a shorthand for `{ "backfill": { "enabled": true } }`, but prefer the structured object.

<Card title="Backfill" icon="user-plus" href="/lobbies/backfill">
  Full config, the engine-authoritative hybrid model, and the server integration guide (roster polling + admission).
</Card>

***

## Party Size Limits

Prevent a 5-stack from queueing for a 1v1:

```json theme={null}
{
  "maxPartySize": 1
}
```

Lobbies with more than `maxPartySize` eligible players are rejected from queueing.

***

## Matchmaking Timeout

The `timeout` field on a matchmaking mode caps how long a player will wait in queue before the system gives up.

```json theme={null}
{ "timeout": 60 }
```

When the timeout elapses, the lobby transitions back to `waiting`, delivered as a normal `lobby_updated` SSE event — players are **not** re-queued automatically. Players must explicitly press matchmake again.

**Typical values:**

* `30` — casual / quick play
* `60` – `120` — ranked
* `180`+ — large FFAs or niche modes where the candidate pool is thin

***

## Battle Royale

Battle royale modes are not a separate feature — they are just a particular shape of the existing `teams` / `playersPerTeam` fields. There is nothing special to enable on the backend.

**Squad BR** uses the Teams format: many small squads fight in one match. A `{ "teams": 25, "playersPerTeam": 4 }` mode fills one 100-player server from 25 four-player lobbies.

**Solo BR** uses the Free-for-all format: `{ "teams": 100, "playersPerTeam": 1 }` fills a 100-player match from 100 solo lobbies.

### Anchor-pairwise matching

When N lobbies come together to form one match, rules are evaluated **pairwise against the anchor** (the first lobby in the queue), not against a running average. For a 25-squad BR that means 24 anchor-vs-candidate evaluations — each candidate must be compatible with the anchor.

This matters because two admitted lobbies can legally be up to `2 × maxDifference` apart from each other, even though each is within `maxDifference` of the anchor.

### Rule recommendations

* **Skill (`difference` on `mmr`)** — works, but tune `maxDifference` on the conservative side. Remember two admitted squads can be `2 × maxDifference` apart.
* **`equals` on `gameVersion`** — every lobby must match the anchor exactly. Recommended.
* **`region`** — critical for BR. One cross-continent squad ruins the server for everyone.

<Warning>
  Do **not** enable `matchConfirmation` (accept match) on BR modes. 100 players × "click accept" means any single holdout cancels the match. Accept-match is for 1v1 and small team matches, not large rooms.
</Warning>

### Party semantics reminder

Numeric fields in a lobby's `state` (like `mmr`) are averaged **within** a party when it joins matchmaking together. Across parties, each party carries its own averaged value — the matchmaker compares those averages against the anchor.

### Example: 25-squad BR

```json theme={null}
{
  "matchmaking": {
    "modes": {
      "squads": {
        "teams": 25,
        "playersPerTeam": 4,
        "timeout": 180,
        "rules": [
          { "type": "difference", "field": "mmr", "maxDifference": 150 },
          { "type": "equals", "field": "gameVersion" },
          { "type": "region" }
        ]
      }
    }
  }
}
```

***

## How Matchmaking Runs

<Info>
  **Matchmaking runs inline on queue entry.** When lobby B calls `POST /me/matchmaking`, the system immediately scans for compatible lobbies. If A is already queued, B matches with A within \~100ms. No polling loops, no worker delay.

  A QStash-driven cron runs every 60s as a safety net (catches edge cases like simultaneous-entry races).
</Info>

**Concurrency safety:** The matchmaker uses Postgres `FOR UPDATE SKIP LOCKED` + a claim-then-create pattern. Two simultaneous match attempts can never claim the same lobbies or launch duplicate servers.

***

## Error Cases

| Status                    | Cause                                                    |
| :------------------------ | :------------------------------------------------------- |
| `400 Mode not found`      | The `mode` you passed isn't defined in your lobby config |
| `400 Party size exceeded` | Your lobby has more players than `maxPartySize`          |
| `400 Already in queue`    | Lobby is already in `in_queue` status                    |
| `403 Not host`            | Non-host tried to start/cancel matchmaking               |
| `409 Invalid state`       | Lobby is `in_game` or otherwise not in `waiting`         |

<Info>
  This table lists causes and approximate messages, not verbatim error strings. Errors return `{ error, detail, status }` with no machine-readable `code` field — branch on the HTTP **status**, not the exact message text.
</Info>

***

## Full Example: Ranked 1v1

```bash theme={null}
# Host creates a lobby (with MMR in state)
curl -X POST "https://api.computeflow.cloud/api/v3/lobbies/ranked" \
  -H "api-key: pfclient_..." \
  -H "x-player-id: p1" \
  -d '{"name":"1v1","maxPlayers":1,"state":{"mmr":1500}}'

# Host queues for matchmaking
curl -X POST "https://api.computeflow.cloud/api/v3/lobbies/ranked/me/matchmaking" \
  -H "api-key: pfclient_..." \
  -H "x-player-id: p1" \
  -d '{"mode":"1v1"}'

# Separately, another player does the same — they match automatically
# Both get the same matchId and server info
curl "https://api.computeflow.cloud/api/v3/lobbies/ranked/me" \
  -H "api-key: pfclient_..." \
  -H "x-player-id: p1"
# → { "status": "in_game", "server": { "network_ports": [{"host": "...", "external_port": 30234, "protocol": "udp", "tls_enabled": false}] } }
# Read host + external_port straight from network_ports[] — never hardcode a port.
```

<CardGroup>
  <Card title="Real-time Events" icon="bolt" href="/lobbies/real-time">
    Stream matchmaking progress and queue stats via SSE.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Full schemas for the matchmaking endpoints.
  </Card>
</CardGroup>


# Lobbies & Matchmaking Overview
Source: https://docs.playflowcloud.com/lobbies/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.

<Info>
  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.
</Info>

## 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.
</Tip>

### 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.

<Tabs>
  <Tab title="Quick Match">
    **"Just put me in a game."** The player presses a button, gets connected to a server within seconds.

    <Steps>
      <Step title="Player creates a lobby">
        `POST /v3/lobbies/ranked` — instant, even with no friends.
      </Step>

      <Step title="Host starts matchmaking">
        `POST /v3/lobbies/ranked/me/matchmaking` with a mode name.
      </Step>

      <Step title="System finds opponents">
        Another queueing lobby matches within seconds.
      </Step>

      <Step title="Game server launches">
        All matched lobbies get a populated `server.network_ports[]`. Connect your game client to `host:external_port`.
      </Step>
    </Steps>

    **Best for:** Ranked ladders, competitive play, quick play modes, Counter-Strike/League of Legends-style matchmaking.
  </Tab>

  <Tab title="Invite a Friend">
    **"Create a game, share a code, friends join, start playing."**

    <Steps>
      <Step title="Host creates a lobby">
        `POST /v3/lobbies/casual` — returns an invite code like `MEOW-42`.
      </Step>

      <Step title="Friend joins with the code">
        `POST /v3/lobbies/casual/join` with `{"code": "MEOW-42"}`.
      </Step>

      <Step title="Ready up, pick teams">
        Each player sets their state: `PATCH /v3/lobbies/casual/me` with `{"state": {"ready": true, "team": "blue"}}`.
      </Step>

      <Step title="Host starts the game">
        `POST /v3/lobbies/casual/me/start` — launches a dedicated server immediately.
      </Step>
    </Steps>

    **Best for:** Party games, Among Us-style lobbies, Minecraft-style private worlds, custom matches.
  </Tab>
</Tabs>

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.
</Warning>

**No player auth is required** to start using lobbies. Ship an MVP with random player IDs, add real auth later when you need it.

<Info>
  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](/guides/player-authentication) for setup.
</Info>

***

## 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

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/lobbies/quickstart">
    Get a working lobby in 5 minutes with copy-paste curl commands.
  </Card>

  <Card title="Lobby Lifecycle" icon="arrows-rotate" href="/lobbies/lifecycle">
    Create, join, update your own state, kick, automatic host handoff, start games.
  </Card>

  <Card title="Matchmaking" icon="swords" href="/lobbies/matchmaking">
    Configure modes, skill-based rules, asymmetric teams, expanding buckets.
  </Card>

  <Card title="Real-time Events" icon="bolt" href="/lobbies/real-time">
    Subscribe to SSE for live lobby updates and queue stats.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Every endpoint with request/response schemas and try-it-out.
  </Card>
</CardGroup>


# Lobbies Quickstart
Source: https://docs.playflowcloud.com/lobbies/quickstart

Go from zero to a working multiplayer lobby in 5 minutes using nothing but curl.

This guide gets you a working lobby in under 5 minutes. No dashboard setup. No player auth. Just curl.

By the end, you'll have created a lobby, joined it with a second player, updated player state, and torn it all down.

## Prerequisites

* A PlayFlow project (free tier works — [sign up here](https://app.playflowcloud.com))
* Your **Client API Key** (from Project Settings → starts with `pfclient_`)

<Warning>
  Use the **client** key (`pfclient_*`) for anything a game client can do. Use the **server** key (`pf_*`) only for trusted backend services or admin operations.
</Warning>

<Info>
  This quickstart assumes no player-auth provider is configured on the project (the free-tier default), so the `x-player-id` header names the player. If you've set up JWT, PlayFab, or Steam auth, client-key calls must send a valid `x-player-token` instead — see the [player authentication guide](/guides/player-authentication).
</Info>

***

## 1. Create a Lobby

A lobby is created by a "host" player. The host is whoever sends the `x-player-id` header on the create request.

```bash theme={null}
curl -X POST "https://api.computeflow.cloud/api/v3/lobbies/default" \
  -H "api-key: pfclient_YOUR_KEY" \
  -H "x-player-id: player1" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Lobby",
    "maxPlayers": 4
  }'
```

**Response:**

```json theme={null}
{
  "id": "a1b2c3d4-...",
  "code": "MEOW-42",
  "config": "default",
  "status": "waiting",
  "host": "player1",
  "currentPlayers": 1,
  "maxPlayers": 4,
  "players": [
    { "id": "player1", "state": null, "isHost": true }
  ],
  ...
}
```

<Check>
  **You just made a lobby.** No dashboard config was needed — PlayFlow used defaults. Note the `code` field: that's the invite code your players share.
</Check>

### About `{config}`

The `default` in the URL is a **lobby config name**. If no config with that name exists in your dashboard, PlayFlow uses sensible defaults:

* `timeout: 300s`
* `serverSize: small`
* Build: latest `default`

`maxPlayers` isn't a config default — it comes from the create request body (omit it and you get `2`). Set it explicitly on each create call, as shown above.

For production games, you'll create named configs in the dashboard (`casual`, `ranked_2v2`, etc.) with custom matchmaking rules and server overrides. But you don't need to yet.

***

## 2. Join as a Second Player

Share the invite code `MEOW-42` with your friend. They call:

```bash theme={null}
curl -X POST "https://api.computeflow.cloud/api/v3/lobbies/default/join" \
  -H "api-key: pfclient_YOUR_KEY" \
  -H "x-player-id: player2" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "MEOW-42",
    "state": { "team": "blue", "ready": false }
  }'
```

They could also join by **lobby ID** if they have it:

```bash theme={null}
curl -X POST "https://api.computeflow.cloud/api/v3/lobbies/default/join" \
  -H "api-key: pfclient_YOUR_KEY" \
  -H "x-player-id: player2" \
  -H "Content-Type: application/json" \
  -d '{
    "lobbyId": "a1b2c3d4-..."
  }'
```

The response is the full lobby, now with 2 players:

```json theme={null}
{
  "id": "a1b2c3d4-...",
  "currentPlayers": 2,
  "players": [
    { "id": "player1", "state": null, "isHost": true },
    { "id": "player2", "state": { "team": "blue", "ready": false }, "isHost": false }
  ],
  ...
}
```

***

## 3. Check Your Current Lobby

Any player can check which lobby they're in using `/me`:

```bash theme={null}
curl "https://api.computeflow.cloud/api/v3/lobbies/default/me" \
  -H "api-key: pfclient_YOUR_KEY" \
  -H "x-player-id: player2"
```

Returns the full lobby state. If you're not in a lobby, returns `404`.

<Tip>
  `/me` is the player-centric primitive throughout the API. Instead of tracking lobby IDs in your game, just use `/me` endpoints — PlayFlow finds your lobby automatically from the `x-player-id` header.
</Tip>

***

## 4. Update Player State

Ready up, pick a character, set your MMR — anything goes in player state. The server merges your updates into existing state.

```bash theme={null}
curl -X PATCH "https://api.computeflow.cloud/api/v3/lobbies/default/me" \
  -H "api-key: pfclient_YOUR_KEY" \
  -H "x-player-id: player2" \
  -H "Content-Type: application/json" \
  -d '{
    "state": {
      "ready": true,
      "loadout": "sniper",
      "mmr": 1500
    }
  }'
```

The response shows `player2`'s updated state:

```json theme={null}
{
  "players": [
    { "id": "player1", "state": null, "isHost": true },
    {
      "id": "player2",
      "state": {
        "team": "blue",
        "ready": true,
        "loadout": "sniper",
        "mmr": 1500
      },
      "isHost": false
    }
  ],
  ...
}
```

<Info>
  State updates **merge** — existing keys are preserved unless overwritten. Setting `ready: true` doesn't wipe out `team: blue`.
</Info>

***

## 5. Start the Game

When ready, the host launches a game server directly:

```bash theme={null}
curl -X POST "https://api.computeflow.cloud/api/v3/lobbies/default/me/start" \
  -H "api-key: pfclient_YOUR_KEY" \
  -H "x-player-id: player1"
```

The response now has `server` populated:

```json theme={null}
{
  "status": "in_game",
  "server": {
    "instance_id": "srv-abc123",
    "status": "launching",
    "region": "us-east",
    "network_ports": [
      {
        "name": "game_udp",
        "host": "203.0.113.42",
        "external_port": 30234,
        "internal_port": 7770,
        "protocol": "udp",
        "tls_enabled": false
      }
    ]
  },
  ...
}
```

Use `server.network_ports[0].host` and `server.network_ports[0].external_port` to connect your game client. The `server` block is the same shape as `GET /v3/servers/{instance_id}`. The server transitions from `launching` → `running` in typically 10-30 seconds.

<Warning>
  Only the **host** can start the game. If a non-host tries, they get a `403` with the message "Only the host can perform this action". Lobby errors return `{error, detail, status}` — branch on the HTTP status, not the message text.
</Warning>

***

## 6. Leave (Cleanup)

Every player leaves with:

```bash theme={null}
curl -X DELETE "https://api.computeflow.cloud/api/v3/lobbies/default/me" \
  -H "api-key: pfclient_YOUR_KEY" \
  -H "x-player-id: player2"
```

When the **last player** leaves, the lobby auto-deletes. The response is `{"status": "lobby_deleted"}`.

If the **host** leaves while others remain, host transfers to the next player automatically.

***

## That's It

You've now exercised the full lobby lifecycle using just 6 API calls. The full API adds matchmaking, host-only actions (kick, settings), invite code joining, lobby browsing, real-time SSE updates, and more — but this is the 80% of what most games need.

<CardGroup>
  <Card title="Lobby Lifecycle" icon="arrows-rotate" href="/lobbies/lifecycle">
    Host-only actions (kick, settings, transfer host), leaving behavior, error handling.
  </Card>

  <Card title="Matchmaking" icon="swords" href="/lobbies/matchmaking">
    Skip the manual "start" — let PlayFlow find opponents automatically.
  </Card>

  <Card title="Real-time Events" icon="bolt" href="/lobbies/real-time">
    Stop polling. Subscribe to live events with SSE.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Every endpoint with full schemas and try-it-out.
  </Card>
</CardGroup>


# Real-time Events
Source: https://docs.playflowcloud.com/lobbies/real-time

Subscribe to live lobby updates with Server-Sent Events (SSE). Stop polling. Get instant notifications when players join, matches form, servers launch.

PlayFlow provides a single SSE endpoint per player that streams everything you need: lobby updates, queue stats, match notifications, and server status changes. No polling required.

## The Endpoint

```bash theme={null}
GET /v3/lobbies/{config}/me/events
x-player-id: {player_id}
api-key: {key}
Accept: text/event-stream
```

* **One connection per player** is enough — all events for their current lobby flow through it
* The connection stays open indefinitely (with keep-alive pings every 30s)
* When the player leaves the lobby, close the connection

<Info>
  **Player auth:** If your project has a player-auth provider configured (`custom_jwt`, `playfab`, or `steam`), client-key (`pfclient_*`) requests must also send an `x-player-token: {verified token}` header — `x-player-id` alone only works when the provider is `none` or when you use a server key (`pf_*`). Without it, every request below returns `401`. See [Player Authentication](/guides/player-authentication) for setup.
</Info>

<Info>
  The SSE connection doubles as a **heartbeat**. As long as the stream is open, PlayFlow knows the player is alive. You don't need a separate heartbeat endpoint unless you're not using SSE (e.g., polling clients on legacy platforms).
</Info>

***

## Event Types

| Event           | When it fires                | Data                                                   |
| :-------------- | :--------------------------- | :----------------------------------------------------- |
| `connected`     | Right after connection opens | Full lobby state                                       |
| `lobby_updated` | Any time the lobby changes   | Full lobby state                                       |
| `queue_stats`   | Every 10s while `in_queue`   | `{ playersSearching, lobbiesInQueue, avgWaitSeconds }` |
| `lobby_deleted` | Lobby was deleted            | `{ id, reason }`                                       |
| `ping`          | Every 30s (keep-alive)       | `{ ts }` (epoch ms)                                    |

### Event: `connected`

Fires immediately on connection. Gives you the full current state — no need to call `GET /me` first.

```
event: connected
data: {"id":"abc-123","status":"waiting","host":"p1","players":[...],...}
```

### Event: `lobby_updated`

Fires whenever the lobby changes:

* A player joins or leaves
* Host kicks someone
* A player updates their state
* Host changes settings
* Host starts matchmaking / game
* Match found → status becomes `in_game`
* Game server status changes (launching → running)

```
event: lobby_updated
data: {"id":"abc-123","status":"in_game","server":{"status":"running","network_ports":[{"name":"game_udp","host":"1.2.3.4","external_port":30234,"internal_port":7770,"protocol":"udp","tls_enabled":false}]},...}
```

**Key usage:** When `status` becomes `in_game` and `server.status` becomes `running`, read `host` and `external_port` from `server.network_ports[]` (never assume a fixed port — the external port is proxy-allocated) and connect your game client.

### Event: `queue_stats`

Only fires while `status: in_queue`. Emitted every 10 seconds.

```
event: queue_stats
data: {"playersSearching":42,"lobbiesInQueue":8,"avgWaitSeconds":12.3}
```

Use this to show live "42 searching, \~12s wait" in your matchmaking UI.

### Event: `lobby_deleted`

Fires when the lobby is deleted (last player left, host deleted it, or cleanup timeout).

```
event: lobby_deleted
data: {"id":"abc-123","reason":"match_ended"}
```

The `reason` field tells you why the lobby closed, so you can differentiate a completed match from a timeout:

| `reason`            | Meaning                                                           |
| :------------------ | :---------------------------------------------------------------- |
| `match_ended`       | The game finished (lobby was `in_game`)                           |
| `closed_or_expired` | Closed before play — last player left, cleanup timeout, or expiry |
| `closed`            | Closed for any other reason                                       |

Close the connection on this event — there's nothing left to subscribe to.

### Event: `ping`

Keep-alive every 30 seconds. Carries a `{ ts }` payload (epoch milliseconds). You can ignore these in your handler — they exist only to keep the connection alive through proxies and load balancers.

```
event: ping
data: {"ts":1752345678901}
```

***

## Client Examples

<Tabs>
  <Tab title="JavaScript (Browser)">
    ```javascript theme={null}
    const playerId = "player_123";
    const config = "ranked";
    const apiKey = "pfclient_...";

    // Note: EventSource doesn't support custom headers directly.
    // Pass the api-key and player-id via query params or use a polyfill.
    const url = `https://api.computeflow.cloud/api/v3/lobbies/${config}/me/events`;

    // Use fetch + ReadableStream for full header support:
    const res = await fetch(url, {
      headers: {
        "api-key": apiKey,
        "x-player-id": playerId,
        "Accept": "text/event-stream",
      },
    });

    const reader = res.body.getReader();
    const decoder = new TextDecoder();
    let buffer = "";

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;
      
      buffer += decoder.decode(value, { stream: true });
      const events = buffer.split("\n\n");
      buffer = events.pop() ?? "";
      
      for (const block of events) {
        const eventMatch = block.match(/^event: (.+)$/m);
        const dataMatch = block.match(/^data: (.+)$/m);
        if (!eventMatch || !dataMatch) continue;
        
        const eventType = eventMatch[1];
        const data = JSON.parse(dataMatch[1]);
        
        switch (eventType) {
          case "connected":
          case "lobby_updated":
            console.log("Lobby:", data);
            if (data.status === "in_game" && data.server?.status === "running") {
              const port = data.server.network_ports[0];
              connectToGameServer(port.host, port.external_port);
            }
            break;
          case "queue_stats":
            updateQueueUI(data.playersSearching, data.avgWaitSeconds);
            break;
          case "lobby_deleted":
            console.log("Lobby deleted");
            return;
        }
      }
    }
    ```
  </Tab>

  <Tab title="Unity (C#)">
    ```csharp theme={null}
    using System.Collections;
    using UnityEngine;
    using UnityEngine.Networking;

    public class LobbyEventStream : MonoBehaviour
    {
        [SerializeField] string apiKey = "pfclient_...";
        [SerializeField] string playerId = "player_123";
        [SerializeField] string config = "ranked";
        
        UnityWebRequest request;
        
        public IEnumerator Connect()
        {
            var url = $"https://api.computeflow.cloud/api/v3/lobbies/{config}/me/events";
            request = UnityWebRequest.Get(url);
            request.SetRequestHeader("api-key", apiKey);
            request.SetRequestHeader("x-player-id", playerId);
            request.SetRequestHeader("Accept", "text/event-stream");
            request.downloadHandler = new SSEDownloadHandler(OnEvent);
            yield return request.SendWebRequest();
        }
        
        void OnEvent(string eventType, string data)
        {
            switch (eventType)
            {
                case "connected":
                case "lobby_updated":
                    var lobby = JsonUtility.FromJson<Lobby>(data);
                    HandleLobbyUpdate(lobby);
                    break;
                case "queue_stats":
                    var stats = JsonUtility.FromJson<QueueStats>(data);
                    UpdateQueueUI(stats);
                    break;
                case "lobby_deleted":
                    CleanupAndGoToMenu();
                    break;
            }
        }
        
        void HandleLobbyUpdate(Lobby lobby)
        {
            if (lobby.status == "in_game" && lobby.server?.status == "running")
            {
                var port = lobby.server.network_ports[0];
                // Connect your netcode (Mirror, Fishnet, Netcode for GameObjects...)
                NetworkManager.singleton.StartClient(port.host, port.external_port);
            }
        }
    }
    ```

    <Tip>
      The PlayFlow Unity SDK ships with an SSE handler. You don't need to write this from scratch.
    </Tip>
  </Tab>

  <Tab title="Godot (GDScript)">
    ```gdscript theme={null}
    extends Node

    var api_key = "pfclient_..."
    var player_id = "player_123"
    var config = "ranked"
    var http_client: HTTPClient

    func connect_events():
        http_client = HTTPClient.new()
        http_client.connect_to_host("api.computeflow.cloud", 443, TLSOptions.client())
        
        while http_client.get_status() == HTTPClient.STATUS_CONNECTING or http_client.get_status() == HTTPClient.STATUS_RESOLVING:
            http_client.poll()
            await get_tree().process_frame
        
        var headers = [
            "api-key: " + api_key,
            "x-player-id: " + player_id,
            "Accept: text/event-stream",
        ]
        http_client.request(HTTPClient.METHOD_GET, "/api/v3/lobbies/%s/me/events" % config, headers)
        
        # Process stream (simplified)
        while http_client.get_status() == HTTPClient.STATUS_BODY:
            http_client.poll()
            var chunk = http_client.read_response_body_chunk()
            if chunk.size() > 0:
                process_sse_chunk(chunk.get_string_from_utf8())
            await get_tree().process_frame
    ```
  </Tab>

  <Tab title="curl (testing)">
    ```bash theme={null}
    curl -N \
      -H "api-key: pfclient_..." \
      -H "x-player-id: test_player" \
      -H "Accept: text/event-stream" \
      "https://api.computeflow.cloud/api/v3/lobbies/default/me/events"
    ```

    Output (live):

    ```
    event: connected
    data: {"id":"abc-123","status":"waiting",...}

    event: lobby_updated
    data: {"id":"abc-123","status":"waiting","currentPlayers":2,...}

    event: ping
    data: {"ts":1752345678901}

    ```

    Useful for debugging — watch events live as you trigger state changes from another terminal.
  </Tab>
</Tabs>

***

## Handling Disconnects

SSE connections can drop due to network issues, proxy timeouts, or server restarts. Your client should:

1. **Detect disconnect** — the read loop exits or the connection errors
2. **Reconnect automatically** — with exponential backoff (1s, 2s, 4s, max 30s)
3. **Replay state on reconnect** — the `connected` event sends the current full state, so you can recover cleanly

<Warning>
  While disconnected, you **won't receive events**. You might miss a match, a kick, or a server ready event. Your reconnect logic should fetch `GET /me` on reconnect to ensure state consistency, OR rely on the `connected` event's initial state.
</Warning>

***

## Polling as a Fallback

If SSE isn't available (e.g., your platform blocks streaming), poll `GET /me` instead:

```bash theme={null}
# Every 2-5 seconds
curl "https://api.computeflow.cloud/api/v3/lobbies/{config}/me" \
  -H "api-key: pfclient_..." \
  -H "x-player-id: {player}"
```

When polling, enable `heartbeat: true` in your lobby config and send a heartbeat on each tick (well under `heartbeatTimeout` seconds). Without SSE keeping the player implicitly alive, the `lobby-sweep` cron will otherwise evict inactive players:

```bash theme={null}
POST /v3/lobbies/{config}/me/heartbeat
x-player-id: {player}
```

***

## The Full Matchmaking Flow with SSE

This is what a player's event stream looks like during a matchmaking session:

```
# 1. Connect
event: connected
data: {"status":"waiting","players":[{"id":"p1","isHost":true}],...}

# 2. Player starts matchmaking
event: lobby_updated
data: {"status":"in_queue","matchmaking":{"mode":"5v5","queueStats":{...}}}

# 3. Queue stats stream every 10s
event: queue_stats
data: {"playersSearching":42,"avgWaitSeconds":12.3}

event: queue_stats
data: {"playersSearching":45,"avgWaitSeconds":11.8}

# 4. Match found! Server launching
event: lobby_updated
data: {"status":"in_game","matchId":"m_abc","server":{"status":"launching","network_ports":[]}}
# Note: if match confirmation is enabled for the mode, an intermediate
# lobby_updated with "status":"match_found" fires first — each player must
# call POST /me/confirm-match before the lobby advances to "in_game".

# 5. Server ready
event: lobby_updated
data: {"status":"in_game","server":{"status":"running","network_ports":[{"name":"game_udp","host":"1.2.3.4","external_port":30234,"internal_port":7770,"protocol":"udp","tls_enabled":false}]}}
# → Client now connects to 1.2.3.4:30234 (external_port)

# 6. Game ends, lobby cleanup
event: lobby_deleted
data: {"id":"abc-123","reason":"match_ended"}
```

That's the entire competitive matchmaking experience — queue, find opponents, launch server, connect — delivered through one SSE stream.

<CardGroup>
  <Card title="Matchmaking" icon="swords" href="/lobbies/matchmaking">
    How matchmaking finds opponents and forms matches.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Full SSE endpoint reference.
  </Card>
</CardGroup>


# Quick Start - Fish-Net
Source: https://docs.playflowcloud.com/quickstart/fishnet

Step-by-step tutorial for getting up and running with PlayFlow Cloud

# Getting Started with PlayFlow

<iframe title="Fish-Net on PlayFlow Cloud Tutorial" />

***

## Written Tutorial

This guide assumes you have some or all of your game already written using Fish-Net and are now ready to use PlayFlow to implement a dedicated server. You can also use PlayFlow throughout the development process as its one-click deployment makes it easy to setup a temporary server for testing.

<Info>
  This guide is based on the [official Fish-Net PlayFlow tutorial](https://fish-networking.gitbook.io/docs/guides/server-hosting/services/playflow-cloud/getting-started-with-playflow). Visit their guide for additional details.
</Info>

## Before We Begin

<Steps>
  <Step title="Starting Project">
    If you don't have a project already setup but want to follow this tutorial, you can use the Fish-Net getting started tutorial project.

    <Card title="Getting Started Project" icon="download" href="https://github.com/maxkratt/fish-networking-getting-started/releases/download/using-syncvars-to-sync-colors/using-syncvars-to-sync-colors.unitypackage">
      Download the Fish-Net tutorial project files
    </Card>
  </Step>

  <Step title="Install the PlayFlow SDK">
    Now that we're ready to start, let's install PlayFlow Cloud. You can directly import it with the following git URL:

    ```
    https://github.com/PlayFlowCloud/PlayFlow-Multiplayer-Unity-SDK.git
    ```

    Simply add this through the Unity Package Manager and you'll be ready to continue!

    <Info>
      If you need more detailed instructions for this step, check out the [Installation Guide](/guides/installation).
    </Info>
  </Step>

  <Step title="Add the Necessary Unity Modules">
    Ensure your Unity installation has the correct modules for building a server. Install the **Linux Build Support** modules for your Unity version in the Unity Hub.

    <Info>
      Exact details on the required modules depending on your Unity version can be found in the [Unity Modules Setup](/guides/unity-modules) guide.
    </Info>
  </Step>

  <Step title="Add Tugboat">
    Select the NetworkManager in your project and add the Tugboat component if it isn't already there (if you are using a different transport, that is also fine).

    **Enable the "Reuse Address" checkbox** - this will be needed for our server to work correctly.

    <img alt="Tugboat Reuse Address Setting" />

    The other two fields we'll be paying attention to are the **Port** and **Client Address** ones. For now you can leave the default settings, we'll remember the port number (7770) for later.
  </Step>

  <Step title="Manage Auto Start">
    We want Fish-Net to automatically start as a server in the server build. Fish-Net will actually do this by default with the "Start on Headless" option on the ServerManager. If you disabled this, be sure to manage starting the server itself, or simply re-enable it.

    If you have set the NetworkHudCanvas Auto Start Type to something other than **Disabled**, then you will want to disable it now, since we want our server to only behave as a server.

    <img alt="Setting Auto Start Type to Disabled" />
  </Step>
</Steps>

Once that's all done we can move on to using PlayFlow Cloud!

## Deploying Your Game with PlayFlow

<Steps>
  <Step title="Create Your PlayFlow Account">
    Go to the [PlayFlow Cloud website](https://app.playflowcloud.com/) and sign-up using your email, or log in with your GitHub or Google account. If asked, confirm your email address to complete the setup.
  </Step>

  <Step title="Create an Organization">
    You'll now be prompted to create an Organization. Organizations hold your projects and let you collaborate with teammates.

    Enter an organization name and click **Create Organization**. Every new organization starts on the **Free** plan, which is perfect for this tutorial. You can read more about the plan types [here](/fundamentals/plan-instance-types). When you're ready for more capacity, you can upgrade to **Pro** at any time from your organization's billing settings.

    <Info>
      You can invite teammates and manage Team Collaboration from your organization settings once it's created, on either plan.
    </Info>
  </Step>

  <Step title="Create a New Project">
    Now that you've created your first Organization, you'll be prompted to choose it and then we can move forward with creating a new project.

    Click the **Create New Project** button and enter the details of your project:

    * **Project Name**: Give your project any fitting name you'd like
    * **Game Engine**: Select **Unity** as the Game Engine

    Click **Create Project** to proceed.
  </Step>

  <Step title="Explore the Dashboard">
    With your new project created and selected, you can check out the PlayFlow dashboard for it.

    PlayFlow has a lot of powerful features and makes it very easy for you, the developer of your game, to view the logs, metrics, server details and more. The PlayFlow dashboard can also be used to directly upload your game's server builds and manage server instances.

    <img alt="PlayFlow Dashboard" />

    Once you're done looking around, we'll jump into setting up our server build and running it.
  </Step>

  <Step title="Link the PlayFlow SDK to Your Project">
    Now let's link our Unity Project to the PlayFlow one we've just created.

    1. Open the **Overview** page in the PlayFlow dashboard
    2. Find the **API Keys** section and click the **View API Keys** button
    3. Copy the **PlayFlow API Key** to your clipboard
    4. In Unity Editor, open the PlayFlow window from the Toolbar at **PlayFlow → PlayFlow Cloud**
    5. Inside the Token field, paste the **PlayFlow API Key** you copied

       <img alt="PlayFlow SDK Window" />
  </Step>

  <Step title="Build and Upload the Server">
    You can now customize the other settings in the PlayFlow Cloud window, such as the Development Build or Server Scene.

    When you're happy with those, press the **Upload Server** button to have PlayFlow automatically build and upload a headless Linux server build of your game. This will take a brief moment, and then you will have a log in the editor console saying the build uploaded successfully.

    If needed, you can browse the files of the build and delete it directly from the PlayFlow Dashboard under the Builds tab; pressing the **View Builds** button in the PlayFlow window will open this directly for you.
  </Step>

  <Step title="Setup the PlayFlow Port">
    Now we will setup the port to use in the PlayFlow dashboard. Open up the website, go to the project **Settings** tab, then the **Configuration → Network Ports** section. Click the **Add Port** button and fill in the fields.

    <img alt="Add New Port Configuration" />

    * **Port Name**: We can enter a simple name for it here, we'll just call ours `getting_started_udp`
    * **Port Number**: This field should be filled in with the port we have entered in our Transport's Port field. Since we are using Tugboat, the default is `7770`, so enter that now
    * **Protocol**: This is the protocol used by your transport, Tugboat uses UDP, so leave that as the option
    * **Description (Optional)**: This field is optional and self-explanatory

    Once those are entered, click the **Add Port** button to finish this step.
  </Step>

  <Step title="Create the Server">
    Now we are ready to start our server, head over to the Servers tab and click the **Create Your First Server** button.

    <img alt="Create Server Dialog" />

    A window will pop-up letting you customize the settings for this server. You can change the **Name** to "Fish-Net Getting Started", or choose any name you like as well as customizing the other settings to better suit your needs. Once you are happy, press **Create Server**.

    You should now see the server in the Servers tab and you can see its details or stop it directly from here.

    <img alt="Launching Servers View" />
  </Step>

  <Step title="Connect to the Server">
    Click on the **Details** button to see the details of the server. You can view the Details, Metrics, and Logs of the server here. We will look at the **Details → Network** section and copy the Host and the External Port fields.

    <img alt="Server Details" />

    In the Unity Editor, select the Tugboat component (or other transport you may be using):

    * Enter the IP Address you copied from the **Host** field into the Transport's Client Address field
    * Enter the **Port** you copied into the Transport's Port field
  </Step>

  <Step title="Test the Game">
    You can now run the game or build and run it and connect as a client. Your game should connect to the PlayFlow server we setup and work correctly!
  </Step>
</Steps>

## Take the Next Steps!

Well done! You've now learned how to setup and deploy your server using PlayFlow.

## Resources

* **PlayFlow Documentation**: [docs.playflowcloud.com](https://docs.playflowcloud.com/)
* **PlayFlow Discord**: [discord.gg/P5w45Vx5Q8](https://discord.gg/P5w45Vx5Q8)
* **Fish-Net Documentation**: [fish-networking.gitbook.io](https://fish-networking.gitbook.io/docs/)

## Next Steps

<CardGroup>
  <Card title="WebGL Deployment" icon="globe" href="/quickstart/fishnet-webgl">
    Deploy Fish-Net for web browsers
  </Card>

  <Card title="Lobby System" icon="users" href="/unity/lobby-overview">
    Add Fish-Net compatible lobbies
  </Card>

  <Card title="Matchmaking" icon="shuffle" href="/unity/matchmaking">
    Implement ranked matchmaking
  </Card>
</CardGroup>


# Quick Start - Fish-Net WebGL
Source: https://docs.playflowcloud.com/quickstart/fishnet-webgl

Simple tutorial showing how easy PlayFlow makes it to host a server for your WebGL game

# Easy WebGL Hosting with PlayFlow

## How PlayFlow Makes WebGL Hosting Easy

For seamless WebGL gaming experiences in web browsers, secure WebSocket connections are crucial, but configuring them can be complex. Often, developers end up managing certificates and networking issues, which can be time-consuming. **With PlayFlow**, however, you only need to enable a simple option to handle these concerns effortlessly.

<Info>
  This guide is based on the [official Fish-Net WebGL tutorial](https://fish-networking.gitbook.io/docs/guides/server-hosting/services/playflow-cloud/easy-webgl-hosting-with-playflow). Visit their guide for additional screenshots and details.
</Info>

## Before We Begin

<Warning>
  This tutorial assumes you've already completed the [standard Fish-Net setup](/quickstart/fishnet). In the following steps, we'll convert your project to support WebGL.
</Warning>

## Setup Steps

<Steps>
  <Step title="Install Bayou">
    For Fish-Net connections on WebGL, we need a web-supported transport. This tutorial uses **Bayou**.

    1. Download the latest `unitypackage` from [Bayou GitHub Releases](https://github.com/FirstGearGames/Bayou/releases/latest)
    2. Import it into your Unity project

       <img alt="Bayou Latest Release" />
  </Step>

  <Step title="Add Bayou to NetworkManager">
    1. Select your NetworkManager in the scene
    2. Add the **Bayou** component to it

       <img alt="Bayou Added to NetworkManager" />

    <Info>
      If you have multiple transports (like Tugboat), add the **TransportManager** component and drag Bayou into its **Transport** field to set it as active.
    </Info>
  </Step>

  <Step title="Enable WSS">
    In the Bayou component:

    1. Enable the **"Use WSS"** option (Web Socket Secure)
    2. SSL Configuration options will appear below - **don't modify these** for PlayFlow

       <img alt="Bayou WSS Enabled" />

    <Warning>
      PlayFlow handles all SSL configuration automatically when you enable TLS.
    </Warning>
  </Step>

  <Step title="Build Your PlayFlow Server">
    Open the PlayFlow Cloud window from Unity toolbar (**PlayFlow → PlayFlow Cloud**).

    Click **Upload Server** to build and upload your Unity server.

    <img alt="PlayFlow Uploading Server" />
  </Step>

  <Step title="Configure PlayFlow Port Protocol">
    In the [PlayFlow dashboard](https://app.playflowcloud.com/):

    1. Navigate to **Configuration** tab
    2. Add or edit your port
    3. Choose **TCP** protocol
    4. **Enable TLS** ✓ (Critical for WebGL)
    5. Save configuration

       <img alt="PlayFlow TCP TLS Configuration" />

    <Info>
      **Why TCP with TLS?** WebGL requires secure WebSocket connections. PlayFlow handles the SSL certificates automatically when you enable TLS. TLS is a separate checkbox that can only be enabled on **TCP** ports, so choose TCP first, then tick TLS.
    </Info>
  </Step>

  <Step title="Start a PlayFlow Server">
    1. Go to the **Servers** tab in PlayFlow
    2. Create your server instance
    3. Select your uploaded build
    4. Launch the server

       <img alt="PlayFlow Create WebGL Server" />
  </Step>

  <Step title="Prepare Your Client Build">
    1. Click on your server instance's **Details**
    2. Look for the **TLS Connection** information (this maps to the `host` and `external_port` of the TCP entry in the server's `network_ports` array from the API)
    3. In Unity, select the Bayou component
    4. Enter the TLS **host** into the **Client Address** field
    5. Enter the **external port** into the **Port** field

    <Warning>
      **Read the host and port from your server, never hardcode them.** The TLS host and the external port are shown in the server's TLS Connection details (and returned in the `network_ports[]` array from the API). The external port is allocated per server and differs from your internal port, so copy the exact values PlayFlow gives you rather than assuming a fixed hostname or port.
    </Warning>

    <img alt="PlayFlow Server Details" />

    <img alt="Bayou Configuration" />
  </Step>

  <Step title="Build Your WebGL Client">
    1. In Unity, switch to **WebGL** platform in Build Settings
    2. Build your game
    3. Zip the built files
    4. Upload to your chosen hosting platform (e.g., itch.io, GitHub Pages)

       <img alt="Zipped WebGL Files" />

    <Info>
      The example below shows hosting on itch.io:
    </Info>

    <img alt="itch.io WebGL Game" />
  </Step>
</Steps>

## Success!

Just like that, you've created a server and have your clients in the web browser securely connecting to it!

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection Failed">
    * Verify TLS is enabled in PlayFlow port settings
    * Check that the client is using the TLS host copied from the server details (not an IP address)
    * Ensure "Use WSS" is enabled in Bayou
    * Confirm the external port matches the value from your server's `network_ports` (it is allocated per server and differs from the internal port)
  </Accordion>

  <Accordion title="Multiple Transports Issue">
    If you have both Tugboat and Bayou on your NetworkManager, make sure to add TransportManager component and set Bayou as the active transport.
  </Accordion>

  <Accordion title="SSL Configuration">
    Don't modify the SSL Configuration settings in Bayou - PlayFlow handles all certificates automatically when TLS is enabled.
  </Accordion>
</AccordionGroup>

## Resources

* **PlayFlow Documentation**: [docs.playflowcloud.com](https://docs.playflowcloud.com/)
* **PlayFlow Discord**: [discord.gg/P5w45Vx5Q8](https://discord.gg/P5w45Vx5Q8)
* **Fish-Net Documentation**: [fish-networking.gitbook.io](https://fish-networking.gitbook.io/docs/)

## Related Guides

<CardGroup>
  <Card title="WebGL Deployments" icon="browser" href="/guides/webgl-deployments">
    Advanced WebGL deployment strategies
  </Card>

  <Card title="Fish-Net Standard" icon="fish" href="/quickstart/fishnet">
    Standard Fish-Net setup for desktop/mobile
  </Card>

  <Card title="Lobby System" icon="users" href="/unity/lobby-overview">
    Add lobbies to your WebGL game
  </Card>
</CardGroup>


# Quick Start - Godot
Source: https://docs.playflowcloud.com/quickstart/godot

Step-by-step tutorial for getting up and running with Godot on PlayFlow Cloud

# Getting Started with Godot on PlayFlow

This guide assumes you have some or all of your game already written using Godot and are now ready to use PlayFlow to implement a dedicated server. You can also use PlayFlow throughout the development process as its one-click deployment makes it easy to setup a temporary server for testing.

<Info>
  **Godot 4.x** - This guide uses Godot 4.4, but any 4.x version should work. We'll be using WebSocket networking for cross-platform compatibility.
</Info>

## Prerequisites

Before you start, make sure you have:

* **Godot 4.x** installed with the Linux export templates
* A **PlayFlow Cloud account** (created in the first step below)
* A Godot project with multiplayer networking, or you can follow the [multiplayer game tutorial](/guides/godot-first-multiplayer-game) to build one from scratch

## Before We Begin

<Steps>
  <Step title="Starting Project">
    If you don't have a project already setup but want to follow this tutorial, you can create a complete multiplayer game from scratch using our comprehensive guide.

    <Card title="Create Your First Multiplayer Game" icon="gamepad-2" href="/guides/godot-first-multiplayer-game">
      Complete tutorial for building a multiplayer game in Godot with PlayFlow
    </Card>
  </Step>

  <Step title="Configure Server Auto-Start">
    Configure your game to automatically start as a server in headless builds. In your main multiplayer manager script, add server detection:

    ```gdscript theme={null}
    func _ready() -> void:
        if OS.has_feature("dedicated_server"):
            start_server()
    ```

    This ensures your server starts automatically when deployed to PlayFlow.
  </Step>
</Steps>

Once that's all done we can move on to using PlayFlow Cloud!

## Deploying Your Game with PlayFlow

<Steps>
  <Step title="Create Your PlayFlow Account">
    Go to the [PlayFlow Cloud website](https://app.playflowcloud.com/) and sign-up using your email, or log in with your GitHub or Google account. If asked, confirm your email address to complete the setup.
  </Step>

  <Step title="Create an Organization">
    Create an Organization to hold your projects (and your team, on Pro).

    * Enter an organization name
    * Click **Create Organization**

    <Info>
      New organizations start on the **Free** plan (max 1 active server, forced `small` size, 1-hour TTL). You can upgrade to **Pro** later from **Billing** in your project settings to unlock all compute sizes, longer TTLs, and unlimited active servers.
    </Info>
  </Step>

  <Step title="Create a New Project">
    Click **Create New Project** and enter:

    * **Project Name**: Your game name
    * **Game Engine**: Godot

    Click **Create Project** to proceed.
  </Step>

  <Step title="Export Your Server Build">
    1. Go to **Project → Export** in Godot
    2. Add a **Linux/X11** export preset
    3. In the **Resources** tab, set **Export Mode** to "Export as dedicated server"
    4. **IMPORTANT**: Name your executable "Server" (required by PlayFlow)
    5. Export your project and create a .zip archive of all files

    <Info>
      The dedicated server export creates a headless build perfect for PlayFlow deployment.
    </Info>
  </Step>

  <Step title="Upload Your Server Build">
    1. In the PlayFlow dashboard, go to the **Builds** tab
    2. Click **Upload Build**
    3. Upload your .zip file containing the server executable
    4. Wait for the upload to complete

    <Info>
      PlayFlow will automatically detect and configure your Godot server build.
    </Info>
  </Step>

  <Step title="Setup the PlayFlow Port">
    Now we will setup the port to use in the PlayFlow dashboard. Open up the website and head to the **Configuration** tab and then **Network Ports** section. Click the **Add Your First Port** button and fill in the fields.

    <img alt="PlayFlow TCP TLS Configuration" />

    * **Port Name**: `godot_websocket`
    * **Port Number**: `8080` (or your configured port)
    * **Protocol**: **TCP**
    * **Enable TLS**: **Yes** (required for "wss\://" connections from web clients)
    * **Description (Optional)**: WebSocket port for Godot multiplayer

    Click the **Add Port** button to finish this step.

    <Warning>
      **Enable TLS** is critical for web browser compatibility. Without TLS, web clients cannot connect using "wss\://" protocol.
    </Warning>
  </Step>

  <Step title="Create the Server">
    Now we are ready to start our server, head over to the Servers tab and click the **Create Your First Server** button.

    <img alt="Create Server Dialog" />

    A window will pop-up letting you customize the settings for this server. You can change the **Name** to "Godot Game Server", or choose any name you like as well as customizing the other settings to better suit your needs. Once you are happy, press **Create Server**.

    You should now see the server in the Servers tab and you can see its details or stop it directly from here.

    <img alt="Launching Servers View" />
  </Step>

  <Step title="Connect to the Server">
    Click on the **Details** button to see the details of the server. Look at the **Details → Network** section and copy the Host and External Port.

    <img alt="Server Details" />

    Configure your Godot client with the PlayFlow server details:

    **In your connection script:**

    ```gdscript theme={null}
    func connect_to_server(host: String, port: String):
        var peer = WebSocketMultiplayerPeer.new()
        var url = "wss://" + host + ":" + port
        var error = peer.create_client(url)
        if error == OK:
            multiplayer.multiplayer_peer = peer
    ```

    <Info>
      **For Web Builds**: Always use "wss\://" protocol for secure WebSocket connections. For local testing, you can use "ws\://" but production deployments should use TLS.
    </Info>
  </Step>

  <Step title="Test the Game">
    1. Run your Godot project locally or export a client build
    2. Enter the PlayFlow Host and External Port in your connection UI
    3. Connect to the server
    4. Your game should connect to the PlayFlow server and work correctly!

    <Tip>
      **Testing Multiple Clients**: Enable **Debug → Customize Run Instances → Enable Multiple Instances** in Godot to test multiple clients connecting to your PlayFlow server.
    </Tip>
  </Step>
</Steps>

## Take the Next Steps!

Well done! You've now learned how to setup and deploy your Godot server using PlayFlow.

## Resources

* **PlayFlow Documentation**: [docs.playflowcloud.com](https://docs.playflowcloud.com/)
* **PlayFlow Discord**: [discord.gg/P5w45Vx5Q8](https://discord.gg/P5w45Vx5Q8)
* **Godot Documentation**: [docs.godotengine.org](https://docs.godotengine.org/)
* **Godot Multiplayer**: [docs.godotengine.org/en/stable/tutorials/networking](https://docs.godotengine.org/en/stable/tutorials/networking/)

## Next Steps

<CardGroup>
  <Card title="Complete Multiplayer Tutorial" icon="gamepad-2" href="/guides/godot-first-multiplayer-game">
    Build a complete multiplayer game from scratch
  </Card>

  <Card title="Lobby System" icon="users" href="/unity/lobby-overview">
    Add lobbies to your Godot game
  </Card>

  <Card title="Matchmaking" icon="shuffle" href="/unity/matchmaking">
    Implement matchmaking for competitive play
  </Card>
</CardGroup>

<Info>
  PlayFlow's lobby and matchmaking systems are engine-agnostic REST APIs (`/api/v3/lobbies`), so they work from Godot too. The linked pages use Unity examples, but the same HTTP endpoints apply — call them from GDScript with `HTTPRequest`, sending your key in the `api-key` header.
</Info>

## Common Issues

<AccordionGroup>
  <Accordion title="Server not starting automatically">
    Ensure your server detection script uses `OS.has_feature("dedicated_server")` and that the "Export as dedicated server" option is enabled in your export preset.
  </Accordion>

  <Accordion title="Web clients can't connect">
    * Verify TLS is enabled in PlayFlow port configuration
    * Ensure you're using "wss\://" protocol for web clients
    * Check that the port (8080) matches between your server code and PlayFlow configuration
    * Verify firewall rules aren't blocking connections
  </Accordion>

  <Accordion title="Players not spawning or synchronizing">
    * Check that MultiplayerSpawner is properly configured
    * Verify MultiplayerSynchronizer is set up on player scenes
    * Ensure players are being added to the correct groups
    * Check that spawn functions are called when peers connect
  </Accordion>

  <Accordion title="Connection timeout or failed">
    * Verify the server URL and port are correct
    * Check that the PlayFlow server instance is running
    * For local testing, use "ws\://" instead of "wss\://"
    * Ensure your networking code handles connection failures gracefully
  </Accordion>
</AccordionGroup>


# Quick Start - Any Game Engine
Source: https://docs.playflowcloud.com/quickstart/index

Choose your networking framework and deploy your first game server on PlayFlow Cloud

# Choose Your Quick Start Guide

Select the networking framework you're using to get started with PlayFlow Cloud.

## Video Tutorial

<iframe title="Unity on PlayFlow Cloud Tutorial" />

<Tip>
  This video demonstrates deploying Unity games to PlayFlow Cloud. The concepts apply to all Unity networking frameworks.
</Tip>

## Popular Networking Frameworks

PlayFlow's backend is engine-agnostic — it hosts any headless Linux dedicated server over the REST API. Unity is the first-class SDK, and the guides below cover the most common setups.

<CardGroup>
  <Card title="Mirror" icon="network" href="/quickstart/mirror">
    High-level networking library with clean API and battle-tested architecture
  </Card>

  <Card title="Mirror WebGL" icon="globe" href="/quickstart/mirror-webgl">
    Deploy Mirror games for web browsers with secure WebSocket connections
  </Card>

  <Card title="Fish-Net" icon="fish" href="/quickstart/fishnet">
    High-performance networking with prediction and lag compensation
  </Card>

  <Card title="Fish-Net WebGL" icon="globe" href="/quickstart/fishnet-webgl">
    Deploy Fish-Net games for web browsers with secure WebSocket connections
  </Card>

  <Card title="Unity Netcode" icon="unity" href="/quickstart/netcode">
    Unity's official Netcode for GameObjects (NGO)
  </Card>

  <Card title="Godot" icon="gamepad-2" href="/quickstart/godot">
    Deploy a Godot dedicated server using the REST API
  </Card>

  <Card title="Generic Setup" icon="server" href="#generic-setup">
    For other engines, frameworks, or custom networking solutions
  </Card>
</CardGroup>

<Info>
  **Not sure which framework to choose?**

  * **Mirror**: Great for beginners, large community, stable and mature
  * **Fish-Net**: Best performance, advanced features, actively developed
  * **Unity Netcode**: Official Unity support, good integration with Unity services
</Info>

## Generic Setup

If you're using a different framework or custom networking solution, follow these general steps.

<Info>
  **Not using Unity?** The Unity plugin and the Unity prerequisites below only apply to Unity projects. For any other engine (Godot, Unreal, custom C++/Go/Node servers, etc.), skip the Unity tooling and use **Option 2: Manual Upload** together with the [REST API](/fundamentals/api) — PlayFlow runs any headless Linux dedicated server. The [Godot quickstart](/quickstart/godot) is a worked example.
</Info>

<Warning>
  **Prerequisites (Unity)**

  If you're building with Unity, make sure you have completed the following setup steps first:

  <CardGroup>
    <Card title="Installation Guide" icon="download" href="/guides/installation">
      Install the PlayFlow SDK into your Unity project.
    </Card>

    <Card title="Unity Modules Setup" icon="box" href="/guides/unity-modules">
      Install the required Linux modules for dedicated server builds.
    </Card>
  </CardGroup>
</Warning>

### 1. Unity Project Setup

Before uploading your server, ensure your Unity project is correctly configured.

#### Configure Your Networking

Your game needs a networking transport. Make sure you have one set up. Take note of the **Port** you are using (e.g., `7777`). You will need this later.

#### Ensure Server Auto-Start

Your dedicated server build must start the server automatically when it launches. Most networking libraries have a setting for this, often called "Start on Headless" or similar. Ensure this is enabled so your server doesn't just launch and sit idle.

### 2. PlayFlow Account & Project Setup

<Steps>
  <Step title="Create your PlayFlow Account">
    First, you'll need an account.

    1. Visit [app.playflowcloud.com](https://app.playflowcloud.com).
    2. Sign up with your email or connect with your GitHub/Google account.
  </Step>

  <Step title="Set up your Organization">
    Organizations help you manage your game projects and teams. You'll be prompted to create one after signing up. Give it a name (e.g., your studio name).
  </Step>

  <Step title="Create your First Project">
    Projects in PlayFlow represent individual games.

    1. From your organization dashboard, click **Create Project**.
    2. Give your project a name and click **Create**.
  </Step>
</Steps>

### 3. Upload Your Game Server

You can upload your game server build either directly from the Unity Editor using the PlayFlow plugin (recommended) or manually through the dashboard.

<Tabs>
  <Tab title="Option 1: Upload via Unity Plugin">
    This is the easiest method for Unity developers.

    1. In your PlayFlow project dashboard, go to **API Keys** and copy your **PlayFlow API Key**.
    2. In the Unity Editor, open the PlayFlow window (**PlayFlow → PlayFlow Cloud**).
    3. Paste your API key into the token box.
    4. Select your game server scene from the list.
    5. Click **Upload Server**.

    The plugin will automatically build a headless Linux server and upload it directly to PlayFlow.
  </Tab>

  <Tab title="Option 2: Manual Upload">
    This method works for any game engine.

    1. Build a **headless Linux server** from your game project.
    2. Create a `.zip` file containing your server executable and all its dependencies.
       * PlayFlow defaults to running `Server.x86_64`. If your executable has a different name (e.g. `GameServer.x86_64`), pass `executable_path` when creating the build — see the [API guide](/fundamentals/api#upload-a-build).
    3. In your PlayFlow project dashboard, navigate to the **Builds** tab and click **Upload Build**.
    4. Upload your `.zip` file.
  </Tab>
</Tabs>

### 4. Configure and Deploy

<Steps>
  <Step title="Configure Network Ports">
    For clients to connect, you must tell PlayFlow which port to open.

    1. Go to the **Configuration** tab in your project.
    2. Under **Network Configuration**, add a new port.
    3. Set the **Port Number** to match the one your networking transport uses (e.g., `7777`).
    4. Set the **Protocol** (usually UDP for games).
    5. Save your settings.
  </Step>

  <Step title="Deploy Your Server">
    Now you're ready to launch your server.

    1. Navigate to the **Servers** tab.
    2. Click **Create Server**.
    3. Select the build you just uploaded.
    4. Choose a region and an instance type.
    5. Click **Launch Server**.
  </Step>

  <Step title="Connect to Your Server">
    Once the server status changes to "Running", it's live.

    1. Click **Details** on your running server.
    2. In the **Network** section, read the public **host** and **port** for each mapping.
    3. Use that host and port in your game client to connect.

    <Warning>
      Always read the connection details from the server's response — never hardcode them. Each entry in the response's `network_ports[]` array gives you the `host` and the **`external_port`** to connect to. The external port is allocated by PlayFlow's proxy and is **different from the internal port** your server listens on (it is not `7777`). TCP ports return a hostname (for example `relay.computeflow.cloud`) while UDP ports return a proxy IP address, so treat the host as a host string, not always a raw IP.
    </Warning>
  </Step>
</Steps>

## Next Steps

Congratulations! Your first server is running. Now you can explore more of PlayFlow's features.

<CardGroup>
  <Card title="Game Servers Overview" icon="server" href="/unity/overview">
    Learn more about how dedicated servers work on PlayFlow.
  </Card>

  <Card title="Game Servers API" icon="code" href="/unity/game-servers">
    Learn to manage servers programmatically from your game.
  </Card>

  <Card title="Lobby System" icon="users" href="/unity/lobby-overview">
    Learn how to create lobbies and match players together.
  </Card>
</CardGroup>


# Quick Start - Mirror
Source: https://docs.playflowcloud.com/quickstart/mirror

Step-by-step tutorial for getting up and running with Mirror on PlayFlow Cloud

# Getting Started with Mirror on PlayFlow

This guide assumes you have some or all of your game already written using Mirror and are now ready to use PlayFlow to implement a dedicated server. You can also use PlayFlow throughout the development process as its one-click deployment makes it easy to setup a temporary server for testing.

<Info>
  **Mirror** is a high-level networking library for Unity that makes multiplayer game development easy with its clean API and battle-tested architecture.
</Info>

## Prerequisites

Before you start, make sure you have:

* A Unity project using **Mirror** (or one of Mirror's example scenes, such as **Tanks** or **Pong**)
* **Linux Build Support** modules installed for your Unity version (via Unity Hub) so you can build headless servers
* A free [PlayFlow Cloud](https://app.playflowcloud.com/) account

## Before We Begin

<Steps>
  <Step title="Starting Project">
    If you don't have a project already setup but want to follow this tutorial, you can use one of Mirror's included examples like **Tanks** or **Pong**.

    <Info>
      Mirror comes with several ready-to-use examples. The **Tanks** and **Pong** examples are great starting points for testing multiplayer functionality.
    </Info>
  </Step>

  <Step title="Install the PlayFlow SDK">
    Now that we're ready to start, let's install PlayFlow Cloud. You can directly import it with the following git URL:

    ```
    https://github.com/PlayFlowCloud/PlayFlow-Multiplayer-Unity-SDK.git
    ```

    Simply add this through the Unity Package Manager and you'll be ready to continue!

    <Info>
      If you need more detailed instructions for this step, check out the [Installation Guide](/guides/installation).
    </Info>
  </Step>

  <Step title="Add the Necessary Unity Modules">
    Ensure your Unity installation has the correct modules for building a server. Install the **Linux Build Support** modules for your Unity version in the Unity Hub.

    <Info>
      Exact details on the required modules depending on your Unity version can be found in the [Unity Modules Setup](/guides/unity-modules) guide.
    </Info>
  </Step>

  <Step title="Configure Network Manager">
    Select the NetworkManager in your project. Make sure **Auto Start Server Build** is checked - this will automatically start the server in headless builds.

    <img alt="Mirror NetworkManager Settings" />
  </Step>

  <Step title="Configure Transport">
    Mirror typically comes with **KCP Transport** by default, which is a UDP-based transport.

    <img alt="KCP Transport Settings" />

    <Info>
      **Note the port number** (default is **7777**) - you'll need this for PlayFlow configuration.
    </Info>
  </Step>
</Steps>

Once that's all done we can move on to using PlayFlow Cloud!

## Deploying Your Game with PlayFlow

<Info>
  The PlayFlow dashboard is engine-agnostic, so some screenshots below were captured with a different Unity networking library. The buttons, tabs, and flow are identical for Mirror.
</Info>

<Steps>
  <Step title="Create Your PlayFlow Account">
    Go to the [PlayFlow Cloud website](https://app.playflowcloud.com/) and sign-up using your email, or log in with your GitHub or Google account. If asked, confirm your email address to complete the setup.
  </Step>

  <Step title="Create an Organization">
    Create an Organization to hold your projects (and your team, on Pro).

    * Enter an organization name
    * Click **Create Organization**

    <Info>
      New organizations start on the **Free** plan. You can upgrade to **Pro** later from the billing page for unlimited active servers, larger compute sizes, and longer server lifetimes.
    </Info>
  </Step>

  <Step title="Create a New Project">
    Click **Create New Project** and enter:

    * **Project Name**: Your game name
    * **Game Engine**: Unity
    * **Game Type**: Choose what fits (or Other)

    Click **Create Project** to proceed.
  </Step>

  <Step title="Explore the Dashboard">
    Your PlayFlow dashboard shows logs, metrics, server details and more.

    <img alt="PlayFlow Dashboard" />
  </Step>

  <Step title="Link the PlayFlow SDK to Your Project">
    Now let's link our Unity Project to the PlayFlow one we've just created.

    1. Open the **Overview** page in the PlayFlow dashboard
    2. Find the **API Keys** section and click the **View API Keys** button
    3. Copy the **PlayFlow API Key** to your clipboard
    4. In Unity Editor, open the PlayFlow window from the Toolbar at **PlayFlow → PlayFlow Cloud**
    5. Inside the Token field, paste the **PlayFlow API Key** you copied

       <img alt="PlayFlow SDK Window" />
  </Step>

  <Step title="Build and Upload the Server">
    You can now customize the other settings in the PlayFlow Cloud window, such as the Development Build or Server Scene.

    When you're happy with those, press the **Upload Server** button to have PlayFlow automatically build and upload a headless Linux server build of your game. This will take a brief moment, and then you will have a log in the editor console saying the build uploaded successfully.

    If needed, you can browse the files of the build and delete it directly from the PlayFlow Dashboard under the Builds tab; pressing the **View Builds** button in the PlayFlow window will open this directly for you.
  </Step>

  <Step title="Setup the PlayFlow Port">
    Now we will setup the port to use in the PlayFlow dashboard. Open up the website and head to the **Configuration** tab and then **Network Ports** section. Click the **Add Your First Port** button and fill in the fields.

    <img alt="Add New Port Configuration" />

    * **Port Name**: `mirror_udp`
    * **Port Number**: `7777` (Mirror's default)
    * **Protocol**: **UDP** (for KCP Transport)
    * **Description (Optional)**: Optional

    Click the **Add Port** button to finish this step.
  </Step>

  <Step title="Create the Server">
    Now we are ready to start our server, head over to the Servers tab and click the **Create Your First Server** button.

    <img alt="Create Server Dialog" />

    A window will pop-up letting you customize the settings for this server. You can change the **Name** to "Mirror Game Server", or choose any name you like as well as customizing the other settings to better suit your needs. Once you are happy, press **Create Server**.

    You should now see the server in the Servers tab and you can see its details or stop it directly from here.

    <img alt="Launching Servers View" />
  </Step>

  <Step title="Connect to the Server">
    Click on the **Details** button to see the details of the server. Look at the **Details → Network** section and copy the Host and External Port.

    <img alt="Server Details" />

    Configure your Mirror client with the PlayFlow server details:

    **In NetworkManager:**

    * Set **Network Address** to the Host from PlayFlow (e.g., `123.45.67.89`)

    **In KCP Transport:**

    * Set **Port** to the External Port from PlayFlow

    <Info>
      **Alternative**: If using NetworkManagerHUD, you can enter these values at runtime in Play Mode instead of setting them in the Inspector.
    </Info>

    <Warning>
      Always read the **Host** and **External Port** from the running server (the dashboard's **Details → Network** section, or the `network_ports[]` array in the server API response). The external port is allocated by PlayFlow's proxy and **will not** match your internal `7777` config, so never hardcode it on the client.
    </Warning>
  </Step>

  <Step title="Test the Game">
    1. Enter Play Mode in Unity or build your client
    2. Click **Client** (not Host or Server)
    3. Your game should connect to the PlayFlow server!

    <Tip>
      **Debugging Tips:**

      * Check the PlayFlow dashboard logs to see server console output
      * Ensure your firewall isn't blocking the connection
      * Verify the transport and port settings match between client and server
    </Tip>
  </Step>
</Steps>

## Take the Next Steps!

Well done! You've now learned how to setup and deploy your Mirror server using PlayFlow.

## Resources

* **PlayFlow Documentation**: [docs.playflowcloud.com](https://docs.playflowcloud.com/)
* **PlayFlow Discord**: [discord.gg/P5w45Vx5Q8](https://discord.gg/P5w45Vx5Q8)
* **Mirror Documentation**: [mirror-networking.gitbook.io](https://mirror-networking.gitbook.io/docs/)
* **Mirror Discord**: [discord.gg/mirror](https://discord.gg/mirror)

## Next Steps

<CardGroup>
  <Card title="Lobby System" icon="users" href="/unity/lobby-overview">
    Add lobbies to your Mirror game
  </Card>

  <Card title="Matchmaking" icon="shuffle" href="/unity/matchmaking">
    Implement matchmaking for competitive play
  </Card>

  <Card title="Programmatic Access" icon="code" href="/unity/programmatic-access">
    Manage servers via API
  </Card>
</CardGroup>

## Common Issues

<AccordionGroup>
  <Accordion title="Server not starting automatically">
    Ensure your auto-start script is attached to a GameObject in your scene and check for `UNITY_SERVER` or `UNITY_HEADLESS` preprocessor directives.
  </Accordion>

  <Accordion title="Clients can't connect">
    * Verify the port is correctly configured in PlayFlow (7777 for default Mirror)
    * Check that your transport matches between client and server
    * For KCP, ensure UDP protocol is selected in PlayFlow
    * Ensure firewall rules aren't blocking connections
  </Accordion>

  <Accordion title="NetworkManager is null">
    Make sure NetworkManager.singleton is set. This usually means the NetworkManager component needs to be in your scene before trying to access it.
  </Accordion>
</AccordionGroup>


# Quick Start - Mirror WebGL
Source: https://docs.playflowcloud.com/quickstart/mirror-webgl

Simple tutorial showing how easy PlayFlow makes it to host a server for your Mirror WebGL game

# Easy WebGL Hosting with PlayFlow

## How PlayFlow Makes WebGL Hosting Easy

For seamless WebGL gaming experiences in web browsers, secure WebSocket connections are crucial, but configuring them can be complex. Often, developers end up managing certificates and networking issues, which can be time-consuming. **With PlayFlow**, however, you only need to enable a simple option to handle these concerns effortlessly.

<Info>
  **Mirror** with SimpleWebTransport provides robust WebSocket support for WebGL builds, making it easy to deploy multiplayer games to web browsers.
</Info>

## Before We Begin

<Warning>
  This tutorial assumes you've already completed the [standard Mirror setup](/quickstart/mirror). In the following steps, we'll convert your project to support WebGL.
</Warning>

## Setup Steps

<Steps>
  <Step title="Install SimpleWebTransport">
    Mirror comes with SimpleWebTransport included by default. If you don't have it:

    1. Ensure you have the latest version of Mirror
    2. SimpleWebTransport should be in your project automatically

    <Info>
      SimpleWebTransport is Mirror's official WebSocket transport for WebGL builds.
    </Info>
  </Step>

  <Step title="Add SimpleWebTransport to NetworkManager">
    1. Select your NetworkManager in the scene
    2. Add the **SimpleWebTransport** component to it
    3. Remove or disable KCP Transport (not needed for WebGL)

       <img alt="SimpleWebTransport Settings" />
  </Step>

  <Step title="Configure SimpleWebTransport">
    In the SimpleWebTransport component:

    **Client settings:**

    1. Enable **"Client Use Wss"** ✓ (WebSocket Secure)
    2. Set **Client Port Option** to **"Use Custom Port"**
    3. Set **Client Port** to match your PlayFlow external port (you'll get this later)

    **Server settings:**

    * Keep **Port** as `7778` (default)

    <Warning>
      The "Client Use Wss" option is critical for secure WebGL connections through PlayFlow.
    </Warning>
  </Step>

  <Step title="Configure NetworkManager">
    Ensure **Auto Start Server Build** is checked in your NetworkManager - this will automatically start the server in headless builds.
  </Step>

  <Step title="Build Your PlayFlow Server">
    Open the PlayFlow Cloud window from Unity toolbar (**PlayFlow → PlayFlow Cloud**).

    Click **Upload Server** to build and upload your Unity server.

    <Info>
      PlayFlow automatically builds a headless Linux server optimized for dedicated hosting.
    </Info>
  </Step>

  <Step title="Configure PlayFlow Port Protocol">
    In the [PlayFlow dashboard](https://app.playflowcloud.com/):

    1. Navigate to **Configuration** tab
    2. Add a new port or edit existing
    3. **Port Name**: `mirror_webgl`
    4. **Port Number**: `7778` (SimpleWebTransport default)
    5. **Protocol**: **TCP**
    6. **Enable TLS** ✓ (Critical for WebGL)
    7. Save configuration

    <Info>
      **Why TCP + TLS?** WebGL requires secure WebSocket connections. PlayFlow handles the SSL certificates automatically when you enable TLS.
    </Info>
  </Step>

  <Step title="Start a PlayFlow Server">
    1. Go to the **Servers** tab in PlayFlow
    2. Click **Create Server**
    3. Select your uploaded build
    4. Choose your configuration
    5. Launch the server
  </Step>

  <Step title="Configure Your Client">
    1. Click on your server instance's **Details**
    2. Look for the **TLS Connection** information
    3. In Unity, configure your client:

    **In NetworkManager:**

    * Set **Network Address** to the exact TLS hostname shown on the server detail page (PlayFlow serves TCP/TLS traffic through a relay host such as `relay.computeflow.cloud`)

    **In SimpleWebTransport:**

    * Set **Client Port** to the External Port from PlayFlow
    * Ensure **Client Use Wss** is checked ✓
    * Ensure **Client Port Option** is set to **Use Custom Port**

    <Info>
      **Important:** For TLS/WSS connections, read the host and external port straight from the server's details (these come from the `network_ports[]` array in the server API response). Use the hostname shown there, not an IP address, and never hardcode a port — the external port is proxy-allocated and differs from the port your server listens on.
    </Info>
  </Step>

  <Step title="Build Your WebGL Client">
    1. In Unity, switch to **WebGL** platform in Build Settings
    2. Build your game
    3. Zip the built files
    4. Upload to your chosen hosting platform (e.g., itch.io, GitHub Pages, Netlify)

    <Info>
      PlayFlow hosts your game **servers**, not your WebGL client build. Host the client on any static web host — popular options include itch.io, GitHub Pages, and Netlify.
    </Info>
  </Step>
</Steps>

## Success!

Just like that, you've created a server and have your clients in the web browser securely connecting to it!

## Troubleshooting

<AccordionGroup>
  <Accordion title="Connection Failed">
    * Verify TLS is enabled in PlayFlow port settings
    * Check that "Client Use Wss" is enabled in SimpleWebTransport
    * Ensure "Client Port Option" is set to "Use Custom Port"
    * Verify client is using the TLS hostname (not IP address)
    * Confirm the correct external port is configured
  </Accordion>

  <Accordion title="Multiple Transports Issue">
    If you have both KCP and SimpleWebTransport on your NetworkManager, make sure only SimpleWebTransport is active for WebGL builds. You can use platform-specific code to switch transports.
  </Accordion>

  <Accordion title="SSL/TLS Configuration">
    Don't modify the SSL settings in SimpleWebTransport - PlayFlow handles all certificates automatically when TLS is enabled in the port configuration.
  </Accordion>

  <Accordion title="Port Mismatch">
    Remember that the server listens on the port you set in SimpleWebTransport (default 7778), but clients connect through PlayFlow's external port. Always use the external port for client connections.
  </Accordion>
</AccordionGroup>

## Resources

* **PlayFlow Documentation**: [docs.playflowcloud.com](https://docs.playflowcloud.com/)
* **PlayFlow Discord**: [discord.gg/P5w45Vx5Q8](https://discord.gg/P5w45Vx5Q8)
* **Mirror Documentation**: [mirror-networking.gitbook.io](https://mirror-networking.gitbook.io/docs/)
* **Mirror Discord**: [discord.gg/mirror](https://discord.gg/mirror)

## Related Guides

<CardGroup>
  <Card title="WebGL Deployments" icon="browser" href="/guides/webgl-deployments">
    Advanced WebGL deployment strategies
  </Card>

  <Card title="Mirror Standard" icon="network" href="/quickstart/mirror">
    Standard Mirror setup for desktop/mobile
  </Card>

  <Card title="Lobby System" icon="users" href="/unity/lobby-overview">
    Add lobbies to your WebGL game
  </Card>
</CardGroup>


# Quick Start - Unity Netcode
Source: https://docs.playflowcloud.com/quickstart/netcode

Deploy your Unity Netcode for GameObjects server on PlayFlow Cloud

# Deploy Your Unity Netcode Server

This guide assumes you already have a Unity Netcode for GameObjects project and are ready to deploy it on PlayFlow Cloud.

<Info>
  **Unity Netcode for GameObjects** is Unity's official high-level networking library, providing a game-centric networking experience.
</Info>

## Video Tutorial

<iframe title="Unity Netcode on PlayFlow Cloud Tutorial" />

<Tip>
  Watch the video above for a complete walkthrough of deploying Unity Netcode for GameObjects on PlayFlow Cloud, or follow the written guide below.
</Tip>

## Before We Begin

<Steps>
  <Step title="Prerequisites">
    Ensure you have:

    * An existing Unity Netcode for GameObjects project
    * Unity Netcode for GameObjects package installed
    * NetworkManager configured in your scene
  </Step>

  <Step title="Install PlayFlow SDK">
    Install the PlayFlow SDK via Unity Package Manager:

    ```
    https://github.com/PlayFlowCloud/PlayFlow-Multiplayer-Unity-SDK.git
    ```

    <Info>
      For detailed instructions, see the [Installation Guide](/guides/installation).
    </Info>
  </Step>

  <Step title="Install Linux Modules">
    Install **Linux Build Support** modules in Unity Hub for server builds.

    <Info>
      See [Unity Modules Setup](/guides/unity-modules) for your Unity version.
    </Info>
  </Step>
</Steps>

## Configure Netcode for PlayFlow

<Steps>
  <Step title="Configure NetworkManager">
    Ensure your NetworkManager has:

    * Unity Transport component attached
    * Default port set (usually `7777`)
    * Network Prefabs configured
  </Step>

  <Step title="Add Server Auto-Start">
    Create a script to auto-start the server in headless builds:

    ```csharp theme={null}
    using Unity.Netcode;
    using UnityEngine;

    public class PlayFlowNetcodeStarter : MonoBehaviour
    {
        void Start()
        {
            #if UNITY_SERVER || UNITY_HEADLESS
            NetworkManager.Singleton.StartServer();
            Debug.Log("Unity Netcode server started on PlayFlow");
            #endif
        }
    }
    ```

    Attach this script to a GameObject in your scene.
  </Step>

  <Step title="Configure Transport">
    For the Unity Transport component on NetworkManager:

    * Keep the default port (`7777`)
    * Server will automatically bind to `0.0.0.0` in headless builds

    <Info>
      Unity Transport handles most server configuration automatically when running in headless mode.
    </Info>
  </Step>
</Steps>

## Deploy to PlayFlow

<Steps>
  <Step title="Create PlayFlow Account">
    Go to [PlayFlow Cloud](https://app.playflowcloud.com/) and sign up or log in.
  </Step>

  <Step title="Create Organization & Project">
    1. Create an Organization (new orgs start on the **Free** plan; upgrade to **Pro** anytime)
    2. Create a new project
    3. Select **Unity** as the game engine
  </Step>

  <Step title="Link PlayFlow SDK">
    1. In PlayFlow dashboard, go to **API Keys**
    2. Copy your **PlayFlow API Key**
    3. In Unity, open **PlayFlow → PlayFlow Cloud**
    4. Paste the API key
  </Step>

  <Step title="Upload Your Server">
    In the PlayFlow window:

    1. Select your game scene
    2. Click **Upload Server**

    PlayFlow automatically builds and uploads a headless Linux server.

    <Info>
      The build process takes a few minutes. You'll see a success message when complete.
    </Info>
  </Step>
</Steps>

## Configure PlayFlow

<Steps>
  <Step title="Configure Network Port">
    In PlayFlow dashboard:

    1. Go to **Configuration** → **Network Ports**
    2. Click **Add Port**
    3. Enter:
       * **Port Name**: `netcode_game`
       * **Port Number**: `7777`
       * **Protocol**: **UDP**
    4. Save configuration
  </Step>

  <Step title="Create Server">
    1. Go to **Servers** tab
    2. Click **Create Server**
    3. Select your uploaded build
    4. Choose a **region** (required) and a compute size
    5. Click **Create Server**

    Wait for status to change to **Running**.

    <Info>
      On the **Free** plan, servers run on the `small` compute size with a 1-hour maximum lifetime, and you can have 1 active server at a time. Choosing a different compute size and longer TTLs (up to 24 hours) requires the **Pro** plan.
    </Info>
  </Step>

  <Step title="Connect Your Client">
    1. Click **Details** on your running server
    2. Copy the **Host** and **External Port** for your UDP port (these come from the `network_ports[]` array in the server API response — read them at runtime, never hardcode)
    3. In your Unity client:

    ```csharp theme={null}
    using Unity.Netcode;
    using Unity.Netcode.Transports.UTP;

    void ConnectToPlayFlowServer(string host, ushort externalPort)
    {
        var transport = NetworkManager.Singleton.GetComponent<UnityTransport>();
        transport.SetConnectionData(host, externalPort);
        NetworkManager.Singleton.StartClient();
    }
    ```

    Pass the **Host** and **External Port** from PlayFlow into this method.

    <Warning>
      Do **not** connect to port `7777`. `7777` is the internal port your server binds to inside the container. PlayFlow maps UDP through a proxy and allocates a different **external port** for clients. Always read the host and external port from the server's `network_ports[]` response (or the dashboard **Details** panel) at runtime — they change per server.
    </Warning>
  </Step>
</Steps>

## Next Steps

<CardGroup>
  <Card title="Lobby System" icon="users" href="/unity/lobby-overview">
    Integrate Unity Lobby Service with PlayFlow
  </Card>

  <Card title="Matchmaking" icon="shuffle" href="/unity/matchmaking">
    Add matchmaking to your Netcode game
  </Card>

  <Card title="Server Management" icon="server" href="/unity/game-servers">
    Advanced server management techniques
  </Card>
</CardGroup>

## Success!

Your Unity Netcode server is now running on PlayFlow Cloud! Clients can connect using the server's public IP and port.

## Common Issues

<AccordionGroup>
  <Accordion title="NetworkManager is null">
    Ensure NetworkManager exists in your scene and that you're not trying to access it too early in the Start() method.
  </Accordion>

  <Accordion title="Clients stuck on connecting">
    * Verify UDP port 7777 is configured in PlayFlow
    * Check that server is binding to 0.0.0.0 not localhost
    * Ensure firewall rules allow UDP traffic
  </Accordion>

  <Accordion title="High latency or packet loss">
    * Adjust NetworkTickRate based on your needs
    * Configure Unity Transport reliability settings
    * Use PlayFlow's server monitoring to identify issues
  </Accordion>
</AccordionGroup>


# Server Lifecycle
Source: https://docs.playflowcloud.com/unity/game-servers

Understand how your dedicated server works on PlayFlow, from configuration to automatic shutdown.

This guide covers what happens inside your game server build when it runs on the PlayFlow platform.

## Reading Session Config

Every time PlayFlow starts your server, it makes the current session's details available so your server can configure itself dynamically. There are two ways to read them.

### Option 1: `playflow.json` (file)

PlayFlow writes a `playflow.json` file in the root directory, right next to your server executable. This file is written for backwards compatibility with existing SDKs, and it remains fully supported.

**Example `playflow.json`:**

```json theme={null}
{
  "instance_id": "i-12345abcdef",
  "region": "us-east",
  "match_id": "match-abc123",
  "version_tag": "my-build",
  "startup_args": "-mode competitive",
  "custom_data": {
    "map_name": "dust2",
    "game_mode": "competitive"
  }
}
```

<Warning>
  `playflow.json` also contains the server's `api-key` (a `pf_` key with full access). Never ship this file in a client-facing or WebGL build — treat it as server-side only.
</Warning>

Your server should read this file on startup. For example, you can use the `custom_data` to tell the server which map to load or what game mode to run.

### Option 2: `GET :9090/v1/config` (HTTP)

The PlayFlow agent also serves a live config endpoint at `http://localhost:9090/v1/config` from inside the machine. Newer integrations can query it instead of reading the file. It returns the same session fields plus the current `ttl` and the allocated `ports` array, so it is the best source for reading your server's port mappings at runtime.

<Tabs>
  <Tab title="Unity">
    The SDK provides a helper class to make this easy. Simply call `PlayFlowServerConfig.LoadConfig()` to get the data.

    ```csharp theme={null}
    using PlayFlow;
    using UnityEngine;

    public class MyGameServer : MonoBehaviour
    {
        void Start()
        {
            var config = PlayFlowServerConfig.LoadConfig();
            if (config != null)
            {
                Debug.Log($"Server instance ID is: {config.instance_id}");

                if (config.custom_data.TryGetValue("map_name", out object map))
                {
                    Debug.Log($"Loading map: {map}");
                    // Your code to load the map...
                }
            }
        }
    }
    ```
  </Tab>

  <Tab title="Other Engines">
    For other engines, you'll need to read and parse the `playflow.json` file from the server's root directory using standard file I/O operations.
  </Tab>
</Tabs>

## Automatic Server Shutdown

Servers stop automatically in two ways: when your process exits, and when a time-to-live (TTL) expires. Both are always enforced.

### Shutdown on process exit

For match-based games, you want the server to shut down after the match is over to save costs.

**When your server process exits, PlayFlow detects it and automatically stops the instance.**

In Unity, this means all you need to do is call `Application.Quit()` at the end of a match. PlayFlow will handle the rest, ensuring you only pay for the time your server was actually running.

<Info>
  In the default multi-container model the agent detects exit by watching your game ports go down, which takes up to about 45 seconds after the process exits. A brief lingering `running` state after `Application.Quit()` is expected.
</Info>

### Shutdown on TTL

Every server can also carry a TTL — a maximum lifetime after which PlayFlow stops it automatically, even if the process is still running. You set `ttl` (in seconds) when you start a server; the accepted range is `60`–`86400` (24 hours). Leaving it unset means no TTL-based auto-shutdown.

<Warning>
  On the **Free** plan, TTL is force-capped at `3600` seconds (1 hour) regardless of the value you request. See [Plan Instance Types](/fundamentals/plan-instance-types) for per-plan limits.
</Warning>

## Next Steps

Now that you understand how the server behaves, learn how to control it from your game client or backend.

<Card title="Programmatic Access" icon="code" href="/unity/programmatic-access">
  Start, stop, and list servers using the PlayFlow API and Unity SDK.
</Card>


# Unity SDK Overview
Source: https://docs.playflowcloud.com/unity/index

Integrate PlayFlow multiplayer services directly into your Unity projects with our native SDK.

The PlayFlow Unity SDK provides a powerful and convenient way to manage your game servers, lobbies, and matchmaking directly within the Unity Editor and your game's C# scripts.

<Info>
  **Prerequisites**

  * A PlayFlow account with a project (new organizations start on the **Free** plan).
  * A project **API key**. You can create both server keys (`pf_...`) and client keys (`pfclient_...`) from the **API Keys** section of your project.
  * Unity 2021.3 LTS or newer.
</Info>

## Key Features

* **In-Editor Management**: A user-friendly editor window to manage your PlayFlow account, server builds, and deployments without leaving Unity.
* **C# API Clients**: High-level C# APIs for interacting with PlayFlow's services, including Game Servers, Lobbies, and Matchmaking.
* **Simplified Workflow**: Designed to streamline the development process for multiplayer games, from prototyping to production.
* **Example Scenes**: Comes with clear examples to help you get started quickly.

## Installation

To get started with the PlayFlow Unity SDK, please follow our complete installation guide.

<Card title="Installation Guide" icon="download" href="/guides/installation">
  Follow the steps to install the SDK using the Unity Package Manager.
</Card>

## Initial Setup

Once imported, the SDK needs to be configured with your PlayFlow API Key.

1. Find the `PlayFlowLobbyManagerV2` component in your scene, or add it to a new GameObject.
2. In the Inspector for `PlayFlowLobbyManagerV2`, enter your **API Key**. You can find this in the **API Keys** section of your PlayFlow project.
3. That's it! The manager will now be able to authenticate with PlayFlow services.

<Warning>
  Because the SDK ships inside your game client, use a **client key** (`pfclient_...`), which is safe to distribute in game builds. Keep **server keys** (`pf_...`) server-side only — they have full access and can delete builds and change project settings.
</Warning>

<CardGroup>
  <Card title="Game Servers" icon="server" href="/unity/game-servers">
    Learn how to programmatically start, stop, and manage your dedicated game server instances.
  </Card>

  <Card title="Lobbies" icon="users" href="/unity/lobbies">
    Create and manage lobbies for players to congregate before a match.
  </Card>

  <Card title="Matchmaking" icon="swords" href="/unity/matchmaking">
    Use skill-based matchmaking to find suitable opponents for your players.
  </Card>
</CardGroup>


# Lobby Quick Start
Source: https://docs.playflowcloud.com/unity/lobbies

A practical guide to creating and managing game lobbies with code examples.

This guide provides a step-by-step walkthrough of how to use the PlayFlow Lobby SDK. We'll cover setting up, creating, managing, and joining lobbies with practical code examples.

For a high-level overview of the concepts, please see the [Beginner's Guide to Lobbies](lobby-overview).

## Prerequisites

Before you write any lobby code, make sure you have:

* **The PlayFlow Unity SDK installed** in your project.
* **A PlayFlow project** created in the [dashboard](https://app.playflowcloud.com), with your API key copied from the project's settings. Use a client key (prefix `pfclient_`) in game builds you ship to players — it is safe to embed. Keep server keys (prefix `pf_`) server-side only.
* **The SDK configured with that API key** so it can reach the lobby API.

The player ID you pass to `Initialize` becomes the identity the lobby API trusts for that client. If you have configured a player-auth provider on your project, the SDK sends a verified player token instead and the player ID is derived from it.

## Initial Setup (5 Minutes)

First, you need to get the Lobby Manager set up in your game.

### Step 1: Configure in Dashboard

Before you write any code, set up a lobby configuration in your PlayFlow project dashboard.

1. Go to your project's **Configuration** → **Lobbies** tab.
2. Create a new lobby configuration (e.g., "Default" or "Ranked").
3. Select the game server build and instance type this lobby will use.
4. Save your configuration.

### Step 2: Initialize the SDK

To use the lobby system, you must initialize it with a unique ID for the current player.

<Tabs>
  <Tab title="Unity">
    Add the `PlayFlowLobbyManagerV2` component to a GameObject in your scene. Then, in a script, call the `Initialize` method.

    ```csharp theme={null}
    using PlayFlow;
    using UnityEngine;

    public class GameInitializer : MonoBehaviour
    {
        void Start()
        {
            // Use a unique ID for each player (e.g., from a login system or device ID)
            string myPlayerId = SystemInfo.deviceUniqueIdentifier;
            
            // Initialize the manager
            PlayFlowLobbyManagerV2.Instance.Initialize(myPlayerId, () => {
                Debug.Log("PlayFlow SDK is ready to use!");
            });
        }
    }
    ```
  </Tab>

  <Tab title="Unreal Engine">
    Coming soon...
  </Tab>

  <Tab title="Godot">
    Coming soon...
  </Tab>
</Tabs>

## Basic Lobby Actions

Once the SDK is initialized, you can start performing lobby actions.

### Creating a Lobby

To create a new lobby, specify a name, the max number of players, and whether it's private.

<Tabs>
  <Tab title="Unity">
    ```csharp theme={null}
    // Create a public lobby for 4 players
    PlayFlowLobbyManagerV2.Instance.CreateLobby(
        name: "My Awesome Game Room",
        maxPlayers: 4,
        isPrivate: false,
        onSuccess: (lobby) => {
            Debug.Log($"Created public lobby! ID: {lobby.id}");
        },
        onError: (error) => Debug.LogError(error)
    );

    // Create a private lobby with an invite code
    PlayFlowLobbyManagerV2.Instance.CreateLobby(
        name: "Friends Only",
        maxPlayers: 4,
        isPrivate: true,
        onSuccess: (lobby) => {
            Debug.Log($"Created private lobby! Share this code: {lobby.code}");
        },
        onError: (error) => Debug.LogError(error)
    );
    ```
  </Tab>

  <Tab title="Unreal Engine">
    Coming soon...
  </Tab>

  <Tab title="Godot">
    Coming soon...
  </Tab>
</Tabs>

### Joining a Lobby

Every lobby gets an invite code when it is created, public and private alike. Players can join a public lobby by its ID or by its code. Private lobbies can only be joined by code — a direct join by ID is rejected.

<Tabs>
  <Tab title="Unity">
    ```csharp theme={null}
    // Join by lobby ID
    string lobbyIdToJoin = "... a lobby ID from the server list ...";
    PlayFlowLobbyManagerV2.Instance.JoinLobby(lobbyIdToJoin,
        onSuccess: (lobby) => Debug.Log("Joined lobby!"),
        onError: (error) => Debug.LogError(error)
    );

    // Join by invite code (works for both public and private lobbies)
    string inviteCode = "... a code shared by a friend ...";
    PlayFlowLobbyManagerV2.Instance.JoinLobbyByCode(inviteCode,
        onSuccess: (lobby) => Debug.Log("Joined lobby via code!"),
        onError: (error) => Debug.LogError(error)
    );
    ```
  </Tab>

  <Tab title="Unreal Engine">
    Coming soon...
  </Tab>

  <Tab title="Godot">
    Coming soon...
  </Tab>
</Tabs>

### Listing Public Lobbies

To build a server browser, you can fetch a list of all available public lobbies.

<Tabs>
  <Tab title="Unity">
    ```csharp theme={null}
    PlayFlowLobbyManagerV2.Instance.GetAvailableLobbies(
        onSuccess: (lobbies) => {
            Debug.Log($"Found {lobbies.Count} lobbies:");
            foreach (var lobby in lobbies)
            {
                Debug.Log($"  - {lobby.name} ({lobby.currentPlayers}/{lobby.maxPlayers})");
            }
            // Now you can display this list in your UI
        },
        onError: (error) => Debug.LogError(error)
    );
    ```
  </Tab>

  <Tab title="Unreal Engine">
    Coming soon...
  </Tab>

  <Tab title="Godot">
    Coming soon...
  </Tab>
</Tabs>

## Managing the Match

### Starting a Match

When everyone is ready, the host can start the match. This will begin the process of launching a dedicated server.

<Tabs>
  <Tab title="Unity">
    ```csharp theme={null}
    var manager = PlayFlowLobbyManagerV2.Instance;
    if (manager.IsHost)
    {
        manager.StartMatch(
            onSuccess: (lobby) => Debug.Log("Match starting! Waiting for server..."),
            onError: (error) => Debug.LogError(error)
        );
    }
    ```
  </Tab>

  <Tab title="Unreal Engine">
    Coming soon...
  </Tab>

  <Tab title="Godot">
    Coming soon...
  </Tab>
</Tabs>

### Connecting to the Server

After a match is started, all players in the lobby need to listen for the `OnMatchRunning` event. This event provides the IP address and port needed to connect to the game server.

<Tabs>
  <Tab title="Unity">
    ```csharp theme={null}
    void Start()
    {
        // Listen for the server ready event
        PlayFlowLobbyManagerV2.Instance.Events.OnMatchRunning.AddListener(OnServerReady);
    }

    void OnServerReady(ConnectionInfo connectionInfo)
    {
        Debug.Log($"Server is ready! Connecting to {connectionInfo.Ip}:{connectionInfo.Port}");
        
        // Use your networking library (Mirror, Netcode, FishNet, etc.) to connect here
        MyGameNetworkManager.Connect(connectionInfo.Ip, connectionInfo.Port);
    }
    ```
  </Tab>

  <Tab title="Unreal Engine">
    Coming soon...
  </Tab>

  <Tab title="Godot">
    Coming soon...
  </Tab>
</Tabs>

## Syncing Player Data

Use `UpdatePlayerState` to sync custom data for the local player, like their ready status or character choice. This data is automatically sent to all other players in the lobby.

<Tabs>
  <Tab title="Unity">
    ```csharp theme={null}
    public void SetReadyStatus(bool isReady)
    {
        var myCustomData = new Dictionary<string, object>
        {
            { "ready", isReady },
            { "character", "Wizard" },
            { "skin", "blue_robe" }
        };
        
        PlayFlowLobbyManagerV2.Instance.UpdatePlayerState(myCustomData);
    }
    ```
  </Tab>

  <Tab title="Unreal Engine">
    Coming soon...
  </Tab>

  <Tab title="Godot">
    Coming soon...
  </Tab>
</Tabs>

To read another player's data, you can access the `lobbyStateRealTime` dictionary from the `CurrentLobby` object.

## Host-Only Actions

Only the host of a lobby can perform sensitive actions:

* **Kicking a Player**: `KickPlayer(playerId)`
* **Updating Lobby Settings**: `UpdateLobby(...)` / `UpdateLobbySettings(...)`

<Info>
  **Host is assigned automatically.** There is no call to hand the host role to a specific player. When the current host leaves, host duty transfers automatically to the next player in the lobby (controlled by the lobby config's `hostLeaveBehavior`).
</Info>

<Info>
  **Player state is self-owned.** Hosts cannot push state onto other players. Each player updates their own state via `UpdatePlayerState()` and everyone reacts via `OnLobbyUpdated`. For team/role assignment, either have players pick their own team or broadcast assignments through `UpdateLobbySettings()` (host-owned) and have each client apply them locally.
</Info>

<Tabs>
  <Tab title="Unity">
    ```csharp theme={null}
    var manager = PlayFlowLobbyManagerV2.Instance;
    if (manager.IsHost)
    {
        // Kick a player
        manager.KickPlayer("... some player id ...");

        // Change the max players
        manager.UpdateLobby(maxPlayers: 8);

        // Broadcast team assignments through lobby settings (host-owned).
        // Each client reads lobby.settings["teamAssignments"] on OnLobbyUpdated.
        var assignments = new Dictionary<string, object>
        {
            { "teamAssignments", new Dictionary<string, string>
                {
                    { "player_1", "blue" }, { "player_2", "red" }
                }
            }
        };
        manager.UpdateLobbySettings(assignments);
    }
    ```
  </Tab>

  <Tab title="Unreal Engine">
    Coming soon...
  </Tab>

  <Tab title="Godot">
    Coming soon...
  </Tab>
</Tabs>

## Next Steps

<CardGroup>
  <Card title="Matchmaking Guide" icon="swords" href="matchmaking">
    Learn how to use the matchmaking system to find opponents automatically.
  </Card>

  <Card title="Lobby Events Reference" icon="radio" href="lobby-events">
    See a full list of all the events you can subscribe to for building a responsive UI.
  </Card>
</CardGroup>


# Lobby Events
Source: https://docs.playflowcloud.com/unity/lobby-events

React to lobby and player state changes by subscribing to events from the PlayFlowLobbyManagerV2.

The `PlayFlowLobbyManagerV2` uses a system of `UnityEvent`s to communicate state changes and important occurrences to your game. By subscribing to these events, you can create a responsive UI and trigger game logic at the right moments.

All events are accessible through the `PlayFlowLobbyManagerV2.Instance.Events` property, which is an instance of `PlayFlowEvents`.

<Info>
  The `V2` in `PlayFlowLobbyManagerV2` is the SDK component version and is unrelated to the REST API version. Lobbies and matchmaking are served exclusively by the v3 engine API (`/api/v3/lobbies`); there is no v2 compatibility layer for them. These `UnityEvent`s are the SDK's abstraction over the server's real-time SSE event stream — you subscribe to C# events instead of parsing the raw stream yourself.
</Info>

## Prerequisites

Before you wire up events, make sure you have:

* A lobby configuration and the `PlayFlowLobbyManagerV2` set up in your scene — see [Lobbies](/unity/lobbies).
* Matchmaking modes (and optional match confirmation) configured if you use the matchmaking events — see [Matchmaking](/unity/matchmaking).

## Subscribing to Events

You subscribe to events using the standard `AddListener` method. It's best practice to do this after the manager has been initialized.

```csharp theme={null}
using PlayFlow;
using UnityEngine;

public class MyLobbyUI : MonoBehaviour
{
    void Start()
    {
        // It's good practice to wait until the manager is ready
        PlayFlowLobbyManagerV2.Instance.Initialize("my-player-id", SubscribeToEvents);
    }

    void SubscribeToEvents()
    {
        var events = PlayFlowLobbyManagerV2.Instance.Events;
    
        // Fired when the local player joins a lobby
        events.OnLobbyJoined.AddListener(OnLobbyJoined);
    
        // Fired when another player joins the lobby
        events.OnPlayerJoined.AddListener(OnPlayerJoined);

        // Fired when a player leaves
        events.OnPlayerLeft.AddListener(OnPlayerLeft);
    
        // Fired when the lobby data is updated
        events.OnLobbyUpdated.AddListener(OnLobbyUpdated);

        // Fired on connection errors
        events.OnError.AddListener(OnError);
    }

    void OnLobbyJoined(Lobby lobby)
    {
        Debug.Log($"Successfully joined lobby: {lobby.name}");
        // Update UI to show lobby screen
    }

    void OnPlayerJoined(PlayerAction action)
    {
        Debug.Log($"Player {action.PlayerId} joined the lobby!");
        // Add player to UI list
    }

    void OnPlayerLeft(PlayerAction action)
    {
        Debug.Log($"Player {action.PlayerId} left the lobby.");
        // Remove player from UI list
    }

    void OnLobbyUpdated(Lobby lobby)
    {
        Debug.Log("Lobby data has been updated.");
        // Refresh the entire lobby UI
    }

    void OnError(string errorMessage)
    {
        Debug.LogError($"A PlayFlow error occurred: {errorMessage}");
        // Show an error popup to the user
    }

    void OnDisable()
    {
        // Don't forget to unsubscribe to prevent memory leaks!
        var events = PlayFlowLobbyManagerV2.Instance.Events;
        if (events != null)
        {
            events.OnLobbyJoined.RemoveListener(OnLobbyJoined);
            events.OnPlayerJoined.RemoveListener(OnPlayerJoined);
            events.OnPlayerLeft.RemoveListener(OnPlayerLeft);
            events.OnLobbyUpdated.RemoveListener(OnLobbyUpdated);
            events.OnError.RemoveListener(OnError);
        }
    }
}
```

## Event Reference

Here is a complete list of events available on `PlayFlowEvents`.

### Lobby Events

<ResponseField name="OnLobbyCreated" type="LobbyEvent">
  Fired when a lobby is successfully created by the local player. The event passes the created `Lobby` object.
  *Argument: `Lobby`*
</ResponseField>

<ResponseField name="OnLobbyJoined" type="LobbyEvent">
  Fired when the local player successfully joins a lobby.
  *Argument: `Lobby`*
</ResponseField>

<ResponseField name="OnLobbyUpdated" type="LobbyEvent">
  Fired whenever the `Lobby` data changes. This can be due to players joining/leaving, player state changes, or host actions.
  *Argument: `Lobby`*
</ResponseField>

<ResponseField name="OnLobbyLeft" type="VoidEvent">
  Fired after the local player successfully leaves a lobby.
  *Argument: `void`*
</ResponseField>

### Match Events

<ResponseField name="OnMatchStarted" type="LobbyEvent">
  Fired for all players in a lobby when the host starts the match (via `StartMatch()` or a completed matchmaking cycle). Status is now `in_game`, but the server is still `launching`.
  *Argument: `Lobby`*
</ResponseField>

<ResponseField name="OnMatchRunning" type="ConnectionInfoEvent">
  Fired when the game server has finished booting and is ready to accept connections. The payload is a quick-access `ConnectionInfo` for the first port. For multi-port games use `lobby.TryGetPort("name", out var port)` instead.
  *Argument: `ConnectionInfo`*
</ResponseField>

<ResponseField name="OnMatchServerDetailsReady" type="PortMappingInfoListEvent">
  Fires alongside `OnMatchRunning` with the **full list of ports** (name, protocol, host, internal/external port, TLS state). Subscribe to this when your game has more than one port (e.g. `game_udp` + `voice_tcp`).
  *Argument: `List<PortMappingInfo>`*
</ResponseField>

<ResponseField name="OnMatchEnded" type="LobbyEvent">
  Fired for all players when a match ends — either the host called `EndMatch()`, or the server stopped on its own (TTL, crash, clean exit). The lobby auto-heals back to `waiting` with the same players and invite code, ready for a rematch.
  *Argument: `Lobby`*
</ResponseField>

### Matchmaking Events

<ResponseField name="OnMatchmakingStarted" type="LobbyEvent">
  Fired when the lobby enters the matchmaking queue (after a successful `FindMatch()` call). Status is now `in_queue`.
  *Argument: `Lobby`*
</ResponseField>

<ResponseField name="OnQueueStats" type="QueueStatsEvent">
  Fired roughly every 10 seconds while the lobby is searching, with live telemetry: total players searching, number of lobbies in queue, and average wait time. Perfect for a "42 players searching · \~12s wait" UI.
  *Argument: `QueueStats`*
</ResponseField>

<ResponseField name="OnMatchFound" type="LobbyEvent">
  Fired when opponents are found and the match is committed. For modes **without** confirmation this fires right before `OnMatchStarted`. For modes **with** confirmation enabled, use `OnMatchAwaitingConfirmation` instead — `OnMatchFound` only fires after every lobby has accepted.
  *Argument: `Lobby`*
</ResponseField>

<ResponseField name="OnMatchAwaitingConfirmation" type="LobbyEvent">
  Only relevant when the matchmaking mode has `matchConfirmation.enabled: true` in the dashboard. Fired when a match proposal is found — show a CS2-style "Accept Match" dialog. The lobby is in `match_found` status. Use `lobby.matchmaking.confirmation.deadline` (ISO 8601 timestamp) for the countdown.
  *Argument: `Lobby`*
</ResponseField>

<ResponseField name="OnMatchConfirmed" type="LobbyEvent">
  Fired after `ConfirmMatch()` succeeds — your lobby has accepted. You're still waiting on other lobbies to confirm. Update your UI to show "Waiting on N other players…".
  *Argument: `Lobby`*
</ResponseField>

<ResponseField name="OnMatchDeclined" type="LobbyEvent">
  Fired when the match proposal is cancelled — either someone called `DeclineMatch()`, or the confirmation window expired. All participating lobbies return to `waiting`. Show a "Match declined — click to re-queue" UI.
  *Argument: `Lobby`*
</ResponseField>

<ResponseField name="OnMatchmakingCancelled" type="LobbyEvent">
  Fired when the host calls `CancelMatchmaking()` and the lobby returns to `waiting` voluntarily.
  *Argument: `Lobby`*
</ResponseField>

<ResponseField name="OnMatchmakingTimeout" type="LobbyEvent">
  Fired when the matchmaking queue times out without finding a match. The lobby returns to `waiting`.
  *Argument: `Lobby`*
</ResponseField>

### Player Events

<ResponseField name="OnPlayerJoined" type="PlayerEvent">
  Fired for all players in a lobby when a new player joins. The `PlayerAction` contains the ID of the player who joined.
  *Argument: `PlayerAction`*
</ResponseField>

<ResponseField name="OnPlayerLeft" type="PlayerEvent">
  Fired for all players in a lobby when another player leaves. The `PlayerAction` contains the ID of the player who left.
  *Argument: `PlayerAction`*
</ResponseField>

### System Events

<ResponseField name="OnConnected" type="VoidEvent">
  Fired when the client successfully connects to the PlayFlow service.
  *Argument: `void`*
</ResponseField>

<ResponseField name="OnDisconnected" type="VoidEvent">
  Fired when the client disconnects from the PlayFlow service.
  *Argument: `void`*
</ResponseField>

<ResponseField name="OnError" type="StringEvent">
  Fired when any error occurs within the SDK. Provides a string message describing the error.
  *Argument: `string`*
</ResponseField>

### State Events

<ResponseField name="OnStateChanged" type="StateChangedEvent">
  Fired whenever the manager's internal state transitions (`Disconnected`, `Connecting`, `Connected`, `InLobby`, `InMatch`, etc.). Useful for gating UI flow — `(oldState, newState)`.
  *Argument: `LobbyState`, `LobbyState`*
</ResponseField>


# Lobby Hello World Example
Source: https://docs.playflowcloud.com/unity/lobby-hello-world

A guide to using the LobbyHelloWorld.cs example script to quickly test the PlayFlow Lobby SDK.

The PlayFlow SDK includes a `LobbyHelloWorld.cs` script that provides a simple, keyboard-driven way to test the entire lobby and matchmaking lifecycle without needing to build any UI. It's the fastest way to see the SDK in action.

This guide will walk you through setting up and using this example.

## Prerequisites

Before you start, make sure you have:

* A PlayFlow project and a **client API key** (prefix `pfclient_`), which is safe to ship in a game build. With the default `none` player-auth provider this key is all you need for the hello-world. If your project has a player-auth provider configured (custom JWT, PlayFab, or Steam), client-key requests must also send a valid player token — see [Player Authentication](../guides/player-authentication).
* A **lobby config** created for your project, and the manager's default lobby config set to match it (this example uses `firstLobby`).
* A **matchmaking mode** named `1VS1` defined on that lobby config if you want to test the matchmaking keys (`M`/`N`). A mode name that doesn't exist in your project config means the matchmaking keys have nothing to match against. See [Matchmaking](matchmaking) for how to define modes, teams, and rules.

## Setup Instructions

Follow these steps to get the example running in the Unity Editor.

<Steps>
  <Step title="Create a Test Scene">
    Start with a new, empty scene in your Unity project.
  </Step>

  <Step title="Add the Lobby Manager">
    1. Create an empty GameObject and name it `PlayFlowManager`.
    2. Add the `PlayFlowLobbyManagerV2` component to this GameObject.
    3. In the Inspector, paste your **client API key** (`pfclient_...`) into the corresponding field.
    4. Set the component's **default lobby config** to `firstLobby` (or the name of the lobby config you created for your project).
  </Step>

  <Step title="Add the Hello World Script">
    1. Create another empty GameObject and name it `LobbyTester`.
    2. Add the `LobbyHelloWorld.cs` script to this GameObject. This script is located in `Packages/PlayFlow Multiplayer Unity SDK/Runtime/PlayFlow Multiplayer/Lobby/Examples/`.
  </Step>

  <Step title="Run and Test">
    Press **Play** in the Unity Editor. Open your **Console** window to see the output and instructions. You can now use the keyboard shortcuts to interact with the lobby system.
  </Step>
</Steps>

## How It Works

The `LobbyHelloWorld.cs` script performs several key actions:

1. **Initializes** the `PlayFlowLobbyManagerV2` with a unique player ID.
2. **Subscribes** to all the major lobby events to provide real-time feedback in the console.
3. **Listens for keyboard inputs** in its `Update()` loop to trigger lobby functions.

### Keyboard Shortcuts

While the scene is running, use these keys to test the lobby functionality. Watch the Console window for detailed logs.

| Key | Action                               |
| :-: | :----------------------------------- |
| `R` | **Refresh** the public lobby list.   |
| `C` | **Create** a new public lobby.       |
| `J` | **Join** the first available lobby.  |
| `L` | **Leave** the current lobby.         |
| `S` | **Start** the match (host only).     |
| `E` | **End** the match (host only).       |
| `T` | **Update** your own player state.    |
| `I` | **Get** game-server connection info. |
| `M` | **Find Match** (start matchmaking).  |
| `N` | **Cancel** matchmaking.              |

<Info>
  The shipped script also binds the `U` key to a "host updates another player's state" demo. That key is intentionally left out of this table because the backend has no endpoint for one player to write another player's state — see the warning below.
</Info>

## The Example Code

Below is the full code for the `LobbyHelloWorld.cs` example. It's a great reference for how to call the different SDK functions and handle their success/error callbacks.

<Warning>
  The example includes methods that call `UpdateStateForPlayer(...)` — the `U` key (`UpdateOtherPlayerState`), `HostUpdateAnotherPlayerState`, and `HostAssignTeamsToAllPlayers`. **The backend does not support one player writing another player's state.** Every state write goes to the caller's own verified identity (`PATCH /me`), so these host-authoritative writes will not take effect on the server. To manage shared state, have each player set their own state with `UpdatePlayerState`, or store shared/lobby-wide data in the lobby's custom settings from the host.
</Warning>

<Tip>
  When the match server is ready, always read the connection **host** and **external port** from the server details (`OnMatchServerDetailsReady` / `GetGameServerConnectionInfo`). Proxy ports are allocated per server and differ from your game's internal listen port, so never hardcode a port like `7777` on the client.
</Tip>

<Tabs>
  <Tab title="Unity">
    ```csharp theme={null}
    using UnityEngine;
    using System.Collections.Generic;
    using System;
    using System.Linq;
    using PlayFlow;
    using System.Collections;
    using Newtonsoft.Json;

    /// <summary>
    /// A simple example demonstrating how to use the new PlayFlow Lobby SDK V2.
    /// This script shows the core functionality with keyboard shortcuts for testing.
    ///
    /// Setup Instructions:
    /// 1. Create an empty GameObject and add the PlayFlowLobbyManagerV2 component to it.
    /// 2. Configure your API key in the PlayFlowLobbyManagerV2 component in the Inspector.
    /// 3. Set the defaultLobbyConfig to "firstLobby" in the inspector
    /// 4. Create another empty GameObject and add this LobbyHelloWorld script to it.
    /// 5. Play the scene and use the keyboard shortcuts below.
    /// 
    /// Keyboard Shortcuts:
    /// - R: Refresh lobby list
    /// - C: Create a new lobby (for 1v1 matchmaking)
    /// - J: Join first available public lobby
    /// - L: Leave current lobby
    /// - S: Start the match (host only - direct match)
    /// - E: End the match (host only)
    /// - T: Send test player state update (with MMR)
    /// - U: Update other player's state (host only)
    /// - I: Get game server connection info
    /// - M: Start 1v1 Matchmaking (host only)
    /// - N: Cancel Matchmaking (host only)
    /// </summary>
    public class LobbyHelloWorld : MonoBehaviour
    {
        [Header("Settings")]
        [Tooltip("The name for lobbies created by this script")]
        public string lobbyName = "1v1 Match Lobby";
        
        [Tooltip("Maximum players for created lobbies (set to 2 for 1v1)")]
        [Range(2, 10)]
        public int maxPlayers = 2;
        
        [Tooltip("Whether created lobbies should be private")]
        public bool isPrivate = false;
        
        [Header("Matchmaking Settings")]
        [Tooltip("Your player's MMR (matchmaking rating) for testing")]
        [Range(800, 2000)]
        public int playerMMR = 1200;

        private string _playerId;

        void Start()
        {
            // Manager can now be accessed directly via the singleton instance
            if (PlayFlowLobbyManagerV2.Instance == null)
            {
                Debug.LogError("[LobbyHelloWorld] PlayFlowLobbyManagerV2 not found in the scene! Please add it to a GameObject.", this);
                return;
            }

            // Generate a unique player ID
            _playerId = "player-" + Guid.NewGuid().ToString("N").Substring(0, 8);
            Debug.Log($"[LobbyHelloWorld] Starting with player ID: {_playerId}");
            
            // Initialize the manager
            PlayFlowLobbyManagerV2.Instance.Initialize(_playerId, OnManagerReady);
            
            // Subscribe to events
            SubscribeToEvents();
        }
        
        void OnManagerReady()
        {
            Debug.Log("[LobbyHelloWorld] Manager is ready! Use keyboard shortcuts:");
            Debug.Log("  R - Refresh lobby list");
            Debug.Log("  C - Create a new lobby (for 1v1 matchmaking)");
            Debug.Log("  J - Join first available lobby");
            Debug.Log("  L - Leave current lobby");
            Debug.Log("  S - Start the match (direct match)");
            Debug.Log("  E - End the match");
            Debug.Log("  T - Send test player state (with MMR)");
            Debug.Log("  U - Update other player's state");
            Debug.Log("  I - Get game server connection info");
            Debug.Log("  M - Start 1v1 Matchmaking");
            Debug.Log("  N - Cancel Matchmaking");
            
            // Automatically set initial player state with MMR when ready
            StartCoroutine(SetInitialPlayerState());
        }
        
        void Update()
        {
            if (!PlayFlowLobbyManagerV2.Instance.IsReady) return;
            
            // Refresh lobby list
            if (Input.GetKeyDown(KeyCode.R))
            {
                RefreshLobbies();
            }
            
            // Create lobby
            if (Input.GetKeyDown(KeyCode.C))
            {
                CreateLobby();
            }
            
            // Join first available lobby
            if (Input.GetKeyDown(KeyCode.J))
            {
                JoinFirstAvailableLobby();
            }
            
            // Leave lobby
            if (Input.GetKeyDown(KeyCode.L))
            {
                LeaveLobby();
            }
            
            // Send player state update
            if (Input.GetKeyDown(KeyCode.T))
            {
                SendTestPlayerState();
            }
            
            // Start match
            if (Input.GetKeyDown(KeyCode.S))
            {
                StartMatch();
            }
            
            // End match
            if (Input.GetKeyDown(KeyCode.E))
            {
                EndMatch();
            }
            
            // [Host-Only] Update another player's state
            if (Input.GetKeyDown(KeyCode.U))
            {
                UpdateOtherPlayerState();
            }

            // Get game server connection info
            if (Input.GetKeyDown(KeyCode.I))
            {
                GetConnectionInfo();
            }
            
            // Start 1v1 Matchmaking
            if (Input.GetKeyDown(KeyCode.M))
            {
                StartMatchmaking();
            }
            
            // Cancel Matchmaking
            if (Input.GetKeyDown(KeyCode.N))
            {
                CancelMatchmaking();
            }
        }
        
        void RefreshLobbies()
        {
            Debug.Log("[LobbyHelloWorld] Refreshing lobby list...");
            
            PlayFlowLobbyManagerV2.Instance.GetAvailableLobbies(
                onSuccess: (lobbies) => {
                    Debug.Log($"[LobbyHelloWorld] Found {lobbies.Count} lobbies:");
                    foreach (var lobby in lobbies)
                    {
                        Debug.Log($"  - {lobby.name} ({lobby.currentPlayers}/{lobby.maxPlayers}) ID: {lobby.id}");
                    }
                },
                onError: (error) => {
                    Debug.LogError($"[LobbyHelloWorld] Failed to get lobbies: {error}");
                }
            );
        }
        
        void CreateLobby()
        {
            Debug.Log($"[LobbyHelloWorld] Creating 1v1 lobby '{lobbyName}'...");
            
            // Create custom settings for the lobby
            var customSettings = new Dictionary<string, object>
            {
                ["gameMode"] = "1v1",
                ["matchType"] = "ranked"
            };
            
            // Create lobby optimized for 1v1 matchmaking
            PlayFlowLobbyManagerV2.Instance.CreateLobby(
                name: lobbyName,
                maxPlayers: 2, // Always 2 for 1v1
                isPrivate: isPrivate,
                allowLateJoin: false, // No late join for competitive 1v1
                region: "us-west", // You might want to make this configurable
                customSettings: customSettings,
                onSuccess: (lobby) => {
                    Debug.Log($"[LobbyHelloWorld] Successfully created 1v1 lobby: {lobby.name} (ID: {lobby.id})");
                    if (lobby.isPrivate && !string.IsNullOrEmpty(lobby.code))
                    {
                        Debug.Log($"[LobbyHelloWorld] Invite code: {lobby.code}");
                    }
                    Debug.Log("[LobbyHelloWorld] Tip: Press 'M' to start 1v1 matchmaking once you're ready!");
                },
                onError: (error) => {
                    Debug.LogError($"[LobbyHelloWorld] Failed to create lobby: {error}");
                }
            );
        }
        
        void JoinFirstAvailableLobby()
        {
            Debug.Log("[LobbyHelloWorld] Looking for available lobbies...");
            
            PlayFlowLobbyManagerV2.Instance.GetAvailableLobbies(
                onSuccess: (lobbies) => {
                    var availableLobby = lobbies.Find(l => !l.isPrivate && l.currentPlayers < l.maxPlayers);
                    
                    if (availableLobby != null)
                    {
                        Debug.Log($"[LobbyHelloWorld] Joining lobby: {availableLobby.name}");
                        
                        PlayFlowLobbyManagerV2.Instance.JoinLobby(availableLobby.id,
                            onSuccess: (lobby) => {
                                Debug.Log($"[LobbyHelloWorld] Successfully joined lobby: {lobby.name}");
                            },
                            onError: (error) => {
                                Debug.LogError($"[LobbyHelloWorld] Failed to join lobby: {error}");
                            }
                        );
                    }
                    else
                    {
                        Debug.LogWarning("[LobbyHelloWorld] No available public lobbies found. Try creating one!");
                    }
                },
                onError: (error) => {
                    Debug.LogError($"[LobbyHelloWorld] Failed to get lobbies: {error}");
                }
            );
        }
        
        void LeaveLobby()
        {
            if (PlayFlowLobbyManagerV2.Instance.CurrentLobby == null)
            {
                Debug.LogWarning("[LobbyHelloWorld] Not in a lobby!");
                return;
            }
            
            Debug.Log("[LobbyHelloWorld] Leaving current lobby...");
            
            PlayFlowLobbyManagerV2.Instance.LeaveLobby(
                onSuccess: () => {
                    Debug.Log("[LobbyHelloWorld] Successfully left lobby");
                },
                onError: (error) => {
                    Debug.LogError($"[LobbyHelloWorld] Failed to leave lobby: {error}");
                }
            );
        }
        
        void StartMatch()
        {
            if (PlayFlowLobbyManagerV2.Instance.CurrentLobby == null || !PlayFlowLobbyManagerV2.Instance.IsHost)
            {
                Debug.LogWarning("[LobbyHelloWorld] Cannot start match: you must be in a lobby and be the host.");
                return;
            }
            
            Debug.Log("[LobbyHelloWorld] Starting match...");
            
            PlayFlowLobbyManagerV2.Instance.StartMatch(
                onSuccess: (lobby) => {
                    Debug.Log($"[LobbyHelloWorld] Match started successfully. Status: {lobby.status}");
                },
                onError: (error) => {
                    Debug.LogError($"[LobbyHelloWorld] Failed to start match: {error}");
                }
            );
        }
        
        void EndMatch()
        {
            if (PlayFlowLobbyManagerV2.Instance.CurrentLobby == null || !PlayFlowLobbyManagerV2.Instance.IsHost)
            {
                Debug.LogWarning("[LobbyHelloWorld] Cannot end match: you must be in a lobby and be the host.");
                return;
            }
            
            Debug.Log("[LobbyHelloWorld] Ending match...");
            
            PlayFlowLobbyManagerV2.Instance.EndMatch(
                onSuccess: (lobby) => {
                    Debug.Log($"[LobbyHelloWorld] Match ended successfully. Status: {lobby.status}");
                },
                onError: (error) => {
                    Debug.LogError($"[LobbyHelloWorld] Failed to end match: {error}");
                }
            );
        }
        
        void SendTestPlayerState()
        {
            if (PlayFlowLobbyManagerV2.Instance.CurrentLobby == null)
            {
                Debug.LogWarning("[LobbyHelloWorld] Not in a lobby!");
                return;
            }
            
            var testState = new Dictionary<string, object>
            {
                ["position"] = new Dictionary<string, float> { ["x"] = 10f, ["y"] = 20f },
                ["health"] = 100,
                ["ready"] = true,
                ["mmr"] = playerMMR, // Include MMR for matchmaking
                ["regions"] = new List<string> { "eu-west", "eu-north" },
                ["timestamp"] = DateTime.UtcNow.ToString()
            };
            
            Debug.Log($"[LobbyHelloWorld] Sending player state update with MMR: {playerMMR}...");
            
            PlayFlowLobbyManagerV2.Instance.UpdatePlayerState(testState,
                onSuccess: (lobby) => {
                    Debug.Log("[LobbyHelloWorld] Successfully updated player state");
                },
                onError: (error) => {
                    Debug.LogError($"[LobbyHelloWorld] Failed to update player state: {error}");
                }
            );
        }
        
        void GetConnectionInfo()
        {
            var manager = PlayFlowLobbyManagerV2.Instance;
            if (manager.CurrentLobby?.status != "in_game")
            {
                Debug.LogWarning("[LobbyHelloWorld] Cannot get connection info: not in a running match.");
                return;
            }

            ConnectionInfo? connectionInfo = manager.GetGameServerConnectionInfo();

            if (connectionInfo.HasValue)
            {
                Debug.Log($"[LobbyHelloWorld] Game Server Connection Info: IP = {connectionInfo.Value.Ip}, Port = {connectionInfo.Value.Port}");
                // Here you would use this information to connect your game client (e.g., using Netcode, Mirror, etc.)
            }
            else
            {
                Debug.LogError("[LobbyHelloWorld] Failed to get connection info, although the match is running. The server data might be missing.");
            }
        }
        
        void UpdateOtherPlayerState()
        {
            var manager = PlayFlowLobbyManagerV2.Instance;
            if (!manager.IsHost)
            {
                Debug.LogWarning("[LobbyHelloWorld] Only the host can update another player's state.");
                return;
            }

            if (manager.CurrentLobby == null || manager.CurrentLobby.players.Length < 2)
            {
                Debug.LogWarning("[LobbyHelloWorld] Need at least one other player in the lobby to test this feature.");
                return;
            }

            // Find the first player who is not the host
            string otherPlayerId = null;
            foreach (var player in manager.CurrentLobby.players)
            {
                if (player != manager.PlayerId)
                {
                    otherPlayerId = player;
                    break;
                }
            }

            if (string.IsNullOrEmpty(otherPlayerId))
            {
                 Debug.LogWarning("[LobbyHelloWorld] Couldn't find another player in the lobby.");
                 return;
            }

            var testState = new Dictionary<string, object>
            {
                ["messageFromHost"] = "The host updated your state!",
                ["timestamp"] = DateTime.UtcNow.ToString()
            };

            Debug.Log($"[LobbyHelloWorld] Host is updating state for player {otherPlayerId}...");
            
            manager.UpdateStateForPlayer(otherPlayerId, testState,
                onSuccess: (lobby) => {
                    Debug.Log($"[LobbyHelloWorld] Successfully updated state for player {otherPlayerId}.");
                },
                onError: (error) => {
                    Debug.LogError($"[LobbyHelloWorld] Failed to update player state: {error}");
                }
            );
        }
        
        void StartMatchmaking()
        {
            if (!PlayFlowLobbyManagerV2.Instance.IsInLobby || !PlayFlowLobbyManagerV2.Instance.IsHost)
            {
                Debug.LogWarning("[LobbyHelloWorld] Must be host in a lobby to start matchmaking!");
                return;
            }

            Debug.Log("[LobbyHelloWorld] Starting 1v1 matchmaking...");
            
            PlayFlowLobbyManagerV2.Instance.FindMatch("1VS1",
                onSuccess: (lobby) => {
                    Debug.Log($"[LobbyHelloWorld] Successfully started matchmaking! Status: {lobby.status}");
                    Debug.Log($"[LobbyHelloWorld] Matchmaking mode: {lobby.matchmaking.mode}");
                },
                onError: (error) => {
                    Debug.LogError($"[LobbyHelloWorld] Failed to start matchmaking: {error}");
                }
            );
        }
        
        void CancelMatchmaking()
        {
            if (!PlayFlowLobbyManagerV2.Instance.IsInLobby || !PlayFlowLobbyManagerV2.Instance.IsHost)
            {
                Debug.LogWarning("[LobbyHelloWorld] Must be host in a lobby to cancel matchmaking!");
                return;
            }

            Debug.Log("[LobbyHelloWorld] Cancelling matchmaking...");
            
            PlayFlowLobbyManagerV2.Instance.CancelMatchmaking(
                onSuccess: (lobby) => {
                    Debug.Log($"[LobbyHelloWorld] Successfully cancelled matchmaking! Status: {lobby.status}");
                },
                onError: (error) => {
                    Debug.LogError($"[LobbyHelloWorld] Failed to cancel matchmaking: {error}");
                }
            );
        }
        
        IEnumerator SetInitialPlayerState()
        {
            // Wait a frame to ensure everything is initialized
            yield return null;
            
            // Wait until we're in a lobby
            yield return new WaitUntil(() => PlayFlowLobbyManagerV2.Instance.IsInLobby);
            
            // Set initial player state with MMR
            var initialState = new Dictionary<string, object>
            {
                ["mmr"] = playerMMR,
                ["ready"] = false,
                ["playerName"] = $"Player_{_playerId.Substring(0, 8)}"
            };
            
            Debug.Log($"[LobbyHelloWorld] Setting initial player state with MMR: {playerMMR}");
            
            PlayFlowLobbyManagerV2.Instance.UpdatePlayerState(initialState,
                onSuccess: (lobby) => {
                    Debug.Log("[LobbyHelloWorld] Initial player state set successfully");
                },
                onError: (error) => {
                    Debug.LogError($"[LobbyHelloWorld] Failed to set initial player state: {error}");
                }
            );
        }
        
        void SubscribeToEvents()
        {
            var events = PlayFlowLobbyManagerV2.Instance.Events;
            
            // Lobby events
            events.OnLobbyCreated.AddListener(OnLobbyCreated);
            events.OnLobbyJoined.AddListener(OnLobbyJoined);
            events.OnLobbyUpdated.AddListener(OnLobbyUpdated);
            events.OnLobbyLeft.AddListener(OnLobbyLeft);
            
            // Match events
            events.OnMatchStarted.AddListener(OnMatchStarted);
            events.OnMatchEnded.AddListener(OnMatchEnded);
            events.OnMatchRunning.AddListener(OnMatchRunning);
            events.OnMatchServerDetailsReady.AddListener(OnMatchServerDetailsReady);
            
            // Matchmaking events
            events.OnMatchmakingStarted.AddListener(OnMatchmakingStarted);
            events.OnMatchmakingCancelled.AddListener(OnMatchmakingCancelled);
            events.OnMatchFound.AddListener(OnMatchFound);
            
            // Player events
            events.OnPlayerJoined.AddListener(OnPlayerJoined);
            events.OnPlayerLeft.AddListener(OnPlayerLeft);
            
            // System events
            events.OnError.AddListener(OnError);
            
            // Session state changes
            var manager = PlayFlowLobbyManagerV2.Instance;
            manager.Events.OnStateChanged.AddListener(OnStateChanged);
        }
        
        // Event handlers
        void OnStateChanged(LobbyState oldState, LobbyState newState)
        {
            Debug.Log($"[LobbyHelloWorld] State changed: {oldState} -> {newState}");
        }
        
        void OnLobbyCreated(Lobby lobby)
        {
            Debug.Log($"[LobbyHelloWorld] EVENT: Lobby created - {lobby.name}");
        }
        
        void OnLobbyJoined(Lobby lobby)
        {
            Debug.Log($"[LobbyHelloWorld] EVENT: Joined lobby - {lobby.name}");
            Debug.Log($"  Players: {string.Join(", ", lobby.players)}");
            Debug.Log($"  Host: {lobby.host}");
        }
        
        void OnLobbyUpdated(Lobby lobby)
        {
            Debug.Log($"[LobbyHelloWorld] EVENT: Lobby updated - {lobby.name} ({lobby.currentPlayers}/{lobby.maxPlayers})");
            
            // Check if SSE is connected
            var sseManager = LobbySseManager.Instance;
            if (sseManager != null && sseManager.IsConnected)
            {
                Debug.Log("[LobbyHelloWorld] ✅ Update received via SSE (real-time)");
            }
            else
            {
                Debug.Log("[LobbyHelloWorld] ⏱️ Update received via polling");
            }
        }
        
        void OnLobbyLeft()
        {
            Debug.Log("[LobbyHelloWorld] EVENT: Left lobby");
        }
        
        // =============================================================================
        // PLAYER STATE UPDATE EXAMPLES
        // =============================================================================
        
        /// <summary>
        /// Example: Update your own player state
        /// Any player can update their own state at any time
        /// </summary>
        public void UpdateMyOwnState()
        {
            // Check if we're in a lobby
            if (!PlayFlowLobbyManagerV2.Instance.IsInLobby)
            {
                Debug.LogWarning("Not in a lobby!");
                return;
            }
            
            // Create your player state data
            var myState = new Dictionary<string, object>
            {
                ["position"] = new Dictionary<string, float> { ["x"] = 100f, ["y"] = 50f, ["z"] = 0f },
                ["health"] = 85,
                ["armor"] = 50,
                ["weapon"] = "plasma_rifle",
                ["team"] = "blue",
                ["ready"] = true,
                ["lastUpdated"] = DateTime.UtcNow.ToString()
            };
            
            // Update your own state
            PlayFlowLobbyManagerV2.Instance.UpdatePlayerState(myState, 
                onSuccess: (lobby) => {
                    Debug.Log($"Successfully updated my state. My player ID: {PlayFlowLobbyManagerV2.Instance.PlayerId}");
                    
                    // You can access your updated state from the lobby
                    if (lobby.lobbyStateRealTime.TryGetValue(PlayFlowLobbyManagerV2.Instance.PlayerId, out var updatedState))
                    {
                        Debug.Log($"My updated state: {JsonConvert.SerializeObject(updatedState)}");
                    }
                },
                onError: (error) => {
                    Debug.LogError($"Failed to update my state: {error}");
                }
            );
        }
        
        /// <summary>
        /// Example: Host updates another player's state
        /// Only the host can update other players' states
        /// </summary>
        public void HostUpdateAnotherPlayerState(string targetPlayerId)
        {
            // Check if we're in a lobby
            if (!PlayFlowLobbyManagerV2.Instance.IsInLobby)
            {
                Debug.LogWarning("Not in a lobby!");
                return;
            }
            
            // Check if we're the host
            if (!PlayFlowLobbyManagerV2.Instance.IsHost)
            {
                Debug.LogError("Only the host can update other players' states!");
                return;
            }
            
            // Verify target player is in the lobby
            var currentLobby = PlayFlowLobbyManagerV2.Instance.CurrentLobby;
            if (!currentLobby.players.Contains(targetPlayerId))
            {
                Debug.LogError($"Player {targetPlayerId} is not in the lobby!");
                return;
            }
            
            // Create state data for the target player
            var targetPlayerState = new Dictionary<string, object>
            {
                ["team"] = "red",  // Host assigns player to red team
                ["role"] = "sniper",  // Host assigns player role
                ["spawnPoint"] = new Dictionary<string, float> { ["x"] = 200f, ["y"] = 100f, ["z"] = 50f },
                ["allowedWeapons"] = new List<string> { "sniper_rifle", "pistol" },
                ["updatedByHost"] = true,
                ["hostUpdatedAt"] = DateTime.UtcNow.ToString()
            };
            
            // Update the target player's state
            PlayFlowLobbyManagerV2.Instance.UpdateStateForPlayer(targetPlayerId, targetPlayerState,
                onSuccess: (lobby) => {
                    Debug.Log($"Host successfully updated state for player: {targetPlayerId}");
                    
                    // Verify the update
                    if (lobby.lobbyStateRealTime.TryGetValue(targetPlayerId, out var updatedState))
                    {
                        Debug.Log($"Target player's updated state: {JsonConvert.SerializeObject(updatedState)}");
                    }
                },
                onError: (error) => {
                    Debug.LogError($"Failed to update player {targetPlayerId}'s state: {error}");
                }
            );
        }
        
        /// <summary>
        /// Example: Host assigns teams to all players
        /// Demonstrates batch updates by the host
        /// </summary>
        public void HostAssignTeamsToAllPlayers()
        {
            if (!PlayFlowLobbyManagerV2.Instance.IsInLobby || !PlayFlowLobbyManagerV2.Instance.IsHost)
            {
                Debug.LogError("Must be host and in lobby to assign teams!");
                return;
            }
            
            var players = PlayFlowLobbyManagerV2.Instance.CurrentLobby.players;
            var teamAssignments = new[] { "blue", "red" };
            
            for (int i = 0; i < players.Count(); i++)
            {
                var playerId = players[i];
                var team = teamAssignments[i % 2]; // Alternate between blue and red
                
                var teamState = new Dictionary<string, object>
                {
                    ["team"] = team,
                    ["teamAssignedAt"] = DateTime.UtcNow.ToString()
                };
                
                // Skip if it's the host's own ID - use UpdatePlayerState instead
                if (playerId == PlayFlowLobbyManagerV2.Instance.PlayerId)
                {
                    PlayFlowLobbyManagerV2.Instance.UpdatePlayerState(teamState);
                }
                else
                {
                    PlayFlowLobbyManagerV2.Instance.UpdateStateForPlayer(playerId, teamState);
                }
            }
            
            Debug.Log("Host assigned teams to all players!");
        }
        
        void OnPlayerJoined(PlayerAction action)
        {
            Debug.Log($"[LobbyHelloWorld] EVENT: Player joined - {action.PlayerId}");
        }
        
        void OnPlayerLeft(PlayerAction action)
        {
            Debug.Log($"[LobbyHelloWorld] EVENT: Player left - {action.PlayerId}");
        }
        
        void OnError(string error)
        {
            Debug.LogError($"[LobbyHelloWorld] EVENT: Error - {error}");
        }
        
        void OnMatchStarted(Lobby lobby)
        {
            Debug.Log($"[LobbyHelloWorld] EVENT: Match start has been triggered for lobby {lobby.name}. Waiting for server to be ready...");
        }

        void OnMatchRunning(ConnectionInfo connectionInfo)
        {
            Debug.Log($"[LobbyHelloWorld] EVENT: Server is ready! IP: {connectionInfo.Ip}, Port: {connectionInfo.Port}");
            // Here you would connect your game client using the connectionInfo details.
        }

        void OnMatchServerDetailsReady(List<PortMappingInfo> portMappings)
        {
            Debug.Log("[LobbyHelloWorld] EVENT: Full server details are ready.");
            foreach (var portInfo in portMappings)
            {
                Debug.Log($"  - Port '{portInfo.Name}' ({portInfo.Protocol}): connect to {portInfo.Host}:{portInfo.ExternalPort} (game listens on internal port {portInfo.InternalPort})");
            }

            // Example: Find the specific port for your game (e.g., the one mapped from internal port 7770)
            if (PlayFlowLobbyManagerV2.Instance.CurrentLobby.TryGetPortMapping(7770, out var gamePort))
            {
                Debug.Log($"[LobbyHelloWorld] Found our specific game port '{gamePort.Name}' running on {gamePort.Host}:{gamePort.ExternalPort}");
                // Connect your game client using gamePort.Host and gamePort.ExternalPort
            }
        }
        
        void OnMatchEnded(Lobby lobby)
        {
            Debug.Log($"[LobbyHelloWorld] EVENT: Match ended in lobby {lobby.name}. Returning to 'waiting' status.");
        }
        
        void OnMatchmakingStarted(Lobby lobby)
        {
            Debug.Log($"[LobbyHelloWorld] EVENT: Matchmaking started! Mode: {lobby.matchmaking.mode}, Status: {lobby.status}");
            Debug.Log($"[LobbyHelloWorld] Looking for opponents with similar MMR...");
        }
        
        void OnMatchmakingCancelled(Lobby lobby)
        {
            Debug.Log($"[LobbyHelloWorld] EVENT: Matchmaking cancelled. Status: {lobby.status}");
        }
        
        void OnMatchFound(Lobby lobby)
        {
            Debug.Log($"[LobbyHelloWorld] EVENT: Match found! Status: {lobby.status}");
            Debug.Log($"[LobbyHelloWorld] Game server is being launched...");
            
            // Log matchmaking data if available
            if (lobby.matchmakingData != null)
            {
                Debug.Log($"[LobbyHelloWorld] Matchmaking data: {JsonConvert.SerializeObject(lobby.matchmakingData)}");
            }
        }
        
        void OnDestroy()
        {
            // Clean up
            if (PlayFlowLobbyManagerV2.Instance != null)
            {
                // If the player is in a lobby, make sure they leave it gracefully.
                if (PlayFlowLobbyManagerV2.Instance.IsInLobby)
                {
                    // This is a fire-and-forget call. We don't wait for the response
                    // because the application is likely quitting.
                    PlayFlowLobbyManagerV2.Instance.LeaveLobby();
                }
                
                PlayFlowLobbyManagerV2.Instance.Disconnect();
                
                // Unsubscribe from events
                var events = PlayFlowLobbyManagerV2.Instance.Events;
                events.OnLobbyCreated.RemoveAllListeners();
                events.OnLobbyJoined.RemoveAllListeners();
                events.OnLobbyUpdated.RemoveAllListeners();
                events.OnLobbyLeft.RemoveAllListeners();
                events.OnPlayerJoined.RemoveAllListeners();
                events.OnPlayerLeft.RemoveAllListeners();
                events.OnMatchStarted.RemoveAllListeners();
                events.OnMatchEnded.RemoveAllListeners();
                events.OnMatchRunning.RemoveAllListeners();
                events.OnMatchServerDetailsReady.RemoveAllListeners();
                events.OnMatchmakingStarted.RemoveAllListeners();
                events.OnMatchmakingCancelled.RemoveAllListeners();
                events.OnMatchFound.RemoveAllListeners();
                events.OnError.RemoveAllListeners();
            }
        }
    }
    ```
  </Tab>

  <Tab title="Godot">
    Coming soon...
  </Tab>

  <Tab title="Unreal Engine">
    Coming soon...
  </Tab>
</Tabs>


# Lobby Manager API Reference
Source: https://docs.playflowcloud.com/unity/lobby-manager-api

A detailed API reference for the PlayFlowLobbyManagerV2 class in the Unity SDK.

This document provides a detailed reference for the public properties and methods of the `PlayFlowLobbyManagerV2` class.

## Properties

<ResponseField name="Instance" type="PlayFlowLobbyManagerV2">
  Singleton instance of the Lobby Manager. Access all lobby functionality through this.
</ResponseField>

<ResponseField name="IsReady" type="bool">
  Returns true if the manager has been successfully initialized.
</ResponseField>

<ResponseField name="CurrentLobby" type="Lobby">
  Gets the full data for the lobby the player is currently in. Returns null if not in a lobby.
</ResponseField>

<ResponseField name="PlayerId" type="string">
  Gets the unique ID of the current player, as provided during initialization.
</ResponseField>

<ResponseField name="State" type="LobbyState">
  Gets the current state of the lobby session (e.g., Disconnected, InLobby).
</ResponseField>

<ResponseField name="Events" type="PlayFlowEvents">
  Provides access to all lobby-related UnityEvents (e.g., OnLobbyJoined, OnPlayerLeft).
</ResponseField>

<ResponseField name="AvailableLobbies" type="List<Lobby>">
  A cached list of all currently available public lobbies. This list is updated automatically if auto-refresh is enabled.
</ResponseField>

<ResponseField name="IsInLobby" type="bool">
  A quick check to see if the player is currently in a lobby.
</ResponseField>

<ResponseField name="IsHost" type="bool">
  Returns true if the current player is the host of the lobby they are in.
</ResponseField>

<ResponseField name="InviteCode" type="string">
  Gets the invite code for the current private lobby. Returns null if not in a private lobby.
</ResponseField>

## Methods

<AccordionGroup>
  <Accordion title="Initialize">
    Initializes the lobby manager. This must be called before any other lobby operations.

    ```csharp theme={null}
    public void Initialize(string playerId, Action onComplete = null)
    ```

    <ResponseField name="playerId" type="string">
      A unique identifier for the local player.
    </ResponseField>

    <ResponseField name="onComplete" type="Action">
      An optional callback that is invoked when initialization is successful.
    </ResponseField>
  </Accordion>

  <Accordion title="CreateLobby">
    Creates a new lobby. There are two overloads for this method.

    Pass `forceFresh: true` to replace any lobby the local player currently **hosts**
    in this config — the backend deletes the old lobby (stopping its game server
    best-effort) before creating the new one. Intended for reconnect / "start a
    fresh session" flows, where the host may still own a stale lobby from a
    previous run. It's a no-op when the player has no prior lobby.

    **Simple:**

    ```csharp theme={null}
    public void CreateLobby(string name, int maxPlayers = 4, bool isPrivate = false, bool forceFresh = false, Action<Lobby> onSuccess = null, Action<string> onError = null)
    ```

    <ResponseField name="name" type="string">The public name of the lobby.</ResponseField>
    <ResponseField name="maxPlayers" type="int">The maximum number of players (1–100). The SDK sends `4` when omitted; if you call the API directly and omit this field, the server default is `2`.</ResponseField>
    <ResponseField name="isPrivate" type="bool">If true, the lobby will not appear in public searches.</ResponseField>
    <ResponseField name="forceFresh" type="bool">If true, delete any lobby the local player already hosts before creating a new one. Defaults to `false`.</ResponseField>
    <ResponseField name="onSuccess" type="Action<Lobby>">Callback invoked with the created lobby data on success.</ResponseField>
    <ResponseField name="onError" type="Action<string>">Callback invoked with an error message on failure.</ResponseField>

    **Detailed:**

    ```csharp theme={null}
    public void CreateLobby(string name, int maxPlayers, bool isPrivate, bool allowLateJoin, string region, Dictionary<string, object> customSettings, bool forceFresh = false, Action<Lobby> onSuccess = null, Action<string> onError = null)
    ```

    <ResponseField name="name" type="string">The public name of the lobby.</ResponseField>
    <ResponseField name="maxPlayers" type="int">The maximum number of players that can join.</ResponseField>
    <ResponseField name="isPrivate" type="bool">If true, the lobby will not appear in public searches.</ResponseField>
    <ResponseField name="allowLateJoin" type="bool">If true, players can join even after the match has started.</ResponseField>
    <ResponseField name="region" type="string">The server region for the lobby (e.g., "us-west").</ResponseField>
    <ResponseField name="customSettings" type="Dictionary<string, object>">A dictionary of custom game-specific settings.</ResponseField>
    <ResponseField name="forceFresh" type="bool">If true, delete any lobby the local player already hosts before creating a new one. Defaults to `false`.</ResponseField>
    <ResponseField name="onSuccess" type="Action<Lobby>">Callback invoked with the created lobby data on success.</ResponseField>
    <ResponseField name="onError" type="Action<string>">Callback invoked with an error message on failure.</ResponseField>
  </Accordion>

  <Accordion title="CreateFreshLobby">
    Shorthand for `CreateLobby(..., forceFresh: true)`. The backend first deletes
    any lobby this player already hosts (stopping its game server best-effort),
    then creates a brand-new lobby atomically — replacing the old
    "TryReconnect → DeleteLobby → CreateLobby" dance with a single call.

    ```csharp theme={null}
    public void CreateFreshLobby(string name, int maxPlayers = 4, bool isPrivate = false, Action<Lobby> onSuccess = null, Action<string> onError = null)
    ```

    <ResponseField name="name" type="string">The public name of the lobby.</ResponseField>
    <ResponseField name="maxPlayers" type="int">The maximum number of players (1–100). The SDK sends `4` when omitted; the raw API default is `2`.</ResponseField>
    <ResponseField name="isPrivate" type="bool">If true, the lobby will not appear in public searches.</ResponseField>
    <ResponseField name="onSuccess" type="Action<Lobby>">Callback invoked with the created lobby data on success.</ResponseField>
    <ResponseField name="onError" type="Action<string>">Callback invoked with an error message on failure.</ResponseField>
  </Accordion>

  <Accordion title="JoinLobby">
    Joins an existing lobby using its unique ID.

    ```csharp theme={null}
    public void JoinLobby(string lobbyId, Action<Lobby> onSuccess = null, Action<string> onError = null)
    ```

    <ResponseField name="lobbyId" type="string">The unique ID (UUID) of the lobby to join.</ResponseField>
    <ResponseField name="onSuccess" type="Action<Lobby>">Callback invoked with the joined lobby data on success.</ResponseField>
    <ResponseField name="onError" type="Action<string>">Callback invoked with an error message on failure.</ResponseField>
  </Accordion>

  <Accordion title="JoinLobbyByCode">
    Joins an existing private lobby using its invite code.

    ```csharp theme={null}
    public void JoinLobbyByCode(string inviteCode, Action<Lobby> onSuccess = null, Action<string> onError = null)
    ```

    <ResponseField name="inviteCode" type="string">The invite code of the lobby to join.</ResponseField>
    <ResponseField name="onSuccess" type="Action<Lobby>">Callback invoked with the joined lobby data on success.</ResponseField>
    <ResponseField name="onError" type="Action<string>">Callback invoked with an error message on failure.</ResponseField>
  </Accordion>

  <Accordion title="GetAvailableLobbies">
    Fetches the list of public lobbies in the project. Results are also cached on the `AvailableLobbies` property.

    ```csharp theme={null}
    public void GetAvailableLobbies(Action<List<Lobby>> onSuccess, Action<string> onError = null)
    ```

    <ResponseField name="onSuccess" type="Action<List<Lobby>>">Callback invoked with the list of public lobbies.</ResponseField>
    <ResponseField name="onError" type="Action<string>">Callback invoked with an error message on failure.</ResponseField>
  </Accordion>

  <Accordion title="LeaveLobby">
    Leaves the lobby the player is currently in.

    ```csharp theme={null}
    public void LeaveLobby(Action onSuccess = null, Action<string> onError = null)
    ```

    <ResponseField name="onSuccess" type="Action">Callback invoked on successfully leaving the lobby.</ResponseField>
    <ResponseField name="onError" type="Action<string>">Callback invoked with an error message on failure.</ResponseField>
  </Accordion>

  <Accordion title="UpdatePlayerState">
    Updates the **local player's** custom state data within the lobby. This is useful for synchronizing data like character selection or ready status.

    ```csharp theme={null}
    public void UpdatePlayerState(Dictionary<string, object> state, Action<Lobby> onSuccess = null, Action<string> onError = null)
    ```

    <ResponseField name="state" type="Dictionary<string, object>">A dictionary representing the player's custom data.</ResponseField>
    <ResponseField name="onSuccess" type="Action<Lobby>">Callback invoked with the updated lobby data on success.</ResponseField>
    <ResponseField name="onError" type="Action<string>">Callback invoked with an error message on failure.</ResponseField>
  </Accordion>

  <Accordion title="UpdateStateForPlayer">
    Kept for backward compatibility. In V3, **only the target player can update their own state** — if `targetPlayerId` isn't the local player this call routes to `UpdatePlayerState()` and logs a warning. For team/role assignment, have each player set their own team via `UpdatePlayerState()` or push assignments through `UpdateLobbySettings()` (host-owned).

    ```csharp theme={null}
    public void UpdateStateForPlayer(string targetPlayerId, Dictionary<string, object> state, Action<Lobby> onSuccess = null, Action<string> onError = null)
    ```

    <ResponseField name="targetPlayerId" type="string">The unique ID of the player whose state you want to update. Must equal the local player ID.</ResponseField>
    <ResponseField name="state" type="Dictionary<string, object>">A dictionary representing the new data for the target player.</ResponseField>
    <ResponseField name="onSuccess" type="Action<Lobby>">Callback invoked with the updated lobby data on success.</ResponseField>
    <ResponseField name="onError" type="Action<string>">Callback invoked with an error message on failure.</ResponseField>
  </Accordion>

  <Accordion title="KickPlayer">
    Kicks a player from the lobby. This can only be called by the host.

    ```csharp theme={null}
    public void KickPlayer(string playerToKickId, Action<Lobby> onSuccess = null, Action<string> onError = null)
    ```

    <ResponseField name="playerToKickId" type="string">The unique ID of the player to remove from the lobby.</ResponseField>
    <ResponseField name="onSuccess" type="Action<Lobby>">Callback invoked with the updated lobby data on success.</ResponseField>
    <ResponseField name="onError" type="Action<string>">Callback invoked with an error message on failure.</ResponseField>
  </Accordion>

  <Accordion title="UpdateLobby">
    Host-only. Updates lobby metadata and settings. Pass only the fields you want to change — unspecified fields are left untouched. Cannot be called while the lobby is `in_game`.

    ```csharp theme={null}
    public void UpdateLobby(
        string name = null,
        int? maxPlayers = null,
        bool? isPrivate = null,
        bool? allowLateJoin = null,
        string region = null,
        Dictionary<string, object> customSettings = null,
        Action<Lobby> onSuccess = null,
        Action<string> onError = null)
    ```

    <ResponseField name="name" type="string">New lobby name (1–100 characters).</ResponseField>
    <ResponseField name="maxPlayers" type="int?">New max player count (1–100).</ResponseField>
    <ResponseField name="isPrivate" type="bool?">Toggle public/private listing.</ResponseField>
    <ResponseField name="allowLateJoin" type="bool?">Allow players to join after the match starts.</ResponseField>
    <ResponseField name="region" type="string">Region for the next game server (e.g. `"us-west"`).</ResponseField>
    <ResponseField name="customSettings" type="Dictionary<string, object>">Replace the custom settings blob.</ResponseField>
    <ResponseField name="onSuccess" type="Action<Lobby>">Callback invoked with the updated lobby data on success.</ResponseField>
    <ResponseField name="onError" type="Action<string>">Callback invoked with an error message on failure.</ResponseField>

    <Info>
      Invite codes can't be toggled per-lobby at runtime. Whether a lobby type issues invite codes is controlled by its `inviteCodeConfig` in Project Settings; every lobby of a type that has it enabled gets a code automatically.
    </Info>
  </Accordion>

  <Accordion title="UpdateLobbySettings">
    Convenience shortcut for `UpdateLobby(customSettings: newSettings)`. Host-only. Use this when you only need to update the `customSettings` dictionary.

    ```csharp theme={null}
    public void UpdateLobbySettings(Dictionary<string, object> newSettings, Action<Lobby> onSuccess = null, Action<string> onError = null)
    ```

    <ResponseField name="newSettings" type="Dictionary<string, object>">New custom settings dictionary (replaces the existing one).</ResponseField>
    <ResponseField name="onSuccess" type="Action<Lobby>">Callback invoked with the updated lobby data on success.</ResponseField>
    <ResponseField name="onError" type="Action<string>">Callback invoked with an error message on failure.</ResponseField>
  </Accordion>

  <Accordion title="DeleteLobby">
    Host-only. Deletes the current lobby for every player. All members are kicked and the lobby stops appearing in public searches.

    ```csharp theme={null}
    public void DeleteLobby(Action onSuccess = null, Action<string> onError = null)
    ```

    <ResponseField name="onSuccess" type="Action">Callback invoked once the lobby has been deleted.</ResponseField>
    <ResponseField name="onError" type="Action<string>">Callback invoked with an error message on failure.</ResponseField>
  </Accordion>

  <Accordion title="TransferHost (V3: not supported)">
    <Warning>
      V3 does not support explicit host transfer. Calling this method logs a warning and invokes `onError`. When the current host leaves, the server promotes a new host automatically — no manual transfer needed. Kept on the class for backward compatibility with V2 integrations.
    </Warning>

    ```csharp theme={null}
    public void TransferHost(string newHostId, Action<Lobby> onSuccess = null, Action<string> onError = null)
    ```
  </Accordion>

  <Accordion title="StartMatch">
    Starts the match directly, skipping matchmaking. Host-only. Launches a dedicated game server and transitions status to `in_game`. Use this for "Invite a friend" style lobbies; use `FindMatch()` for competitive queues.

    ```csharp theme={null}
    public void StartMatch(Action<Lobby> onSuccess = null, Action<string> onError = null)
    ```

    <ResponseField name="onSuccess" type="Action<Lobby>">Callback invoked with the updated lobby data on success.</ResponseField>
    <ResponseField name="onError" type="Action<string>">Callback invoked with an error message on failure.</ResponseField>
  </Accordion>

  <Accordion title="EndMatch">
    Host-only. Rematch helper — stops the current game server, returns the lobby to `waiting` while keeping all players, invite code, and settings intact. Perfect for a "Play again" button. Requires lobby status `in_game`.

    If the server stops on its own (TTL, crash, clean exit), the lobby also auto-heals to `waiting` — no call needed.

    ```csharp theme={null}
    public void EndMatch(Action<Lobby> onSuccess = null, Action<string> onError = null)
    ```

    <ResponseField name="onSuccess" type="Action<Lobby>">Callback invoked with the updated lobby data on success.</ResponseField>
    <ResponseField name="onError" type="Action<string>">Callback invoked with an error message on failure.</ResponseField>
  </Accordion>

  ### Matchmaking

  <Accordion title="FindMatch">
    Host-only. Enters the lobby into the matchmaking queue for the given mode. Modes are configured per-project in the dashboard (5v5, 1v1, FFA, party sizes, skill rules, etc.).

    Subscribe to `OnMatchmakingStarted`, `OnQueueStats`, and `OnMatchFound` / `OnMatchAwaitingConfirmation` to drive your matchmaking UI. The lobby transitions `waiting → in_queue → in_game` (or `match_found` first, if the mode has `matchConfirmation` enabled).

    ```csharp theme={null}
    public void FindMatch(string mode, Action<Lobby> onSuccess = null, Action<string> onError = null)
    ```

    <ResponseField name="mode" type="string">Matchmaking mode name (must exist in dashboard config).</ResponseField>
    <ResponseField name="onSuccess" type="Action<Lobby>">Callback invoked once the lobby enters the queue.</ResponseField>
    <ResponseField name="onError" type="Action<string>">Callback invoked on validation/API error.</ResponseField>
  </Accordion>

  <Accordion title="CancelMatchmaking">
    Host-only. Exits the matchmaking queue. Lobby returns to `waiting` with all players intact.

    ```csharp theme={null}
    public void CancelMatchmaking(Action<Lobby> onSuccess = null, Action<string> onError = null)
    ```

    <ResponseField name="onSuccess" type="Action<Lobby>">Callback invoked when back in `waiting`.</ResponseField>
    <ResponseField name="onError" type="Action<string>">Callback invoked with an error message on failure.</ResponseField>
  </Accordion>

  <Accordion title="ConfirmMatch">
    CS2-style "Accept Match". Only relevant when the matchmaking mode has `matchConfirmation.enabled: true` and the lobby is in `match_found` status. Any player in the lobby can call this. Once every matched lobby confirms, the game server launches and status becomes `in_game`.

    Listen for `OnMatchAwaitingConfirmation` (match pending), `OnMatchConfirmed` (you/your lobby accepted), and `OnMatchDeclined` (someone declined or the window timed out — back to `waiting`).

    ```csharp theme={null}
    public void ConfirmMatch(Action<Lobby> onSuccess = null, Action<string> onError = null)
    ```

    <ResponseField name="onSuccess" type="Action<Lobby>">Callback invoked once the confirmation is recorded.</ResponseField>
    <ResponseField name="onError" type="Action<string>">Callback invoked with an error message on failure.</ResponseField>
  </Accordion>

  <Accordion title="DeclineMatch">
    Declines a found match. **Cancels the match for every participating lobby** — one dissenter bails everyone. All lobbies (yours included) return to `waiting`; players must explicitly re-queue if they want to try again. Only valid while the lobby is in `match_found`.

    ```csharp theme={null}
    public void DeclineMatch(Action<Lobby> onSuccess = null, Action<string> onError = null)
    ```

    <ResponseField name="onSuccess" type="Action<Lobby>">Callback invoked once the decline is recorded.</ResponseField>
    <ResponseField name="onError" type="Action<string>">Callback invoked with an error message on failure.</ResponseField>
  </Accordion>

  ### Connection Info

  <Accordion title="GetGameServerConnectionInfo">
    Convenience helper that returns the first port as a simple `{ Ip, Port }` tuple. Good for single-port games; for anything else use the named lookups below.

    ```csharp theme={null}
    public ConnectionInfo? GetGameServerConnectionInfo()
    ```

    **Returns:** A `ConnectionInfo` struct with `Ip` and `Port` of the first `network_ports` entry, or `null` if no server is running.
  </Accordion>

  <Accordion title="Port lookups (by name) — recommended">
    Look up a network port by the name you defined in your project's port configuration (e.g. `"game_udp"`, `"voice_tcp"`). These live directly on `Lobby` (and mirror to `GameServerInfo`) so you don't need to hand-code `server.network_ports[0]` and hope.

    ```csharp theme={null}
    // On Lobby (null-safe; returns null / 0 if no server or no match)
    string        host           = lobby.GetHost("game_udp");
    int           externalPort   = lobby.GetExternalPort("game_udp");
    GameServerPort port          = lobby.FindPort("game_udp");
    bool          ok             = lobby.TryGetPort("game_udp", out var p);
    ```

    The full `GameServerPort` shape matches the servers API: `name`, `internal_port` (what your game binds to inside the container), `external_port` (what clients connect to), `protocol` (`udp` / `tcp`), `host`, `tls_enabled`. Connect with `host:external_port`.

    <Tip>
      Define port names once in the dashboard under **Project Settings → Port Configuration** (e.g. `game_udp` for gameplay, `query_tcp` for server browser, `voice_tcp` for voice). Reference those names from Unity — you never need to hardcode port numbers.
    </Tip>
  </Accordion>
</AccordionGroup>


# A Beginner's Guide to Multiplayer Lobbies
Source: https://docs.playflowcloud.com/unity/lobby-overview

Learn how to create, manage, and find game lobbies for any engine.

Welcome! This guide will teach you how to add a multiplayer lobby to your game. We'll cover the basics step-by-step, assuming you've never built a lobby before.

This guide explains the concepts in a general way that applies to any game engine. For concrete code, see the engine-specific examples at the end.

## 1. What is a Lobby System?

Think of a lobby as a **virtual waiting room** where players can group up before a game starts. It's the screen where you invite your friends and wait for everyone to be ready before jumping into the action.

**Why use a lobby system?**

* **Let players connect:** It's the easiest way for players to form parties or teams.
* **Manage game setup:** Players can choose characters, teams, or game settings.
* **Launch a match:** When everyone is ready, the lobby system can automatically start a game server for the players.

Here is a simple visual of the process:

```mermaid theme={null}
graph LR
    subgraph Your Game
        P1[Player 1]
        P2[Player 2]
        P3[Player 3]
    end

    subgraph "Lobby (Waiting Room)"
        Lobby(( ))
    end

    subgraph "Game Server"
        Server["Game is On!"]
    end

    P1 --> Lobby;
    P2 --> Lobby;
    P3 --> Lobby;
    Lobby -->|Everyone is ready| Server;

    style Lobby fill:#2563EB,stroke:#fff
```

## 2. The Lobby Lifecycle

A lobby has a simple lifecycle. It starts in a `Waiting` state and moves to an `In-Game` state when the match begins.

```mermaid theme={null}
graph TD
    A[Waiting] -->|"Host starts the match"| B(In-Game);
    B -->|"Host ends the match"| A;
```

* **Waiting**: The default state. Players can join, leave, and prepare for the game.
* **In-Game**: The match is active. The lobby is usually locked, and a game server is running.

## 3. Managing Your Lobby

Here are the basic actions you can perform to manage a lobby.

### Creating a Lobby

One player, the **Host**, creates the lobby. To do this, you'll call a `create_lobby` function from the SDK. You typically need to provide a few key pieces of information:

* **Name**: A public name for the lobby, like "My Awesome Game".
* **Region**: Required — the geographic region the lobby (and any match server it launches) lives in, like `us-east` or `eu-west`.
* **Max Players**: The total number of players allowed (e.g., 4).
* **Privacy**: Whether the lobby is `public` (discoverable by anyone) or `private` (requires an invite code).

### Joining a Lobby

Other players can join a public lobby using its unique ID or a private lobby using its secret invite code.

### Leaving & Deleting

Any player can leave a lobby. If the host leaves, another player is automatically promoted to be the new host. A lobby is deleted automatically when its last player leaves — there is no separate "delete for everyone" client action for the host.

## 4. Storing Information

You can store two kinds of information: data about the lobby itself, and data for each specific player.

### Lobby Data (Public Info)

This is information about the game session that applies to everyone, like the selected map or game mode. The host is usually the one who sets this data by calling an `update_lobby` function.

### Player Data (Per-Player Info)

This is information specific to each player, like their ready status, character, or team. Each player can only update **their own** data — there is no way to write another player's state. To coordinate teams or match settings, the host uses the lobby-level settings (see Lobby Data above), and players set their own team or role on themselves.

## 5. Finding a Game

### The Lobby List

You can get a list of all public lobbies to create a server browser. It's best to apply filters to this search, such as only showing lobbies for a specific game mode or lobbies that are not full.

### Matchmaking

Instead of having players pick from a list, you can use matchmaking to automatically find a good game for them. The flow is simple:

1. A player creates a lobby (even for just themself).
2. They set their matchmaking data (like skill level or region) using the `update_player_data` function.
3. They call a `find_match` function.
4. The system then finds other lobbies that are also searching and have similar data.

```mermaid theme={null}
sequenceDiagram
    participant Player
    participant YourGame as Your Game
    participant PlayFlow

    Player->>YourGame: Clicks "Find Ranked Match"
    YourGame->>PlayFlow: Create Lobby
    YourGame->>PlayFlow: Update Player Data (e.g., skill: 1200)
    YourGame->>PlayFlow: Find Match
    PlayFlow-->>YourGame: Event: Match Found!
    note right of YourGame: Now, start the game!
```

## 6. Handling Updates with Events

Lobbies change constantly. Your game needs to react when players join, leave, or change their status. The SDK uses **events** (also known as callbacks or listeners) to tell your game when something important happens.

**Key Events to Listen For:**

* `OnLobbyUpdated`: Fires when any data in the lobby changes. Use this to refresh your UI.
* `OnPlayerJoined`: Fires when a new player enters the lobby.
* `OnPlayerLeft`: Fires when a player leaves.
* `OnMatchStarted`: Fires when the host starts the match and the game server is ready with connection info.

## 7. Tips and Best Practices

* **Securing Private Lobbies**: When you create a private lobby, it's automatically hidden from the public lobby list. The only way to join is with the secret `invite_code` that is generated. Share this code among friends.
* **Handling Many Lobbies**: If your game is popular, always use filters when searching for lobbies. Fetching a list of thousands of lobbies can be slow. Filter by region or game mode first.

## Next Steps

Now that you understand the core concepts, you're ready to start building. Dive into our engine-specific guides for code examples and step-by-step instructions.

<CardGroup>
  <Card title="Unity Quick Start" icon="rocket" href="/unity/lobbies">
    Implement your first lobby in Unity with a 5-minute guide.
  </Card>

  <Card title="Matchmaking Guide" icon="swords" href="/unity/matchmaking">
    Add skill-based matchmaking to your Unity game.
  </Card>
</CardGroup>


# Matchmaking Guide
Source: https://docs.playflowcloud.com/unity/matchmaking

Integrate traditional and role-based matchmaking with the lobby system.

PlayFlow's matchmaking system supports both **traditional symmetric matchmaking** (like Fortnite, Counter-Strike) and **advanced role-based asymmetric matchmaking** (like League of Legends, Overwatch, Dead by Daylight). The system seamlessly integrates with lobbies to provide automated matching based on skill, region, roles, and custom criteria.

## Prerequisites

Matchmaking always runs on top of the lobby and player-identity systems, so before starting a search you need:

* **A lobby.** Every match request comes from a lobby (even a solo one). See the [Lobby Quick Start](/unity/lobbies) to create and manage lobbies.
* **A player identity.** Lobby and matchmaking calls require an authenticated player. With a client key and an auth provider configured, pass a valid player token; otherwise a trusted player id is used. See [Player Authentication](/guides/player-authentication).
* **A matchmaking mode.** Configure at least one mode in your lobby configuration (below) whose name you pass to `FindMatch`.

## Matchmaking Types

### Traditional/Symmetric Matchmaking

Used for games where all players have equal capabilities and teams are symmetrical. Examples include:

* **Battle Royale** (Fortnite, PUBG): 100 players, last one standing
* **Team Deathmatch** (Counter-Strike, Valorant): 5v5 competitive matches
* **Arena Duels**: 1v1 or 2v2 ranked matches
* **Large-scale Battles**: 32v32 or 64v64 team warfare

### Role-Based/Asymmetric Matchmaking

Used for games where players have distinct roles with unique abilities and responsibilities. Examples include:

* **MOBA Games** (League of Legends, Dota 2): Support, Tank, DPS roles with team composition requirements
* **Hero Shooters** (Overwatch, Paladins): Role queue with tanks, healers, and damage dealers
* **Asymmetric Horror** (Dead by Daylight): 4 survivors vs 1 killer
* **Social Deduction** (Among Us, Werewolf): Different roles with hidden information

## How Matchmaking Works

In PlayFlow, matchmaking always works through lobbies:

1. **A player creates a lobby** (for just themself, or for a party of friends)
2. Players set their matchmaking data (skill, region, roles)
3. The **lobby host starts the search**
4. The system finds compatible lobbies based on your configuration
5. When a match is found, a game server automatically starts for all players

This lobby-based approach naturally supports party matchmaking (friends queuing together) while maintaining team cohesion.

## Dashboard Configuration

Before writing code, you must configure your matchmaking rules in the PlayFlow Dashboard.

1. Go to your project's **Configuration** → **Lobbies** tab
2. Create or edit a lobby configuration
3. Click the **Matchmaking** tab
4. Add and configure matchmaking modes

### Traditional Configuration Examples

<Tabs>
  <Tab title="5v5 Competitive">
    For tactical shooters like Counter-Strike or Valorant:

    ```json theme={null}
    {
      "Competitive5v5": {
        "teams": 2,
        "playersPerTeam": 5,
        "timeout": 120,
        "backfill": { "enabled": false },
        "rules": [
          {
            "type": "difference",
            "field": "mmr",
            "maxDifference": 200
          },
          {
            "type": "region"
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="Battle Royale">
    For games like Fortnite or PUBG:

    ```json theme={null}
    {
      "BattleRoyaleSolo": {
        "teams": 100,
        "playersPerTeam": 1,
        "minPlayersPerTeam": 1,
        "timeout": 60,
        "backfill": { "enabled": true },
        "rules": [
          {
            "type": "difference",
            "field": "mmr",
            "maxDifference": 500
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="Team Deathmatch">
    For casual multiplayer modes:

    ```json theme={null}
    {
      "TeamDeathmatch": {
        "teams": 2,
        "playersPerTeam": 8,
        "minPlayersPerTeam": 4,
        "timeout": 45,
        "backfill": { "enabled": true },
        "maxPartySize": 4,
        "rules": [
          {
            "type": "difference",
            "field": "mmr",
            "maxDifference": 300
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="1v1 Ranked">
    For fighting games or RTS duels:

    ```json theme={null}
    {
      "RankedDuel": {
        "teams": 2,
        "playersPerTeam": 1,
        "timeout": 180,
        "backfill": { "enabled": false },
        "rules": [
          {
            "type": "difference",
            "field": "mmr",
            "maxDifference": 100
          },
          {
            "type": "equals",
            "field": "gameMode"
          }
        ]
      }
    }
    ```
  </Tab>
</Tabs>

### Role-Based Configuration Examples

<Tabs>
  <Tab title="MOBA (LoL/Dota)">
    For games like League of Legends with strict role requirements:

    ```json theme={null}
    {
      "RankedRoleQueue": {
        "teams": 2,
        "playersPerTeam": 5,
        "minPlayersPerTeam": 5,
        "maxPartySize": 2,
        "excludedFromQueue": ["Spectator", "Coach"],
        "teamComposition": {
          "team1": {
            "top": 1,
            "jungle": 1,
            "mid": 1,
            "adc": 1,
            "support": 1
          },
          "team2": {
            "top": 1,
            "jungle": 1,
            "mid": 1,
            "adc": 1,
            "support": 1
          }
        },
        "timeout": 90,
        "rules": [
          {
            "type": "difference",
            "field": "mmr",
            "maxDifference": 150
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="Hero Shooter (Overwatch)">
    For role-locked competitive modes:

    ```json theme={null}
    {
      "CompetitiveRoleQueue": {
        "teams": 2,
        "playersPerTeam": 6,
        "minPlayersPerTeam": 6,
        "maxPartySize": 3,
        "excludedFromQueue": ["Spectator"],
        "teamComposition": {
          "team1": {
            "tank": 2,
            "damage": 2,
            "support": 2
          },
          "team2": {
            "tank": 2,
            "damage": 2,
            "support": 2
          }
        },
        "timeout": 120,
        "backfill": { "enabled": true },
        "rules": [
          {
            "type": "difference",
            "field": "sr",
            "maxDifference": 250
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="Asymmetric Horror">
    For games like Dead by Daylight:

    ```json theme={null}
    {
      "AsymmetricHorror": {
        "teams": 2,
        "playersPerTeam": 4,
        "minPlayersPerTeam": 1,
        "maxPartySize": 4,
        "excludedFromQueue": ["Spectator"],
        "teamComposition": {
          "survivors": {
            "survivor": 4
          },
          "killer": {
            "killer": 1
          }
        },
        "timeout": 60,
        "backfill": { "enabled": false },
        "rules": [
          {
            "type": "difference",
            "field": "rank",
            "maxDifference": 6
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="Social Deduction">
    For games like Among Us or Town of Salem:

    ```json theme={null}
    {
      "SocialDeduction": {
        "teams": 2,
        "playersPerTeam": 8,
        "minPlayersPerTeam": 6,
        "maxPartySize": 3,
        "excludedFromQueue": ["Spectator", "Host"],
        "teamComposition": {
          "crew": {
            "crewmate": 6,
            "detective": 1,
            "engineer": 1
          },
          "impostors": {
            "impostor": 2
          }
        },
        "timeout": 45,
        "backfill": { "enabled": true },
        "rules": [
          {
            "type": "difference",
            "field": "trustScore",
            "maxDifference": 200
          }
        ]
      }
    }
    ```
  </Tab>

  <Tab title="MMO Dungeon">
    For dungeon finder systems:

    ```json theme={null}
    {
      "DungeonFinder": {
        "teams": 1,
        "playersPerTeam": 5,
        "minPlayersPerTeam": 5,
        "maxPartySize": 5,
        "excludedFromQueue": ["Offline"],
        "teamComposition": {
          "party": {
            "tank": 1,
            "healer": 1,
            "dps": 3
          }
        },
        "timeout": 300,
        "backfill": { "enabled": true },
        "rules": [
          {
            "type": "difference",
            "field": "itemLevel",
            "maxDifference": 40
          }
        ]
      }
    }
    ```
  </Tab>
</Tabs>

### Backfill Configuration

Backfill routes newly-queued players into an already-running match that still has open slots, instead of always spinning up a fresh server. Configure it with the `backfill` object on a mode:

```json theme={null}
{
  "TeamDeathmatch": {
    "teams": 2,
    "playersPerTeam": 8,
    "minPlayersPerTeam": 4,
    "timeout": 45,
    "backfill": {
      "enabled": true,
      "windowSeconds": 300,
      "closeWhenFull": true,
      "skill": { "field": "mmr", "maxDifference": 300 }
    }
  }
}
```

| Field           | Default | Purpose                                                                                                     |
| --------------- | ------- | ----------------------------------------------------------------------------------------------------------- |
| `enabled`       | `false` | Master switch. Omit or set `false` to disable backfill.                                                     |
| `windowSeconds` | `300`   | How long after a match forms it stays open to joiners.                                                      |
| `closeWhenFull` | `true`  | Stop accepting backfill once the match reaches capacity.                                                    |
| `skill`         | none    | Optional skill gate — a joining lobby's average `field` must be within `maxDifference` of the match's band. |

<Info>
  `allowBackfill: true` is still accepted as a deprecated alias for `backfill: { "enabled": true }`, but prefer the object form so you can tune the window and skill gate.
</Info>

## Implementation Guide

Here are the steps to implement matchmaking in your game.

### Step 1: Set Player Matchmaking Data

Players must set their matchmaking attributes before searching. This includes MMR, regions, and roles (for role-based modes).

<Tabs>
  <Tab title="Unity">
    #### Traditional Matchmaking Data

    For traditional modes, set MMR and acceptable regions:

    ```csharp theme={null}
    using System.Collections.Generic;
    using PlayFlow;
    using UnityEngine;

    public class TraditionalMatchmaking : MonoBehaviour
    {
        public void SetTraditionalMatchmakingData(int playerMMR)
        {
            var matchmakingData = new Dictionary<string, object>
            {
                { "mmr", playerMMR },
                { "regions", new List<string> { "us-west", "us-east", "eu-west" } }
            };

            PlayFlowLobbyManagerV2.Instance.UpdatePlayerState(matchmakingData,
                onSuccess: (lobby) => {
                    Debug.Log("Player matchmaking data has been set.");
                },
                onError: (error) => {
                    Debug.LogError($"Could not set matchmaking data: {error}");
                }
            );
        }
    }
    ```

    #### Role-Based Matchmaking Data

    For role-based modes, also specify your role preferences:

    ```csharp theme={null}
    public class RoleBasedMatchmaking : MonoBehaviour
    {
        // Single specific role (MOBA player who only plays one lane)
        public void SetSpecificRole(string role, int playerMMR)
        {
            var matchmakingData = new Dictionary<string, object>
            {
                { "role", role }, // e.g., "jungle", "mid", "support"
                { "mmr", playerMMR },
                { "regions", new List<string> { "us-east", "us-west" } }
            };

            PlayFlowLobbyManagerV2.Instance.UpdatePlayerState(matchmakingData);
        }

        // Priority array of roles (flexible fill player)
        public void SetFlexibleRoles(int playerMMR)
        {
            var matchmakingData = new Dictionary<string, object>
            {
                { "role", new List<string> { "support", "adc", "mid" } }, // Preference order
                { "mmr", playerMMR },
                { "regions", new List<string> { "us-east", "eu-west" } }
            };

            PlayFlowLobbyManagerV2.Instance.UpdatePlayerState(matchmakingData);
        }

        // Spectator role (excluded from matchmaking)
        public void SetSpectatorRole()
        {
            var matchmakingData = new Dictionary<string, object>
            {
                { "role", "Spectator" }, // Will be excluded from team requirements
                { "regions", new List<string> { "us-east" } }
            };

            PlayFlowLobbyManagerV2.Instance.UpdatePlayerState(matchmakingData);
        }
    }
    ```
  </Tab>

  <Tab title="Unreal Engine">
    Coming soon...
  </Tab>

  <Tab title="Godot">
    Coming soon...
  </Tab>
</Tabs>

### Step 2: Start the Search

Once the player's data is set, the lobby host can start the search by calling `FindMatch`. The `mode` parameter must match the name of the matchmaking mode you created in the dashboard.

<Tabs>
  <Tab title="Unity">
    ```csharp theme={null}
    public class MatchmakingStarter : MonoBehaviour
    {
        // Traditional matchmaking (Competitive5v5, Duels, BattleRoyale, etc.)
        public void StartTraditionalSearch(string mode = "Competitive5v5")
        {
            var manager = PlayFlowLobbyManagerV2.Instance;

            if (!manager.IsInLobby || !manager.IsHost)
            {
                Debug.LogWarning("Must be the host of a lobby to start matchmaking.");
                return;
            }

            manager.FindMatch(mode,
                onSuccess: (lobby) => {
                    Debug.Log($"Successfully entered the '{lobby.matchmaking.mode}' queue.");
                    // Update your UI to show a "searching..." state
                },
                onError: (error) => {
                    Debug.LogError($"Failed to start matchmaking: {error}");
                }
            );
        }

        // Role-based matchmaking (RankedRoleQueue, AsymmetricHorror, etc.)
        public void StartRoleBasedSearch(string mode = "RankedRoleQueue")
        {
            var manager = PlayFlowLobbyManagerV2.Instance;

            if (!manager.IsInLobby || !manager.IsHost)
            {
                Debug.LogWarning("Must be the host of a lobby to start matchmaking.");
                return;
            }

            // Ensure all players have set their roles
            var currentLobby = manager.CurrentLobby;
            bool allPlayersHaveRoles = true;

            foreach (var playerId in currentLobby.players)
            {
                if (currentLobby.lobbyStateRealTime.TryGetValue(playerId, out var playerState))
                {
                    if (!playerState.ContainsKey("role"))
                    {
                        Debug.LogWarning($"Player {playerId} has not set their role!");
                        allPlayersHaveRoles = false;
                    }
                }
            }

            if (!allPlayersHaveRoles)
            {
                Debug.LogError("All players must set their role before matchmaking!");
                return;
            }

            manager.FindMatch(mode,
                onSuccess: (lobby) => {
                    Debug.Log($"Entered role-based queue: {lobby.matchmaking.mode}");
                    // Show searching UI with role information
                },
                onError: (error) => {
                    Debug.LogError($"Failed to start role-based matchmaking: {error}");
                }
            );
        }
    }
    ```
  </Tab>

  <Tab title="Unreal Engine">
    Coming soon...
  </Tab>

  <Tab title="Godot">
    Coming soon...
  </Tab>
</Tabs>

### Step 3: Handle Matchmaking Events

After starting the search, subscribe to events to drive your UI.

| Event                         | When it fires                                                |
| ----------------------------- | ------------------------------------------------------------ |
| `OnMatchmakingStarted`        | Lobby entered the queue (status → `in_queue`)                |
| `OnQueueStats`                | Every \~10s while queueing — live wait-time telemetry        |
| `OnMatchAwaitingConfirmation` | Match proposal pending (only if `matchConfirmation.enabled`) |
| `OnMatchConfirmed`            | This lobby accepted; waiting on others                       |
| `OnMatchDeclined`             | Someone declined or timed out — back to `waiting`            |
| `OnMatchFound`                | Match committed, server launching                            |
| `OnMatchRunning`              | Server is ready to accept connections                        |
| `OnMatchServerDetailsReady`   | Full port list (for multi-port games)                        |
| `OnMatchmakingCancelled`      | Host called `CancelMatchmaking()`                            |
| `OnMatchmakingTimeout`        | Queue timed out without finding a match                      |

<Tabs>
  <Tab title="Unity">
    ```csharp theme={null}
    void Start()
    {
        var events = PlayFlowLobbyManagerV2.Instance.Events;

        events.OnMatchmakingStarted.AddListener(HandleMatchmakingStarted);
        events.OnQueueStats.AddListener(HandleQueueStats);
        events.OnMatchFound.AddListener(HandleMatchFound);
        events.OnMatchRunning.AddListener(HandleMatchRunning);
        events.OnMatchServerDetailsReady.AddListener(HandleServerDetailsReady);
        events.OnMatchmakingCancelled.AddListener(HandleMatchmakingCancelled);
        events.OnMatchmakingTimeout.AddListener(HandleMatchmakingTimeout);
    }

    private void HandleMatchmakingStarted(Lobby lobby)
    {
        Debug.Log($"In queue for mode: {lobby.matchmaking.mode}");
        // Show "Searching for match…" UI
    }

    private void HandleQueueStats(QueueStats stats)
    {
        // Update your UI: "42 players searching · ~12s avg wait"
        Debug.Log($"{stats.playersSearching} searching, {stats.avgWaitSeconds:F0}s avg wait");
    }

    private void HandleMatchFound(Lobby lobby)
    {
        Debug.Log("Match committed! Server launching…");
        // Update UI to "Connecting…"
    }

    private void HandleMatchRunning(ConnectionInfo connectionInfo)
    {
        // Quick-access for single-port games
        MyNetworkManager.Connect(connectionInfo.Ip, connectionInfo.Port);
    }

    private void HandleServerDetailsReady(List<PortMappingInfo> portMappings)
    {
        // Preferred: look up by the port name you defined in the dashboard
        var lobby = PlayFlowLobbyManagerV2.Instance.CurrentLobby;
        if (lobby.TryGetPort("game_udp", out var port))
        {
            Debug.Log($"Connecting to {port.host}:{port.external_port}");
            MyNetworkManager.Connect(port.host, port.external_port);
        }
    }

    private void HandleMatchmakingCancelled(Lobby lobby) { /* back to lobby */ }
    private void HandleMatchmakingTimeout(Lobby lobby)   { /* show "no match found" */ }
    ```
  </Tab>

  <Tab title="Unreal Engine">
    Coming soon...
  </Tab>

  <Tab title="Godot">
    Coming soon...
  </Tab>
</Tabs>

### Step 3.5: CS2-Style "Accept Match" flow (optional)

If the matchmaking mode has `matchConfirmation.enabled: true` in the dashboard, matches pause at the `match_found` status waiting for every lobby to explicitly accept. Opt in by subscribing to three extra events and exposing accept/decline buttons.

```csharp theme={null}
void Start()
{
    var events = PlayFlowLobbyManagerV2.Instance.Events;
    events.OnMatchAwaitingConfirmation.AddListener(HandleAwaitingConfirmation);
    events.OnMatchConfirmed.AddListener(_  => Debug.Log("You accepted. Waiting on other players…"));
    events.OnMatchDeclined.AddListener(_   => Debug.Log("Match cancelled — re-queue when ready."));
}

void HandleAwaitingConfirmation(Lobby lobby)
{
    // Show your "Accept Match" dialog
    var deadlineIso = lobby.matchmaking.confirmation.deadline;
    Debug.Log($"Match found — accept before {deadlineIso}");
}

public void OnAcceptClicked()  => PlayFlowLobbyManagerV2.Instance.ConfirmMatch();
public void OnDeclineClicked() => PlayFlowLobbyManagerV2.Instance.DeclineMatch();
```

If **any** player declines or the deadline expires, every participating lobby returns to `waiting` (not back to `in_queue`) — players re-queue manually when ready. This matches how CS2 and League of Legends handle match acceptance.

### Step 4: Cancel the Search

The host can cancel the matchmaking search at any time by calling `CancelMatchmaking`.

<Tabs>
  <Tab title="Unity">
    ```csharp theme={null}
    public void CancelSearch()
    {
        var manager = PlayFlowLobbyManagerV2.Instance;

        if (!manager.IsHost || manager.CurrentLobby?.status != "in_queue")
        {
            return; // Can only cancel if you are the host and in the queue
        }

        manager.CancelMatchmaking(
            onSuccess: (lobby) => {
                Debug.Log("Successfully cancelled matchmaking.");
            },
            onError: (error) => {
                Debug.LogError($"Failed to cancel matchmaking: {error}");
            }
        );
    }
    ```
  </Tab>

  <Tab title="Unreal Engine">
    Coming soon...
  </Tab>

  <Tab title="Godot">
    Coming soon...
  </Tab>
</Tabs>

## Advanced Features

### Role Assignment Algorithm

The role-based matchmaking system uses an intelligent priority-based algorithm to assign players to roles. Roles can be provided as either a single string or a string array for flexibility.

<Info>
  **Key Principle**: Players with fewer role options get priority assignment to ensure everyone gets a suitable role. This is NOT random - it's deterministic and fair.
</Info>

#### How Priority Assignment Works

**1. Specificity First**
Players with fewer role options are assigned before flexible players:

```csharp theme={null}
// Assignment priority (highest to lowest):
Player A: ["tank"]                    // 1 option - HIGHEST PRIORITY
Player B: ["tank", "healer"]          // 2 options - medium priority
Player C: ["tank", "healer", "dps"]   // 3 options - lowest priority

// Player A gets first choice, then B, then C
```

**2. Preference Order Matters**
When assigned, the system tries roles left-to-right in your array:

```csharp theme={null}
// Player's preference array:
["support", "adc", "mid"]

// System tries:
// 1st: Can they be support? → If yes, assigned!
// 2nd: If not, can they be adc? → If yes, assigned!
// 3rd: If not, can they be mid? → If yes, assigned!
```

**3. Tie-Breaking**
When players have identical preferences, first-come-first-served applies:

```csharp theme={null}
// Both want the same roles:
Player1: ["support", "adc"]  // Joined lobby first
Player2: ["support", "adc"]  // Joined lobby second

// Result:
Player1 → Gets "support" (first preference)
Player2 → Gets "adc" (support taken, gets second choice)
```

#### Real-World Example

For a MOBA team needing specific roles:

```csharp theme={null}
// Team needs: 1 top, 1 jungle, 1 mid, 1 adc, 1 support

// Players with their preferences:
Player1: ["mid", "top", "support"]     // Flexible
Player2: ["jungle"]                    // One-trick (gets priority!)
Player3: ["support", "adc"]            // Support main
Player4: ["mid"]                       // Mid only
Player5: ["top", "mid", "jungle"]      // Fill player

// Assignment result:
Player2 → jungle (most specific, only wants jungle)
Player4 → mid (most specific for mid)
Player3 → support (first preference available)
Player5 → top (mid/jungle taken, gets top)
Player1 → adc (forced to fill, but match succeeds!)
```

#### Setting Role Preferences in Code

```csharp theme={null}
public class RolePreferenceManager : MonoBehaviour
{
    // Specific player - highest priority but risky
    public void SetOneRoleOnly(string role)
    {
        var data = new Dictionary<string, object> {
            { "role", role }  // Single string
        };
        PlayFlowLobbyManagerV2.Instance.UpdatePlayerState(data);
    }

    // Flexible player - lower priority but guarantees match
    public void SetMultipleRoles(List<string> roles)
    {
        var data = new Dictionary<string, object> {
            { "role", roles }  // String array in preference order
        };
        PlayFlowLobbyManagerV2.Instance.UpdatePlayerState(data);
    }

    // Ultra-flexible - can play anything
    public void SetFillPlayer()
    {
        var allRoles = new List<string> {
            "top", "jungle", "mid", "adc", "support"
        };
        var data = new Dictionary<string, object> {
            { "role", allRoles }
        };
        PlayFlowLobbyManagerV2.Instance.UpdatePlayerState(data);
    }
}
```

<Warning>
  **Edge Case**: If too many players are inflexible (single role only) and want the same role, the match will fail. Always encourage some flexibility in your player base!
</Warning>

### Spectator Support

Spectators are excluded from team requirements but still receive game server access for observation.

```csharp theme={null}
public class SpectatorManager : MonoBehaviour
{
    public void JoinAsSpectator()
    {
        // Set spectator role
        var spectatorData = new Dictionary<string, object>
        {
            { "role", "Spectator" },
            { "regions", new List<string> { "us-east" } }
        };

        PlayFlowLobbyManagerV2.Instance.UpdatePlayerState(spectatorData);
    }

    private void OnMatchFound(Lobby lobby)
    {
        // Spectators still get notified and can connect
        if (IsSpectator())
        {
            Debug.Log("Joined match as spectator!");
            // Connect to server in spectator mode
        }
    }
}
```

### Regional Matchmaking

Players can specify multiple acceptable regions. The system finds matches where players have overlapping regions.

```csharp theme={null}
// Specify regions in order of preference
var regionList = new List<string> { "us-east", "us-west", "eu-west" };
UpdatePlayerState(new Dictionary<string, object> {
    { "regions", regionList }
});
```

### Party Support

The lobby-based approach naturally supports parties. Friends can join the same lobby and queue together:

```csharp theme={null}
public class PartyManager : MonoBehaviour
{
    public void CreatePartyLobby()
    {
        // Create lobby for your party
        PlayFlowLobbyManagerV2.Instance.CreateLobby(
            name: "My Party",
            maxPlayers: 4,  // Your party size
            isPrivate: true,
            onSuccess: (lobby) => {
                Debug.Log($"Party lobby created! Share code: {lobby.code}");
            }
        );
    }

    public void QueueWithParty(string mode)
    {
        // Everyone in the lobby queues together
        PlayFlowLobbyManagerV2.Instance.FindMatch(mode);
    }
}
```

## Troubleshooting

### Common Issues

<AccordionGroup>
  <Accordion title="Players not matching despite being in queue">
    * Verify all players have set required matchmaking data (MMR, regions, roles)
    * Check that players have overlapping regions in their `regions` field
    * For role-based modes, ensure you have the exact roles needed for team composition
    * Check dashboard configuration timeout settings
  </Accordion>

  <Accordion title="Spectators being counted in matchmaking">
    Ensure spectator roles are listed in the `excludedFromQueue` array in your dashboard configuration:

    ```json theme={null}
    "excludedFromQueue": ["Spectator", "Observer"]
    ```
  </Accordion>

  <Accordion title="Role assignment not working correctly">
    * Players with single specific roles are prioritized over flexible players
    * Ensure role names match exactly with dashboard configuration
    * Check that total players match team requirements
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup>
  <Card title="Lobby Quick Start" icon="rocket" href="/unity/lobbies">
    Review the basics of creating and managing lobbies.
  </Card>

  <Card title="Lobby Events Reference" icon="radio" href="/unity/lobby-events">
    See all events for building responsive matchmaking UI.
  </Card>

  <Card title="Game Servers" icon="server" href="/unity/game-servers">
    Learn about server lifecycle and configuration.
  </Card>
</CardGroup>


# Overview
Source: https://docs.playflowcloud.com/unity/overview

Understand the fundamentals of dedicated game servers and how PlayFlow simplifies hosting and management.

## What is a Dedicated Game Server?

In multiplayer gaming, a **dedicated game server** is an authoritative, standalone server that runs the game logic. Unlike player-hosted games where one player's machine acts as the server (peer-to-peer), a dedicated server runs in a professional data center.

This model is the standard for most commercial multiplayer games because it provides a fair, stable, and secure environment for all players.

**Key Benefits:**

* **Authority & Security**: The server is the ultimate source of truth, preventing common cheats like aimbots or speed hacks that manipulate the game on a player's local machine.
* **Performance & Stability**: Hosted on powerful hardware with high-speed internet, dedicated servers provide a low-latency, reliable connection for all players, unaffected by any single player's network issues.
* **Persistence**: The server can run 24/7, allowing for persistent game worlds that exist even when players are offline.
* **Scalability**: You can spin up as many server instances as you need to handle a growing player base.

```mermaid theme={null}
graph LR
    subgraph Players
        pA[Player A]
        pB[Player B]
        pC[Player C]
    end

    subgraph "PlayFlow Cloud"
        ds(Dedicated Server)
    end

    pA -- TCP/UDP --> ds
    pB -- TCP/UDP --> ds
    pC -- TCP/UDP --> ds
```

## How PlayFlow Manages Game Servers

PlayFlow is a platform designed to completely remove the complexity of managing your own dedicated server infrastructure. We handle the hardware, networking, and scaling, so you can focus on building your game.

The lifecycle of a game server on PlayFlow is simple:

<Steps>
  <Step title="1. Upload Your Build">
    You package your game's server executable and assets into a `.zip` file and upload it to PlayFlow. For Unity developers, our plugin can do this for you automatically.
  </Step>

  <Step title="2. Configure Your Server">
    In the PlayFlow dashboard, you define the network settings for your server, such as which internal ports your server listens on. Each port is either TCP or UDP (a toggle), with a separate TLS checkbox for TCP ports. For example, your server might listen on port `7777` for gameplay traffic. This is the internal port your server binds to — the public port that clients connect on is allocated separately by PlayFlow.
  </Step>

  <Step title="3. Deploy an Instance">
    You can launch a server instance from the dashboard or via an API call. You choose the geographic region (required) and the server size, and PlayFlow handles the rest.
  </Step>

  <Step title="4. Connect Players">
    Each running server returns a `network_ports` array in its API response. Read the `host` and `external_port` values from that array to build your client's connection string — never hardcode a fixed IP or port, since the public port is allocated per instance and differs from your internal listen port.
  </Step>
</Steps>

## PlayFlow Networking Architecture

PlayFlow simplifies networking so you don't have to worry about port forwarding or firewalls. Your server listens on its internal ports, and PlayFlow gives your clients a reachable `host` and `external_port` for each one. How that address is served depends on the protocol:

* **UDP** traffic is routed through PlayFlow's proxy fleet on a dedicated proxy IPv4. Clients connect to the proxy, which forwards traffic to your server on its internal port.
* **TCP** traffic is served directly from your server machine on a shared PlayFlow host (`relay.computeflow.cloud`), with optional Fly-managed TLS when you enable the TLS checkbox.

In both cases the public port is allocated by PlayFlow and differs from your internal listen port, so always read `host` and `external_port` from the server's `network_ports` array rather than assuming a static address.

Here’s how it works:

1. When you deploy a server, PlayFlow returns a `host` and `external_port` for each configured port — a dedicated proxy IP for UDP, or the shared `relay.computeflow.cloud` host for TCP.
2. Your game clients connect using the returned `host` and `external_port`.
3. For UDP, PlayFlow's proxy forwards the traffic to your game server on its internal port. For TCP, clients reach the server machine directly on its allocated port.

```mermaid theme={null}
graph LR
    subgraph "Internet"
        client["Game Client"]
    end

    subgraph "PlayFlow Global Network"
        proxy("Global Proxy")
    end

    subgraph "PlayFlow Data Center"
        server("Game Server<br/>Listens on internal port")
    end

    client -- "Connects to host:external_port" --> proxy
    proxy -- "Forwards UDP traffic" --> server
```

This architecture provides several advantages:

* **Simplicity**: Your server code doesn't need to know its public address — it just listens on its internal port.
* **Managed connectivity**: For UDP, the proxy fronts your server so it isn't addressed directly; for TCP, connections reach the server machine directly on a shared PlayFlow host with optional managed TLS.
* **Scalability**: The proxy fleet handles UDP traffic and scales automatically to distribute load.

## Next Steps

Now that you understand the basics, you're ready to get started.

<CardGroup>
  <Card title="Quick Start Guide" icon="rocket" href="/quickstart">
    Follow our step-by-step guide to deploy your very first game server.
  </Card>

  <Card title="Game Servers API" icon="code" href="/unity/game-servers">
    Learn how to programmatically start, stop, and list servers from your game client or backend.
  </Card>
</CardGroup>


# Programmatic Access
Source: https://docs.playflowcloud.com/unity/programmatic-access

Learn how to start, stop, and manage your game servers programmatically using the PlayFlow API.

You can control your game servers from your game client, a custom backend service, or any other application by using the PlayFlow API.

We provide two primary ways to interact with the API:

* **Unity SDK**: A convenient C# wrapper for developers using Unity.
* **REST API**: For all other game engines and custom backends.

<CardGroup>
  <Card title="REST API Reference" icon="code" href="/fundamentals/api">
    Base URL, authentication, and curl examples for every endpoint.
  </Card>

  <Card title="OpenAPI Endpoints" icon="book-open" href="/api-reference/introduction">
    The interactive, auto-generated reference for schemas and responses.
  </Card>
</CardGroup>

## Prerequisites

Before you start, make sure you have:

* The PlayFlow Unity SDK installed. See the [installation guide](/guides/installation).
* A PlayFlow project with at least one build uploaded.
* An API key from the [PlayFlow Dashboard](https://app.playflowcloud.com) under **Project Settings**. PlayFlow issues two key types:
  * **Server key** (`pf_*`) — full access. Keep it server-side (backend, CI/CD). Required for actions like deleting builds or updating project settings.
  * **Client key** (`pfclient_*`) — safe to ship inside a game build.

<Warning>
  Never embed a server key (`pf_*`) in a client or WebGL build. Use a client key (`pfclient_*`) for anything that ships to players.
</Warning>

## Unity SDK Examples

The following examples use the `PlayflowServerApiClient` class from the SDK.

### Initialization

First, you need to initialize the client with your PlayFlow API key.

```csharp theme={null}
using PlayFlow.SDK.Servers;

// Your API key from the PlayFlow dashboard
string playflowApiKey = "YOUR_API_KEY_HERE"; 

private PlayflowServerApiClient _apiClient;

void Start()
{
    _apiClient = new PlayflowServerApiClient(playflowApiKey);
}
```

### Starting a Game Server

To start a new server, you provide a configuration that specifies the server's name, region, and any custom data you want to pass to it. Both `name` and `region` are required. Select a build with `version_tag` (the build name) plus an optional `version`.

<Info>
  On the **Free** plan every server is forced to the `small` compute size and a 1-hour TTL, and you can run one active server at a time. Upgrade to **Pro** (\$20/mo) for all compute sizes, TTLs up to 24 hours, and unlimited active servers. See [plan and instance types](/fundamentals/plan-instance-types) and [regions](/fundamentals/regions).
</Info>

```csharp theme={null}
private async void StartNewServer()
{
    var serverRequest = new ServerCreateRequest
    {
        name = "MyCustomServer",
        region = "us-east",
        custom_data = new Dictionary<string, object>
        {
            { "map_name", "castle_siege" }
        }
    };

    try
    {
        ServerStartResponse response = await _apiClient.StartServerAsync(serverRequest);
        Debug.Log($"Server is starting! Instance ID: {response.instance_id}");
    }
    catch (PlayFlowApiException e)
    {
        Debug.LogError($"Failed to start server: {e.Message}");
    }
}
```

<Tip>
  To connect a game client, read the host and port from the `network_ports` array on the server object once the server is `running` — do not hardcode a port. Ports are allocated by the proxy and differ from your build's internal port. Poll the server (`GetServerAsync`) or list servers until `network_ports` is populated, then use `host` + `external_port` for each entry.
</Tip>

### Stopping a Game Server

To stop a running server, you just need its unique `instance_id`.

```csharp theme={null}
private async void StopServer(string instanceId)
{
    try
    {
        ServerStopResponse response = await _apiClient.StopServerAsync(instanceId);
        // The stop endpoint returns a confirmation message, e.g. "Server stopped successfully".
        Debug.Log($"Server stop initiated: {response.status}");
    }
    catch (PlayFlowApiException e)
    {
        Debug.LogError($"Failed to stop server: {e.Message}");
    }
}
```

### Listing Game Servers

You can get a list of all your currently running servers. This is perfect for building a server browser.

```csharp theme={null}
private async void ListAllServers()
{
    try
    {
        ServerList response = await _apiClient.ListServersAsync(includeLaunching: true);
        Debug.Log($"Found {response.total_servers} total servers.");

        foreach (var server in response.servers)
        {
            Debug.Log($"- Server: {server.name}, Status: {server.status}");
        }
    }
    catch (PlayFlowApiException e)
    {
        Debug.LogError($"Failed to list servers: {e.Message}");
    }
}
```

## REST API (any engine)

If you're not using Unity, the same operations are available over plain HTTP. The API base URL is `https://api.computeflow.cloud/api`, and every request authenticates with an `api-key` header.

Starting a server with the REST API mirrors the Unity example above:

```bash theme={null}
curl -X POST "https://api.computeflow.cloud/api/v3/servers/start" \
  -H "api-key: pf_your_server_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MyCustomServer",
    "region": "us-east",
    "version_tag": "my-build",
    "custom_data": { "map_name": "castle_siege" }
  }'
```

The response includes a snake\_case `instance_id`. Once the server is `running`, read `host` and `external_port` from each entry in `network_ports` to connect a client — never hardcode a port.

<Info>
  See the [REST API Reference](/fundamentals/api) for authentication, the full server-start parameter set, and curl examples for stopping, listing, and inspecting servers.
</Info>

## Next steps

<CardGroup>
  <Card title="Lobbies & Matchmaking" icon="users" href="/unity/lobby-overview">
    Group players and match them into sessions before launching a server.
  </Card>

  <Card title="Uploading Builds" icon="upload" href="/unity/game-servers">
    Upload and manage the server builds you launch with `version_tag`.
  </Card>

  <Card title="Plans & Instance Types" icon="server" href="/fundamentals/plan-instance-types">
    Compare compute sizes, plan limits, and TTLs.
  </Card>

  <Card title="Regions" icon="globe" href="/fundamentals/regions">
    The regions you can launch servers in.
  </Card>
</CardGroup>