# Colyseus documentation

Full text of every page at https://docs.colyseus.io. Individual pages are available as markdown
by appending `.md` to any documentation URL.

# Colyseus Multiplayer Framework

Colyseus is an open-source Node.js framework for building authoritative game servers, with real-time state synchronization, matchmaking, and simple integration into any game engine or frontend. Authentication, database services, an admin panel, and dev tooling are all included.

## Key Features

- [Rooms & Matchmaking](https://docs.colyseus.io/room.md): From a single Room definition, clients are matched into multiple room instances, with visibility flags, lobbies, and ranked queues.
- [State Synchronization](https://docs.colyseus.io/state.md): Define your state on the server; clients receive binary delta patches automatically.
- [Prediction-Ready Netcode](https://docs.colyseus.io/netcode.md): Built-in client prediction, rollback, interpolation, and lag compensation, new in 0.18.
- [Full-Stack Type Safety](https://docs.colyseus.io/sdk.md): Share your server's types with the SDK: typed messages, typed join options, typed state.
- [Any Engine](https://docs.colyseus.io/getting-started.md): Official SDKs for the Web, Unity, Godot, Defold, GameMaker, Construct, Haxe, and more.
- [Scale & Deploy Anywhere](https://docs.colyseus.io/scalability.md): Horizontal scaling across processes. Self-host for free, or use Colyseus Cloud for managed hosting.

## What does it look like?

### Create a server

Create and start a new Colyseus server using the following commands:

**Node.js**

```sh filename="Terminal: Node.js"
# Create a new Colyseus project
npm create colyseus-app@latest ./my-server

# Enter the project directory
cd my-server

# Run the server
npm start
```

**Bun**

```sh filename="Terminal: Bun"
# Create a new Colyseus project
bun create colyseus-app@latest ./my-server

# Enter the project directory
cd my-server

# Install Bun transport & Run the server
bun add @colyseus/bun-websockets
bun run src/index.ts
```

### Define your Room State

The Room state is the data structure that will be synchronized between the server and the connected clients:

**Schema Builder**

```ts filename="src/rooms/MyState.ts"
import { schema, t } from "@colyseus/schema";

export const Player = schema({
    x: t.number().default(0),
    y: t.number().default(0),
}, "Player");

export const MyState = schema({
    players: t.map(Player),
}, "MyState");
```

**Decorators**

```ts filename="src/rooms/MyState.ts"
import { Schema, MapSchema, type } from "@colyseus/schema";

export class Player extends Schema {
    @type("number") x: number = 0;
    @type("number") y: number = 0;
}

export class MyState extends Schema {
    @type({ map: Player }) players = new MapSchema<Player>();
}
```

### Create your Room code

Define the game logic and client interactions with the game state within your Room code.

```ts filename="src/rooms/MyRoom.ts"
import { Room, Client } from "colyseus";
import { MyState, Player } from "./MyState";

export class MyRoom extends Room {
    maxClients = 4;
    state = new MyState();

    messages = {
        doSomething: (client, payload) => {
            // handle client's "doSomething" message
        }
    }

    // Called when the room is created
    onCreate(options) { }

    // Called when a client joins the room
    onJoin(client: Client, options: any) {
        this.state.players.set(client.sessionId, new Player());
    }

    // Called when a client leaves the room
    onLeave(client: Client, code: number) {
        this.state.players.delete(client.sessionId);
    }

    // Called when the room is disposed
    onDispose() { }
}
```

### Expose the Room identifier

Exposing the room type allows clients to connect to the server and dynamically create instances of it.

```ts {6} filename="src/app.config.ts"
import { defineServer, defineRoom } from "colyseus";
import { MyRoom } from "./MyRoom";

const server = defineServer({
    rooms: {
        my_room: defineRoom(MyRoom),
    },
});
```

### Join the Room from the client SDK

Communication between the client and server occurs through room connections. Below are examples for each SDK showing how to join a room and listen for state changes:

**TypeScript**

```ts filename="client.ts"
import { Client, Callbacks } from "@colyseus/sdk";

async function connect() {
    const client = new Client('http://localhost:2567');
    const room = await client.joinOrCreate('my_room', {
        /* custom join options */
    });
    const callbacks = Callbacks.get(room);

    // Listen to 'player' instance additions
    callbacks.onAdd("players", (player, sessionId) => {
        console.log('Player joined:', player);
    });

    // Listen to 'player' instance removals
    callbacks.onRemove("players", (player, sessionId) => {
        console.log('Player left:', player);
    });

    // Send messages to the server
    room.send("doSomething", {/* ... */});

    return room;
}

connect();
```

**JavaScript**

```js filename="client.js"
import * as Colyseus from "@colyseus/sdk";

const client = new Colyseus.Client('http://localhost:2567');

client.joinOrCreate('my_room', {
    /* custom join options */
}).then(function(room) {
    const callbacks = Colyseus.Callbacks.get(room);

    // Listen to 'player' instance additions
    callbacks.onAdd("players", (player, sessionId) => {
        console.log('Player joined:', player);
    });

    // Listen to 'player' instance removals
    callbacks.onRemove("players", (player, sessionId) => {
        console.log('Player left:', player);
    });

    // Send messages to the server
    room.send("doSomething", {/* ... */});
});
```

**C#**

```cs filename="Client.cs"
using Colyseus;

async void Connect() {
    var client = new Client("http://localhost:2567");

    try {
        var room = await client.JoinOrCreate<MyRoomState>("my_room");
        var callbacks = Colyseus.Schema.Callbacks.Get(room);

        // Listen to 'player' instance additions
        callbacks.OnAdd(state => state.players, (sessionId, player) => {
            Debug.Log($"Player joined: {sessionId}");
        });

        // Listen to 'player' instance removals
        callbacks.OnRemove(state => state.players, (sessionId, player) => {
            Debug.Log($"Player left: {sessionId}");
        });

        // Send messages to the server
        room.Send("doSomething", new { /* ... */ });

    } catch (Exception ex) {
        Debug.Log("join error");
        Debug.Log(ex.Message);
    }
}
```

**Lua**

```lua filename="client.lua"
local ColyseusSDK = require("colyseus.sdk")

local client = ColyseusSDK.Client("http://localhost:2567")

client:join_or_create("my_room", {--[[custom join options]]}, function(err, room)
    if (err ~= nil) then
        print("join error: " .. err)
        return
    end

    local callbacks = ColyseusSDK.callbacks(room)

    -- Listen to 'player' instance additions
    callbacks:on_add("players", function(player, sessionId)
        print("Player joined:", sessionId)
    end)

    -- Listen to 'player' instance removals
    callbacks:on_remove("players", function(player, sessionId)
        print("Player left:", sessionId)
    end)

    -- Send messages to the server
    room:send("doSomething", {--[[ ... ]]})
end)
```

**Haxe**

```haxe filename="Client.hx"
import io.colyseus.Client;
import io.colyseus.serializer.schema.Callbacks;

class Main {
    static function main() {
        var client = new Client("http://localhost:2567");

        client.joinOrCreate("my_room", [], MyRoomState, function(err, room) {
            if (err != null) {
                trace("join error: " + err);
                return;
            }

            var callbacks = Callbacks.get(room);

            // Listen to 'player' instance additions
            callbacks.onAdd("players", function(player, sessionId) {
                trace("Player joined: " + sessionId);
            });

            // Listen to 'player' instance removals
            callbacks.onRemove("players", function(player, sessionId) {
                trace("Player left: " + sessionId);
            });

            // Send messages to the server
            room.send("doSomething", [/* ... */]);
        });
    }
}
```

### Explore more

Explore more about Colyseus by following the tutorials and example projects:

- [Example Projects](https://docs.colyseus.io/learn/examples.md)
- [Tutorials](https://docs.colyseus.io/learn/tutorial.md)

---
Source: https://docs.colyseus.io/


#  3rd Party Packages

> **Note:**
>
> **Contribute** - Click on the "Edit this page" link at the sidebar to add more packages.

This page contains a curated list of third-party npm modules that can help you with specific tasks on the backend, frontend, or both.

## Random Number Generator

When building procedurally generated content, use a predictable random number generator. This way, you can reproduce the same content across clients without having to synchronize the generated output.

- [ seedrandom ↗](https://www.npmjs.com/package/seedrandom)

## Entity-Component System (ECS)

An Entity-Component System is a design pattern used mostly in game development. This pattern can help you build complex systems in a more modular way.

- [ miniplex ↗](https://www.npmjs.com/package/miniplex)

## Spatial Partitioning

Spatial partitioning is a technique used in game development to optimize collision detection and other spatial queries.

Use a quadtree for 2D queries. For triangle meshes, a bounding volume hierarchy (BVH) accelerates raycasts and shape queries against level geometry. `three-mesh-bvh` requires no DOM or WebGL, so the same collision code runs on the backend and in the browser.

- [ @timohausmann/quadtree-ts ↗](https://www.npmjs.com/package/@timohausmann/quadtree-ts)
- [ three-mesh-bvh ↗](https://www.npmjs.com/package/three-mesh-bvh)

## Physics

Avoid running an entire physics engine on the backend. You can use a physics engine to calculate collisions and other physics-related computations.

### 3D Physics

- [ @perplexdotgg/bounce ↗](https://www.npmjs.com/package/@perplexdotgg/bounce)
- [ crashcat ↗](http://npmjs.com/package/crashcat)

### 2D Physics

- [ Planck.js ↗](https://www.npmjs.com/package/planck)
- [ matter.js ↗](https://www.npmjs.com/package/matter-js)
- [ kinetics.ts ↗](https://www.npmjs.com/package/kinetics.ts)
- [ grid-engine ↗](https://www.npmjs.com/package/grid-engine)

### Navigation Mesh

- [ navcat ↗](https://www.npmjs.com/package/navcat)

## Loading 3D Models in Node

An authoritative server often needs the same geometry the client renders, for collision or raycasts. The `GLTFLoader` from three.js expects browser APIs, so it does not run under Node.

- [ node-three-gltf ↗](https://www.npmjs.com/package/node-three-gltf)

Convert the model at build time instead of at server boot. Read the `.glb` once, write the triangles you need into a compact binary, then load that file from both the backend and the frontend.

## Profanity Filter

When allowing user-generated content, you may want to filter out profanity from the messages.

- [ obscenity ↗](https://npmjs.com/package/obscenity)

---
Source: https://docs.colyseus.io/3rd-party-packages


# Admin Panel

`@colyseus/admin` is a browser-based operations console for projects using [`@colyseus/database`](https://docs.colyseus.io/database.md). The panel provides user management (browse, ban, revoke sessions), CRUD over your drizzle tables, a live room inspector, and a customizable dashboard. Everything is gated by session-based login with role-based access control and an append-only audit log.

![The admin dashboard: totals, recent users and live rooms widgets](https://docs.colyseus.io/admin/dashboard.webp)

For a lightweight, no-auth dashboard intended for room and process inspection, see the [Monitoring Panel](https://docs.colyseus.io/tools/monitoring.md) instead. The admin panel is the heavier counterpart, built for production operations.

> **Warning:**
>
> `@colyseus/admin` is in **beta**: APIs may change between releases as we incorporate community feedback. Share yours on the [public roadmap](https://docs.colyseus.io/roadmap.md).

## Installation

On top of `@colyseus/core`, the panel has two peer dependencies: [`@colyseus/database`](https://docs.colyseus.io/database.md) (user store, audit log, drizzle table introspection) and [`@colyseus/auth`](https://docs.colyseus.io/auth/module.md) (JWT signing, password hashing). Install all three together:

```sh npm2yarn
npm install --save @colyseus/admin @colyseus/database @colyseus/auth
```

## Mounting

The admin panel mounts in two ways:

**Standard router (recommended)**

Spread `admin({})` into `createRouter`. The factory returns both the SPA static-serving routes and the REST API in one map:

```ts {3,10} filename="src/app.config.ts"
import { defineServer, createRouter } from "colyseus";
import { GameDatabase } from "@colyseus/database";
import { admin } from "@colyseus/admin";

export const db = new GameDatabase({ connectionString: process.env.DATABASE_URL });

export default defineServer({
    database: db,
    routes: createRouter({
        ...admin({}),
    }),
});
```

**Express middleware**

For Express-based stacks, `admin(...)` is also a valid Express middleware. Mount it at the root to keep the default `/admin` and `/admin-api` paths, or under any path to move both:

```ts {3,10,13} filename="src/app.config.ts"
import { defineServer } from "colyseus";
import { GameDatabase } from "@colyseus/database";
import { admin } from "@colyseus/admin";

export const db = new GameDatabase({ connectionString: process.env.DATABASE_URL });

export default defineServer({
    database: db,
    express: (app) => {
        app.use(admin({}));          // UI at /admin/, API at /admin-api

        // or, under a path: UI at /ops/, API at /ops/admin-api
        // app.use("/ops", admin({}));
    },
});
```

    Behind a reverse proxy that strips a prefix, forward it as `X-Forwarded-Prefix` and the served HTML adjusts its base URL.

> **Note:**
>
> The `database` option defaults to `GameDatabase.current`, set automatically when you construct `new GameDatabase(...)`. Multi-database deployments should pass `database` explicitly (e.g. `admin({ database: db })`) to disambiguate which instance the panel drives. `admin()` throws at startup when neither is available.

## Usage

Once mounted, start your server and open `http://localhost:2567/admin/` in your browser (the bare `/admin` redirects to the trailing slash). If you customized `uiPath`, adjust the URL accordingly.

The REST API mounts in parallel at `http://localhost:2567/admin-api` and is consumed by the SPA. Every endpoint enforces the same session and role rules as the UI, so you can script the panel with `curl` or `fetch` using the session cookie. The sub-pages list the endpoints for each area. `GET /admin-api/_health` is the one unauthenticated route: it answers `200 { ok, db, latencyMs }` or `503` when the database is unreachable, for readiness probes.

## First-run bootstrap

The admin panel includes **no built-in admin user**. The SPA calls `GET /admin-api/auth/status` on load; while no user has the `admin` role it reports `needsBootstrap: true` and the panel renders a one-time setup form.

![The first-run setup form asking for an email and password](https://docs.colyseus.io/admin/bootstrap.webp)

Submitting the form calls `POST /admin-api/auth/bootstrap` with `{ email, password }`. If a user with that email already exists (for example, you registered through your game first), that account is promoted instead of created. After bootstrap:

- A session cookie is set (HttpOnly, SameSite=Strict, JWT-signed).
- You're redirected into the panel with full `admin` role access.
- All sibling routes gated with `admin.guard()` (e.g. the Playground or Monitor) now resolve against the same session.
- The endpoint refuses further calls with `403` as soon as one admin exists.

> **Note:**
>
> See [Authentication & RBAC](https://docs.colyseus.io/admin/authentication.md) for the full session, role, and revocation story.

## Hardening for production

The defaults are tuned for local development. Before exposing the panel to the public internet:

- **Set a strong `JWT_SECRET` and `SESSION_SECRET`**: see [Auth Module → Required Environment Secrets](https://docs.colyseus.io/auth/module.md#required-environment-secrets). With `NODE_ENV=production`, `admin()` throws at startup when no JWT secret is configured; outside production it only warns. Rotating `JWT_SECRET` invalidates all admin sessions (`SESSION_SECRET` only signs OAuth state cookies).
- **Keep player accounts out of the panel.** `POST /admin-api/auth/login` accepts any user row with a password. The `user` role then passes the list/read gate on every resource and on the room inspector. A player with an email and password can therefore read live room state and other players' emails through the API. Until the package closes this, serve the panel on a separate hostname or behind your own network guard. Keeping admin accounts in a dedicated database also works. See [Authentication → Roles](https://docs.colyseus.io/admin/authentication.md#roles).
- **Wire [`auth.settings.onForgotPassword`](https://docs.colyseus.io/auth/module.md#on-forgot-password)** so password reset links reach your admins. The panel ships no reset page yet; see [Password reset](https://docs.colyseus.io/admin/authentication.md#password-reset) for the API flow.
- **Tighten the session cookie** via the `session` option: set an explicit `cookieDomain`, an appropriate `ttlSeconds`, and confirm the `cookieSecure`/`cookieSameSite` values match your deployment.
- **Disable `allowDevHeader`** if you don't need it. It auto-disables when `NODE_ENV === "production"`, but setting it to `false` explicitly avoids surprises in mixed environments.
- **Swap the in-memory rate limiters for a Redis-backed implementation** on multi-process deployments. The default token buckets don't share state across instances. The limiter keys on `X-Forwarded-For` / `X-Real-IP` when present, so only expose the panel behind a proxy that overwrites those headers.
- **Gate the Monitor and Playground** behind `admin.guard()` so you don't have multiple unauthenticated panels exposed:

    ```ts filename="src/app.config.ts"
    routes: createRouter({
        ...playground({ use: [admin.guard()] }),
        ...monitor({    use: [admin.guard()] }),
        ...admin({}),
    }),
    ```

> **Important:**
>
> `enforceRbac: false` removes every identity check: any anonymous request can create, update, delete, kick, dispose and ban, and audit rows are written without an `operatorId`. Use it only on a local database.

## Options reference

`admin(options)` accepts the following `AdminOptions`:

| Option | Type | Default | Description |
|---|---|---|---|
| `database` | `GameDatabase` | `GameDatabase.current` | The database powering the user store, audit log, and table introspection. Pass explicitly for multi-database setups. |
| `tables` | `Record<string, Table>` | `database.tables` | Map of drizzle tables exposed in the panel. Custom tables must be added here: `{ ...db.tables, guilds }`. See [Resources & CRUD](https://docs.colyseus.io/admin/resources.md#exposing-a-custom-table). |
| `resources` | `Record<string, ResourceDefinition>` | built-in defaults | Per-table UI/UX overrides: labels, visible columns, form fields, actions, policies. The audit log and user notes get built-in definitions unless you override them. See [Resources & CRUD](https://docs.colyseus.io/admin/resources.md). |
| `uiPath` | `string` | `"/admin"` | Mount path for the admin SPA. Ignored under an Express path mount, where the mount path wins. |
| `apiPath` | `string` | `"/admin-api"` | Mount path for the admin REST API. Nested inside the mount under an Express path mount. |
| `uiDistDir` | `string` | _built-in_ | Absolute path to the built UI assets. Defaults to the bundled `build/` directory inside the package. |
| `session` | `SessionConfig` | _see below_ | Cookie config: `ttlSeconds`, `cookieDomain`, `cookieSameSite`, `cookieSecure`. |
| `resolveUserId` | `(ctx: { getHeader }) => string \| undefined \| Promise<…>` | session cookie, then `X-User-Id` in dev | Replace the identity resolver to integrate another auth scheme. Your function receives only `getHeader(name)`. The default also rejects sessions whose `tokenVersion` was bumped; a replacement has to repeat that check. |
| `enforceRbac` | `boolean` | `true` | Set to `false` to skip every identity and role check (local development only, see the warning above). |
| `allowDevHeader` | `boolean` | `true` in dev, `false` in prod | Permit `X-User-Id: <id>` as a fallback identity for curl/puppeteer testing. |
| `minPasswordLength` | `number` | `8` | Minimum password length accepted by the bootstrap and reset endpoints. Plain length check, no complexity rules. |
| `onResetRequest` | `(ctx) => void \| Promise<void>` | forwards to `auth.settings.onForgotPassword`, else logs the link | Deliver the password reset link. Receives `{ email, userId, token, url }`; `url` is a site-relative path. See [Password reset](https://docs.colyseus.io/admin/authentication.md#password-reset). |
| `rateLimit` | `{ login, bootstrap, requestReset }` | in-memory token buckets | Per-endpoint rate limiters. Pass `false` per slot to disable, or a custom `RateLimiter` to swap in a Redis-backed implementation. |
| `dashboard` | `{ presets, widgets }` | all presets enabled | Configure the dashboard homepage. See [Dashboard & widgets](https://docs.colyseus.io/admin/dashboard.md). |
| `logger` | `Logger \| null` | JSON to stdout / stderr | Pino-compatible logger (`info`, `warn`, `error`, `child`). `warn` and `error` go to stderr; `debug` only prints with `LOG_DEBUG=1`. Pass `null` to silence the panel's internal logs. |

### Session defaults

The `session` config controls the JWT cookie. Defaults:

```ts
session: {
    ttlSeconds: 7 * 24 * 60 * 60, // 1 week
    cookieSameSite: "Strict",
    cookieSecure: process.env.NODE_ENV === "production",
    // cookieDomain: undefined  ← host-only; set explicitly when serving from a subdomain
}
```

The cookie is always `HttpOnly`, scoped to `Path=/`, and signed with `JWT_SECRET`. Revoking a session is done via `db.auth.bumpTokenVersion(userId)`. See [Database → Authentication](https://docs.colyseus.io/database/authentication.md).

## Next steps

- [Authentication & RBAC](https://docs.colyseus.io/admin/authentication.md): sessions, roles, password reset, and `admin.guard()`.
- [Resources & CRUD](https://docs.colyseus.io/admin/resources.md): exposing custom tables, customizing columns and forms, custom actions, the audit log.
- [Dashboard & widgets](https://docs.colyseus.io/admin/dashboard.md): configuring presets and appending custom widgets to the homepage.
- [Live rooms](https://docs.colyseus.io/admin/rooms.md): the built-in room inspector.

---
Source: https://docs.colyseus.io/admin


# Authentication & RBAC

The admin panel uses **session-based JWT cookies** for authentication and a three-role hierarchy (`admin` / `mod` / `user`) for authorization. Both reuse [`@colyseus/database`](https://docs.colyseus.io/database.md) and [`@colyseus/auth`](https://docs.colyseus.io/auth/module.md), so revocation, password hashing, and JWT signing follow the same rules as your application's player auth.

## Sessions

When an admin signs in (`POST /admin-api/auth/login`), the panel sets an HttpOnly cookie carrying a signed JWT with `userId`, `role`, `iat`, `exp`, and `tv` (token-version) claims.

| Property | Default | Notes |
|---|---|---|
| Cookie name | `colyseus_admin_session` | Fixed, not configurable |
| `HttpOnly` | `true` | Always, not configurable |
| `Path` | `/` | Always |
| `SameSite` | `Strict` | Configurable via `session.cookieSameSite` (`'Strict' \| 'Lax' \| 'None'`) |
| `Secure` | `true` in production | Auto-set based on `NODE_ENV`; override via `session.cookieSecure` |
| TTL | 7 days | Configurable via `session.ttlSeconds` |
| Domain | host-only | Set via `session.cookieDomain` when serving from a subdomain |

There is no server-side session store. Every request verifies the cookie's signature, then re-reads two columns from the database. The user's `tokenVersion` must equal the `tv` claim, and the role is always the current one. Two consequences:

- **Logout** (`POST /admin-api/auth/logout`) clears the cookie. The JWT itself remains valid until it expires unless its `tokenVersion` is bumped.
- **Revocation** happens by incrementing the user's `tokenVersion` column. `db.auth.bumpTokenVersion(userId)` invalidates every session issued before the call on its next verification. `db.auth.ban()` does the same atomically with the ban itself. The panel's **Revoke sessions** and **Ban** buttons bump the version. They also close the user's live WebSocket connections in every room they are in.

`POST /admin-api/auth/logout-everywhere` does both for the signed-in admin: it bumps their `tokenVersion` and clears the cookie. Use it after a suspected cookie leak.

See [Database → Authentication](https://docs.colyseus.io/database/authentication.md) for the full revocation story.

### Endpoints

| Method | Path | Auth | Audit action |
|---|---|---|---|
| `GET` | `/admin-api/auth/status` | none | — |
| `POST` | `/admin-api/auth/bootstrap` | none, refused once an admin exists | `auth.bootstrap` |
| `POST` | `/admin-api/auth/login` | none | `auth.login`, `auth.login_failed` |
| `GET` | `/admin-api/auth/me` | session | — |
| `POST` | `/admin-api/auth/logout` | session | `auth.logout` |
| `POST` | `/admin-api/auth/logout-everywhere` | session | `auth.logout` |
| `POST` | `/admin-api/auth/request-reset` | none | `auth.password_reset_requested` |
| `POST` | `/admin-api/auth/reset` | reset token | `auth.password_reset_completed` |

`/auth/status` returns `{ needsBootstrap, authenticated, userId, role }` and drives the SPA's first-run and login redirects. Every auth event lands in the [audit log](https://docs.colyseus.io/admin/resources.md#audit-log) with `resource: "auth"`, including failed logins with the attempted email, IP and user agent.

## Roles

Each admin-panel user has a row in the `roles` table (set via `db.moderation.setRole(userId, role)`). A user without a row counts as `user`. Three roles exist:

| Role | Default access |
|---|---|
| `admin` | Full access: all resources, all actions, all rooms. |
| `mod` | List, read, and update, only on resources assigned via `db.moderation.assignMod()`. No create or delete, no access outside assigned scopes, and the roles table is always blocked. |
| `user` | Cannot open the panel UI (the catalog and dashboard answer 403: an operator role is required). Direct API calls to list and read endpoints still succeed. |

Roles are read from the live DB on every request. A demotion takes effect immediately without re-issuing the cookie.

> **Warning:**
>
> `POST /admin-api/auth/login` issues a session to any user row that has a password, whatever its role. Combined with the `user` row above, a registered player can call `GET /admin-api/users` or `GET /admin-api/rooms/:roomId`. Those answers contain other players' emails and live room state. Until the package closes this gap, keep the panel off the player-facing hostname. A network-level guard of your own in front of `/admin-api` also works.

### Promoting a user to admin

From anywhere with access to the database instance (e.g. a one-off script or an admin-only endpoint):

```ts
await db.moderation.setRole(userId, "admin");
```

The first admin is created by the [bootstrap flow](https://docs.colyseus.io/admin.md#first-run-bootstrap) on first visit; subsequent admins are promoted from the panel's user-management UI.

### Scoping a moderator to specific resources

Mods get mod-level access only on the resources they're assigned to. Assignments are per-resource and use the canonical table key (`guilds`, `userNotes`, `rooms`), not the SQL table name:

```ts
await db.moderation.assignMod(userId, "guilds");        // mod on `guilds`
await db.moderation.assignMod(userId, "leaderboards");  // also mod on leaderboards
await db.moderation.unassignMod(userId, "guilds");      // revoke
```

`assignMod()` promotes a plain `user` to `mod` on the first assignment. `unassignMod()` never demotes: a mod with no scopes left keeps the role and can still open the panel, so call `setRole(userId, "user")` when you want them out.

This pattern lets you give a community manager full control over guilds without exposing every other table. See [Resources & CRUD → Policies](https://docs.colyseus.io/admin/resources.md#policies) for how to declare per-action role gates on individual resources.

## `admin.guard()`

The `admin.guard()` middleware checks the same session cookie used by the panel itself. You can therefore gate other HTTP routes (the Monitor, the Playground, or any custom endpoint) behind a single admin login.

```ts {1,6-7} filename="src/app.config.ts"
import { admin } from "@colyseus/admin";
import { playground } from "@colyseus/playground";
import { monitor } from "@colyseus/monitor";

routes: createRouter({
    ...playground({ use: [admin.guard()] }),
    ...monitor({    use: [admin.guard({ role: "mod" })] }),
    ...admin({ database: db }),
}),
```

The same middleware works on your own endpoints:

```ts
createEndpoint("/ops/reindex", { method: "POST", use: [admin.guard()] }, async (ctx) => {
    // only admins reach this point
});
```

### Behavior

The guard decides how to reject from the `Accept` header. A request counts as a browser navigation when `Accept` contains `text/html` (a bare `*/*` does not).

| Request type | Missing, invalid or revoked session | Insufficient role |
|---|---|---|
| Browser navigation (`Accept: text/html`) | `302` → `<loginUrl>/?next=<originalUrl>` | `302` → login, **session cookie cleared** to break redirect loops |
| XHR / fetch / curl | `401` JSON body | `403` JSON body naming both roles: `requires role 'admin' or higher (you have 'mod')` |

`next` carries the original path and query string. The guard omits it when the path is not a plain absolute path, so an open redirect can't be smuggled in.

The "cookie cleared" behavior on insufficient role is intentional. A lower-role user visiting `/monitor` (gated to `mod` or higher) still holds a valid session cookie. The login page would otherwise treat them as already authenticated and redirect them right back through the guard, creating a loop. Clearing the cookie forces a real re-authentication.

### Options

| Option | Type | Default | Description |
|---|---|---|---|
| `database` | `GameDatabase` | `GameDatabase.current` | Database to validate the session against. `admin.guard()` throws when neither is available. |
| `role` | `'admin' \| 'mod' \| 'user'` | `'admin'` | Minimum role required. Hierarchy: admin > mod > user. |
| `loginUrl` | `string` | `'/admin'` | Where to send unauthenticated browser visits. Match `uiPath` if you customized it. |
| `apiOnly` | `boolean` | `false` | Force JSON responses even for browser navigations. Set to `true` when wrapping non-HTML endpoints. |

## Password reset

The reset flow is implemented on the API, but **the panel ships no reset page yet**. The login screen has no "Forgot password?" link and the SPA has no `/reset` route. You drive the two endpoints from your own page, or from a script when an admin is locked out.

1. `POST /admin-api/auth/request-reset` with `{ email }`. The endpoint answers `200` whether or not the email exists, so it can't be used to enumerate users. Only a missing email (`400`) and the rate limit (`429`) answer differently.
2. If the email matches a user, the panel signs a short-lived token (`15` minutes, not configurable, single-use) and calls your `onResetRequest({ email, userId, token, url })` callback.
3. `url` is the site-relative path `<uiPath>/reset?token=<token>`. Nothing prepends your public origin, so the callback has to build the absolute link, and the page at that path is yours to provide.
4. The page (or your script) calls `POST /admin-api/auth/reset` with `{ token, password }`. The endpoint verifies the token, writes the new hash via `db.auth.setPasswordHash()`, then bumps `tokenVersion` so every existing session for that user is terminated. A second call with the same token fails with `400`, because the bump changed the `tv` the token was signed with.

> **Note:**
>
> The default `onResetRequest` forwards through [`auth.settings.onForgotPassword`](https://docs.colyseus.io/auth/module.md#on-forgot-password) when configured. It renders `html/admin-reset-password-email.html` from your project when present, and the standard `reset-password-email.html` otherwise. Both use the `[LINK]` placeholder (see [custom templates](https://docs.colyseus.io/auth/module.md#customizing-the-email-templates)). Without that hook it logs the link through the admin logger, which is fine for local development only.

```ts filename="src/app.config.ts"
admin({
    database: db,
    onResetRequest: async ({ email, url }) => {
        await mailer.send({
            to: email,
            subject: "Reset your admin password",
            html: `<p>Click <a href="${process.env.PUBLIC_URL}${url}">here</a> to reset your password. The link expires in 15 minutes.</p>`,
        });
    },
}),
```

Until you host a reset page, an operator can complete the flow from a terminal:

```sh
curl -X POST http://localhost:2567/admin-api/auth/request-reset \
     -H 'content-type: application/json' -d '{"email":"ops@example.com"}'
# read the token from the logged link (or the email), then:
curl -X POST http://localhost:2567/admin-api/auth/reset \
     -H 'content-type: application/json' -d '{"token":"<token>","password":"new-password"}'
```

## Rate limits

The auth endpoints are rate-limited to slow down brute-force attacks. Defaults are in-memory token buckets per limiter, sufficient for single-process deployments. Replace with a Redis-backed `RateLimiter` for multi-node setups so the buckets are shared across instances.

| Endpoint | Default limit | Option |
|---|---|---|
| `/auth/login` | burst of 10, refill 10/min, per IP + email | `rateLimit.login` |
| `/auth/bootstrap` | burst of 5, refill 1/min, per IP | `rateLimit.bootstrap` |
| `/auth/request-reset` | burst of 3, refill 1/min, per IP + email | `rateLimit.requestReset` |

A blocked request receives `429` with a `Retry-After` header. A limiter is any object with one method; `null` lets the request through, a `Response` blocks it:

```ts
interface RateLimiter {
    check(key: string): Response | null | Promise<Response | null>;
}
```

Each slot accepts `false` to disable that limiter (e.g. behind your own WAF). It also accepts a tighter in-memory bucket from the exported `createTokenBucketLimiter()`, or your own implementation:

```ts
import { admin, createTokenBucketLimiter } from "@colyseus/admin";

admin({
    database: db,
    rateLimit: {
        login: createTokenBucketLimiter({ capacity: 5, refillPerSec: 1 / 30, retryAfterSec: 30 }),
        requestReset: myRedisLimiter, // your own RateLimiter implementation
        bootstrap: false,
    },
}),
```

The bucket keys use the client IP as seen in `X-Forwarded-For` or `X-Real-IP` when present (`ipFromHeaders()` is exported if your limiter needs the same value). The in-memory map keeps one bucket per distinct key and is never pruned. A long-lived single process exposed to the open internet should prefer the Redis-backed variant.

## Next steps

- [Resources & CRUD](https://docs.colyseus.io/admin/resources.md): per-resource policies (the third layer of access control, on top of role + scope).
- [Hardening for production](https://docs.colyseus.io/admin.md#hardening-for-production): cookie domain, secrets rotation, and email delivery.

---
Source: https://docs.colyseus.io/admin/authentication


# Dashboard & widgets

The admin panel homepage hosts a grid of **widgets**, small cards that surface live data from your database or runtime. Five **preset widgets** are enabled by default, and you can append **custom widgets** for anything else you want at a glance.

![The dashboard with the Totals, Recent users and Live rooms presets and a custom "Active events" KPI card](https://docs.colyseus.io/admin/dashboard.webp)

```ts {4-16} filename="src/app.config.ts"
routes: createRouter({
    ...admin({
        database: db,
        dashboard: {
            presets: {
                totals: { only: ["users", "cloudSaves"] },
                recentUsers: { limit: 10 },
                health: false, // disable
            },
            widgets: [{
                title: "Active events",
                icon: "thunderbolt",
                render: "kpi",
                data: async () => ({ live: 12, queued: 3 }),
            }],
        },
    }),
}),
```

The dashboard is served by `GET /admin-api/_dashboard`, which returns `{ widgets: [...] }` with one entry per widget. Both this route and the per-widget refresh route are operator-only. Any admin or mod can load them (mods regardless of scope); a plain `user` gets `403`.

## Preset widgets

| Preset | Default title | Render | Surfaces |
|---|---|---|---|
| `totals` | Totals | KPI | Row counts per table in `database.tables`, a useful "DB is healthy" snapshot. |
| `recentUsers` | Recent users | Table | Newest user registrations with deep-link to each user's show page. |
| `liveRooms` | Live rooms | Table | Currently-active rooms from the matchmaker driver with deep-link to the room inspector. Refreshes every 3 seconds. |
| `health` | Database health | KPI | Database connectivity check. Reports `status` and query `latency`. |
| `segments` | Segments | KPI | One count per cohort registered with `db.segments.define()` (see [Database](https://docs.colyseus.io/database.md)). Empty when none are defined. |

All presets are enabled by default. Configure each via `dashboard.presets.<name>`:

| Value | Effect |
|---|---|
| _omitted_ or `true` | Enabled with defaults. |
| `false` | Disabled: the preset is not rendered. |
| Options object | Enabled with customization. |

### Preset options

Every preset shares three base options (`title`, `icon`, `span`) and adds preset-specific knobs.

#### `totals`

```ts
totals: {
    title?: string;
    icon?: AdminIconName;
    span?: number;            // 1-24, see Widget shape
    only?: string[];          // restrict to a subset of table keys
}
```

```ts
totals: { only: ["users", "cloudSaves", "leaderboardEntries"] }
```

`totals` only knows the tables in `database.tables` (the built-ins). Custom tables passed through `admin({ tables })` and unknown names are dropped silently. Count a custom table with a [KPI widget](#kpi) instead.

#### `recentUsers`

```ts
recentUsers: {
    title?: string;
    icon?: AdminIconName;
    span?: number;
    limit?: number;                  // default 5
    columns?: UserColumnName[];      // subset of users columns, in order
}
```

```ts
recentUsers: { limit: 10, columns: ["id", "email", "createdAt"] }
```

`columns` uses the drizzle property names of your `users` table (`createdAt`, plus any column you added when extending the schema). Without `columns` the widget returns entire user rows to the browser, including `passwordHash`. Set `columns` on any panel that is not strictly local.

#### `liveRooms`

```ts
liveRooms: {
    title?: string;
    icon?: AdminIconName;
    span?: number;
    limit?: number;                          // default 10
    columns?: LiveRoomColumnName[];          // default: roomId, name, clients, maxClients, locked, createdAt
}
```

```ts
liveRooms: { limit: 20, columns: ["roomId", "name", "clients", "processId"] }
```

Available columns: `roomId`, `name`, `clients`, `maxClients`, `locked`, `private`, `createdAt`, `elapsedTime`, `processId`, `publicAddress`. `maxClients` renders as `∞` for uncapped rooms and `elapsedTime` is raw milliseconds. The 3-second refresh is built into the preset and is not configurable.

#### `health` / `segments`

Both accept only the base options (`title`, `icon`, `span`). No preset-specific knobs.

## Custom widgets

Append your own widgets via `dashboard.widgets`. The widget list is resolved once when `admin()` runs; each widget's `data` function runs on every dashboard request and its result is sent to the client:

```ts
widgets: [{
    title: "Active events",          // also the basis for the auto-derived id
    icon: "thunderbolt",             // AdminIconName
    render: "kpi",                   // 'kpi' | 'table' | 'list' | 'json' (default 'json')
    span: 12,                        // 1-24 grid span (half width)
    refreshIntervalMs: 5000,         // poll for live updates
    data: async ({ database, userId }) => ({ live: 12, queued: 3 }),
}]
```

### Widget shape

```ts
interface DashboardWidget {
    id?: string;             // defaults to slugify(title)
    title: string;
    icon?: AdminIconName;
    render?: WidgetRender;   // 'kpi' | 'table' | 'list' | 'json' (default 'json')
    span?: number;           // 1-24; default per render type
    refreshIntervalMs?: number;
    data: (ctx: { database: GameDatabase; userId: string }) => Promise<unknown>;
}
```

| Field | Notes |
|---|---|
| `id` | Stable identifier, also used for `data-testid="widget-<id>"`. Defaults to `slugify(title)` (e.g. `"Live events"` → `"live-events"`). `admin()` throws at startup when the id collides with a preset or another widget, or when the title slugifies to an empty string. |
| `data` | Server-side resolver. Receives the resolved `GameDatabase` and the requesting admin's `userId`. Errors are caught and surfaced to the panel as `{ error }` on that card only. |
| `refreshIntervalMs` | When set, the client polls `GET /admin-api/_dashboard/<id>` at this cadence and refreshes the card in place (no full dashboard reload). |
| `span` | Width on a 24-unit scale, mapped onto the panel's grid. Defaults: `kpi`/`table`/`json` full width (24), `list` half (12). The grid collapses to a single column on mobile widths regardless of span. |

### Render modes

The `render` field tells the panel how to interpret `data`'s return value.

#### `kpi`

`data` returns `Record<string, number | string>`. The panel renders each entry as a label/value card, with the key as the label.

```ts
{
    title: "Player counts",
    render: "kpi",
    data: async ({ database }) => {
        const [total, banned] = await Promise.all([
            database.drizzle.$count(database.tables.users),
            database.drizzle.$count(database.tables.users, isNotNull(database.tables.users.bannedUntil)),
        ]);
        return { total, banned };
    },
}
```

#### `table`

`data` returns `TableWidgetData`:

```ts
interface TableWidgetData {
    columns: string[];           // header order; auto-humanized for display
    rows: Array<Record<string, any>>;
    linkTo?: {
        resource: string;        // admin resource key to link to
        idColumn?: string;       // row column with the FK value; default 'id'
    };
}
```

When `linkTo` is set, the panel makes each row clickable and navigates to that resource's show page (`rooms` links into the [room inspector](https://docs.colyseus.io/admin/rooms.md)). This behavior is useful for "recent X" widgets that should deep-link back to the records.

```ts
{
    title: "Top guilds",
    render: "table",
    data: async ({ database }) => ({
        columns: ["id", "name", "memberCount"],
        rows: await database.drizzle.select().from(guilds).orderBy(desc(guilds.memberCount)).limit(10),
        linkTo: { resource: "guilds" },
    }),
}
```

#### `list`

`data` returns `Array<{ title: string; description?: string }>`. The panel renders a simple labeled list, good for status feeds or named items without tabular structure.

```ts
{
    title: "Recent events",
    render: "list",
    data: async () => [
        { title: "Server deployed", description: "v1.4.2, 12 minutes ago" },
        { title: "Hotfix applied", description: "v1.4.1, 2 hours ago" },
    ],
}
```

#### `json`

`data` returns anything. The panel pretty-prints it in a scrollable code block. Default render mode when `render` is omitted (useful for ad-hoc diagnostics).

```ts
{
    title: "Cache stats",
    render: "json",
    data: async () => cache.stats(),
}
```

## Refresh and polling

By default, widgets resolve once when the dashboard loads. For live data, set `refreshIntervalMs` to enable client-side polling of `GET /admin-api/_dashboard/<id>`. Only the affected card re-renders, which is useful for a live rooms count or active sessions card without paying for a full dashboard refresh. The first refresh fires one interval after the page loads; a failed poll keeps the last good value.

```ts
{
    title: "Signups today",
    render: "kpi",
    refreshIntervalMs: 3000, // every 3s
    data: async ({ database }) => {
        const since = new Date(Date.now() - 24 * 60 * 60 * 1000);
        return {
            signups: await database.drizzle.$count(database.tables.users, gte(database.tables.users.createdAt, since)),
        };
    },
}
```

## Next steps

- [Resources & CRUD](https://docs.colyseus.io/admin/resources.md): for the underlying tables that widgets pull from.
- [Live rooms](https://docs.colyseus.io/admin/rooms.md): the room inspector that `liveRooms` and your custom widgets can deep-link into.

---
Source: https://docs.colyseus.io/admin/dashboard


# Resources & CRUD

Every drizzle table you pass to the admin panel becomes a browse-able **resource** with a full CRUD UI. The UI includes a paginated list with search, filter and sort. It adds a detail view with related rows, create and edit forms, and per-row custom actions. The built-in tables from [`@colyseus/database`](https://docs.colyseus.io/database.md) are registered automatically. You customize them, and add your own, with the `tables` and `resources` options.

![The Guilds resource list with a toolbar action and per-row actions](https://docs.colyseus.io/admin/resource-list.webp)

## Built-in resources

The built-in tables, in sidebar order:

| Resource | Key | Source table | Notes |
|---|---|---|---|
| Users | `users` | `colyseus_users` | Detail page adds ban, unban and revoke-sessions buttons, plus an **Active sessions** tab (needs [`TrackUserSessionsPlugin`](https://docs.colyseus.io/room/plugins/track-user-sessions.md)). |
| Configs | `configs` | `colyseus_configs` | — |
| Leaderboards | `leaderboards` | `colyseus_leaderboards` | — |
| Analytics Events | `analyticsEvents` | `colyseus_analytics_events` | — |
| Cloud Saves | `cloudSaves` | `colyseus_cloud_saves` | — |
| Leaderboard Entries | `leaderboardEntries` | `colyseus_leaderboard_entries` | — |
| Roles | `roles` | `colyseus_roles` | Blocked for mods by the core role rule itself (not a policy). Modifying it would bypass the role system. |
| User Notes | `userNotes` | `colyseus_user_notes` | `author_id` auto-filled from the session on create. |
| Audit log | `adminAudit` | `colyseus_admin_audit` | Admin-only reads; every write denied, including for admins (append-only contract). |

![A user's detail page: columns, related-row tabs, the Active sessions list, and the per-user audit trail](https://docs.colyseus.io/admin/user-show.webp)

The label derives from the key unless a definition overrides it. The **key** is what you use everywhere else: in URLs (`/admin/cloudSaves`, `/admin-api/cloudSaves`), in `db.moderation.assignMod(userId, "cloudSaves")`, and as the `resource` value in audit rows.

Unless a table declares its own [policies](#policies), access follows the standard role rule. Only the audit log declares policies by default.

- **admin**: full CRUD.
- **mod**: list, read, and update, only on resources they're [scoped to](https://docs.colyseus.io/admin/authentication.md#scoping-a-moderator-to-specific-resources).
- **user**: cannot open the panel UI (403). Direct API calls to list and read endpoints still succeed.

## Exposing a custom table

Two options work together. `tables` decides **which** drizzle tables exist in the panel; `resources` decides **how** each one looks and behaves. A custom table needs both: a `resources` entry alone is stored but never listed, and `/admin-api/guilds` answers `404`.

```ts {2,6-7} filename="src/app.config.ts"
import { admin, defineAdminResource } from "@colyseus/admin";
import { guilds } from "./db/schema";

routes: createRouter({
    ...admin({
        tables: { ...db.tables, guilds },                 // what exists
        resources: { guilds: defineAdminResource(guilds, { label: "Guilds" }) }, // how it looks
    }),
}),
```

`db.tables` holds the built-in tables keyed by their canonical names. The key you pick for a custom table (`guilds`) becomes its URL segment and its scope name for mods. A custom table with no `resources` entry still works: you get the humanized label, a default icon picked from the table name, and all columns.

> **Note:**
>
> `GameDatabase` only creates its own tables at boot. Create custom tables with your migrations (see [Database → Schemas](https://docs.colyseus.io/database/schemas.md)) before pointing the panel at them.

## Customizing a resource

Override the defaults of any table, built-in or custom, by passing `defineAdminResource(table, config)` into `resources`:

```ts {4,36-37} filename="src/app.config.ts"
import { admin, defineAdminResource } from "@colyseus/admin";
import { guilds } from "./db/schema";

const guildResource = defineAdminResource(guilds, {
    label: "Guilds",
    icon: "safety",
    list: {
        columns: ["name", "owner_id", "member_count", "created_at"],
        defaultSort: { field: "created_at", order: "desc" },
    },
    form: {
        fields: ["name", "description", "owner_id"],
    },
    columns: {
        created_at: { label: "Founded" },
    },
    actions: [{
        name: "rename",
        label: "Rename guild",
        perRow: true,
        confirm: { title: "Rename this guild?" },
        handler: async (row, { userId }) => {
            // ...rename logic
            return { renamedBy: userId };
        },
        roles: ["admin", "mod"],
    }],
    policies: {
        delete: ["admin"], // admin-only deletion
    },
});

routes: createRouter({
    ...admin({
        database: db,
        tables: { ...db.tables, guilds },
        resources: { guilds: guildResource },
    }),
}),
```

> **Warning:**
>
> Column lists (`list.columns`, `form.fields`, `show.fields`) and the keys of `columns` are **SQL column names** (`owner_id`), not drizzle property names (`ownerId`). A property name matches nothing and is dropped without an error.

### Configuration reference

```ts
defineAdminResource(table, {
    label,        // sidebar/page title; defaults to the humanized key
    icon,         // sidebar icon from the built-in icon set (see below)
    list:    { columns, defaultSort },
    form:    { fields },
    show:    { fields },
    create:  { defaults },
    columns: { <sqlColumn>: { label, linkTo } },
    relations: { <relName>: { label } },
    actions: [ /* ResourceAction[] */ ],
    policies: { list, read, create, update, delete },
})
```

| Section | Field | Description |
|---|---|---|
| `list` | `columns` | Columns shown in the list view, in order. Primary keys are always included. Omit to show all. |
|        | `defaultSort` | `{ field, order: 'asc' \| 'desc' }` applied when no `_sort` is requested. Useful for append-only tables. |
| `form` | `fields` | Columns shown in the create and edit forms. The create form additionally hides primary keys and columns with a database default, even when listed here. Omit to show all. |
| `show` | `fields` | Columns shown on the read-only detail page. |
| `create` | `defaults` | `(ctx) => Record<string, any> \| Promise<…>`: server-side defaults merged into the body before INSERT. Receives `{ operatorId, resource }`. The request body wins on conflict. |
| `columns` | `<col>.label` | Override the auto-humanized column label. |
|           | `<col>.linkTo` | Decorate the cell as a link to another resource's show page. Static: `{ resource: "users" }`; for the dynamic form, see [FK auto-linking](#fk-auto-linking). |
| `relations` | `<rel>.label` | Override the auto-humanized relation tab label. |
| `actions` | `ResourceAction[]` | Custom per-row or bulk operations. See below. |
| `policies` | `list \| read \| create \| update \| delete` | Per-action RBAC. See [Policies](#policies). |

Every column header in the list view sorts on click; there is no per-column opt-in.

### Server-side defaults on create

The `create.defaults` function runs on every INSERT with the operator in scope. Use it to auto-fill audit fields like `author_id` or `created_by` from the session.

```ts
create: {
    defaults: ({ operatorId }) => ({ authorId: operatorId }),
}
```

Keys can be either SQL column names (`author_id`) or drizzle property names (`authorId`). Both forms are normalized. The request body wins on conflict, matching how SQL `DEFAULT`s behave per-column. `operatorId` is `undefined` when `enforceRbac` is off.

## Custom actions

Custom actions are operations beyond create/update/delete: things like "reset a player's level", "refund a transaction", "rename a guild". They appear as buttons on the resource's list page: a toolbar button for bulk actions, a per-row menu for row actions. The detail page shows none. Each click resolves to a POST request:

```
POST /admin-api/:resource/_action/:name
```

### Per-row actions

Set `perRow: true` to make the action operate on a specific row. The panel sends `{ id }` and the handler receives the row data:

```ts
actions: [{
    name: "reset_progress",
    label: "Reset progress",
    perRow: true,
    confirm: {
        title: "Reset this player's progress?",
        description: "This clears all cloud saves and resets the user's level to 1.",
    },
    handler: async (row, { userId, resource }) => {
        await db.saves.delete(row.id);
        await db.drizzle.update(users).set({ level: 1 }).where(eq(users.id, row.id));
        return { ok: true };
    },
    roles: ["admin"],
}]
```

The endpoint answers `{ ok: true, result }` with the handler's return value, JSON-serialized. The panel itself shows a generic success toast and only displays the body on failure. The return value is for API callers and the audit log.

### Bulk actions

Omit `perRow` for actions that operate on the table at large (e.g. "reseed leaderboard", "purge old entries"). The panel sends `{}` and the handler receives `null` for the row argument.

### Confirmation prompts

`confirm` is optional but recommended for destructive or expensive operations. Without it the panel still asks `Run "<label>"?` before sending:

```ts
confirm: {
    title: "Refund this transaction?",
    description: "The amount will be credited back to the user's wallet.",
}
```

### Audit logging

Custom action invocations are recorded with `action: "custom"`, the row id as `target_id`, and `payload: { name, args, result }`, where `args` is the full request body. Avoid passing secrets through action bodies. See [Audit log](#audit-log) below.

## Policies

Per-resource RBAC overrides the role + scope defaults. `policies` is keyed by action (`list`, `read`, `create`, `update`, `delete`) with values:

| Value | Meaning |
|---|---|
| `['admin']` | Only admins (full role) can perform this action. |
| `['admin', 'mod']` | Admins or any mod, regardless of resource scope assignment. |
| `'everyone'` | Any signed-in identity, whatever its role (including `user`). Anonymous requests still get `401`. |
| `'deny'` | Blocked entirely, even for admins. Useful for read-only resources like the audit log. |

```ts
policies: {
    delete: ["admin"],         // admin-only deletion
    create: ["admin", "mod"],  // mods can create, regardless of scope
    update: "deny",            // table is read-only
}
```

A policy set for an action **replaces** the standard RBAC rule for that action on that resource. The policy is not layered on top. Only actions with no policy fall back to the standard `db.moderation.can(userId, action, resource)` rule.

### Custom action policies

Custom actions have their own `roles` field. Policies do not apply to them, and neither does the mod scope check:

```ts
actions: [{
    name: "rename",
    handler: ...,
    roles: ["admin", "mod"],  // restrict to admins + mods
}]
```

> **Warning:**
>
> A non-empty `roles` list is checked literally and **never includes admins implicitly**, so always list the `admin` role. Omitting `roles`, or passing `[]`, skips the role check entirely. Any signed-in identity can then invoke the action, even a plain `user` who cannot open the panel. The action also bypasses an `update: "deny"` policy on the resource. Give every action an explicit `roles` list. To remove an action, omit it from the resource definition instead.

## FK auto-linking

The panel reads `database.relations` to decorate foreign-key columns. Relations between the built-in tables are declared for you. A `user_id` column on `cloudSaves` becomes a clickable link to the user's show page automatically. The cell shows the user's `display_name`, `name`, `email` or `title` instead of the raw id. Declare relations for your own tables on the `GameDatabase` constructor, using drizzle property names for `fk`:

```ts {4-7} filename="src/db/database.ts"
export const db = new GameDatabase({
    connectionString: process.env.DATABASE_URL,
    schemas: schema,
    relations: {
        guilds: [{ name: "owner", target: "users", kind: "one", fk: "ownerId" }],
        users:  [{ name: "ownedGuilds", target: "guilds", kind: "many", fk: "ownerId" }],
    },
});
```

The `one` relation turns `owner_id` into a labelled link on every guilds row; the `many` relation adds an "Owned guilds" tab to each user's detail page. Composite-key targets are skipped.

A static `columns.<col>.linkTo: { resource }` override also renders a link, but only a link: the cell keeps the raw value. For columns whose target varies per row, use the dynamic form. The built-in audit log definition does this for `target_id`, which references a different table on every row:

```ts
columns: {
    target_id: {
        label: "Target",
        linkTo: { resourceFromColumn: "resource" },
        // value of `resource` on the same row picks the link target
    },
}
```

## Icons

The `icon` field accepts the names of icons from the panel's built-in icon set. Types are surfaced as the `AdminIconName` union. Common picks: `user`, `team`, `safety`, `trophy`, `file-text`, `setting`, `line-chart`, `database`, `thunderbolt`. See `ADMIN_ICON_NAMES` in `@colyseus/admin` for the full list. When `icon` is omitted the panel guesses one from the table name (`*_users` → `user`, `*_scores` → `trophy`, and so on) and falls back to `database`.

## REST endpoints

The SPA is a thin client over these routes. `:resource` is the canonical key and `:id` the primary key value. Composite keys are addressed with a base64url-encoded JSON array of the key values, in table order.

| Method | Path | Gate | Audit action |
|---|---|---|---|
| `GET` | `/admin-api` | operator (admin or mod) | — |
| `GET` | `/admin-api/:resource` | `list` | — |
| `GET` | `/admin-api/:resource/:id` | `read` | — |
| `POST` | `/admin-api/:resource` | `create` | `create` |
| `PATCH` or `PUT` | `/admin-api/:resource/:id` | `update` | `update` |
| `DELETE` | `/admin-api/:resource/:id` | `delete` | `delete` |
| `POST` | `/admin-api/:resource/_action/:name` | action `roles` | `custom` |
| `GET` | `/admin-api/:resource/:id/_counts` | `read` | — |
| `GET` | `/admin-api/:resource/:id/relations/:name` | `read` on both tables | — |
| `POST` | `/admin-api/users/:id/ban` | `update` on `users` | `user.ban` |
| `POST` | `/admin-api/users/:id/unban` | `update` on `users` | `user.unban` |
| `POST` | `/admin-api/users/:id/revoke-sessions` | `update` on `users` | `user.revoke_sessions` |

`GET /admin-api` returns the catalog: every resource with its columns, relations and actions. Request and response bodies use SQL column names.

The list endpoint follows the `@refinedev/simple-rest` query contract:

| Query | Effect |
|---|---|
| `_start`, `_end` | Row window (default `0`–`100`). The response carries `x-total-count`. |
| `_sort`, `_order` | Column name and `asc` / `desc`. Falls back to the resource's `defaultSort`. |
| `_q` | Substring match across the text columns. |
| `<col>_like`, `<col>_eq`, `<col>_ne`, `<col>_gt`, `<col>_gte`, `<col>_lt`, `<col>_lte`, `<col>_in` | Per-column filters. `_in` takes a comma-separated list. |

```sh
curl -b cookies.txt "http://localhost:2567/admin-api/guilds?_sort=member_count&_order=desc&_start=0&_end=20&name_like=night"
```

`ban` takes an optional `{ reason, until }`; the reason is capped at 500 characters. All three user endpoints also close the user's live WebSocket sessions and answer `501` when your `users` table lacks the ban or `token_version` columns.

## Audit log

Every mutation from the panel is recorded to the append-only `colyseus_admin_audit` table. The log covers CRUD (`create`, `update`, `delete`), ban / unban / session-revoke, custom-action invocations, live-room mutations (kick, lock, unlock, state edit, state delete, dispose) and auth events (`auth.login`, `auth.login_failed`, `auth.logout`, `auth.bootstrap`, `auth.password_reset_requested`, `auth.password_reset_completed`). Each entry stores:

- `created_at`: when it happened
- `operator_id`: which admin did it (`null` for failed logins against unknown emails)
- `action`: `create` / `update` / `delete` / `custom` / `user.ban` / `room.kick` / etc. (full `AuditAction` union in `@colyseus/database`)
- `resource`: the canonical key (`users`, `guilds`, `rooms`, `auth`)
- `target_id`: the affected row id
- `payload`: action-specific JSON

| Action | `payload` |
|---|---|
| `create` | `{ row }` |
| `update` | `{ changes: { <column>: { before, after } } }`, changed columns only |
| `delete` | `{ row }` |
| `custom` | `{ name, args, result }` |
| `user.ban` | `{ reason, until, sessionsClosed, ip, userAgent }` |
| `room.*` | action fields plus `ip` and `userAgent`, see [Live rooms](https://docs.colyseus.io/admin/rooms.md#actions) |
| `auth.*` | `{ email?, ip, userAgent }` |

![The audit log list with action badges and linked targets](https://docs.colyseus.io/admin/audit-log.webp)

Browse the log inside the panel under the **Audit log** resource. Reads are admin-only (`list: ['admin'], read: ['admin']`) because payloads can contain before/after row data, and writes from the panel are denied for everyone via `policies: { create: 'deny', update: 'deny', delete: 'deny' }`. Prune old rows out-of-band with `db.audit.prune(before)`.

### Recording from your own code

If your own tooling mutates the DB outside the panel (e.g. a custom HTTP endpoint), record audit entries the same way the panel does:

```ts
await db.audit.record({
    operatorId,
    action: "custom",
    resource: "users",
    targetId: userId,
    payload: { reason: "VIP grant", before: { vip: false }, after: { vip: true } },
});
```

For updates where you want a structured diff, use `recordUpdate()`. It stores a column-level diff of the changed fields (not both full rows):

```ts
await db.audit.recordUpdate({
    operatorId,
    resource: "users",
    targetId: userId,
    before: oldRow,
    after: newRow,
});
```

The panel's own endpoints log audit-write failures without propagating them, so a failed audit write never blocks a successful mutation. A direct `db.audit.record()` call from your own code **throws** on failure instead. Wrap it yourself if you want the same behavior.

## Next steps

- [Dashboard & widgets](https://docs.colyseus.io/admin/dashboard.md): extend the panel homepage with custom KPI/table/list widgets.
- [Live rooms](https://docs.colyseus.io/admin/rooms.md): the built-in room inspector.
- [Authentication & RBAC](https://docs.colyseus.io/admin/authentication.md): the role + scope layer that policies refine.

---
Source: https://docs.colyseus.io/admin/resources


# Live rooms

The admin panel includes a **live room inspector** that lists every active room the matchmaker knows about. It exposes the operational actions you'd otherwise wire by hand. You can kick a client, lock or unlock a room for matchmaking, edit state in place, or force-dispose a stuck room. No per-room wiring is required. The inspector talks to rooms through `matchMaker.remoteRoomCall()`, the same IPC the framework uses internally. It therefore works with any [matchmaker driver](https://docs.colyseus.io/server/driver.md) and [presence](https://docs.colyseus.io/server/presence.md) combination.

## Listing rooms

**Live rooms** in the sidebar lists every room returned by the matchmaker driver. The table shows Room ID, Name, Clients, Max clients, Locked status (with a `private` badge when set), Uptime and Process. It refreshes every 3 seconds, filters by locked state, and searches by room id, name or process id. Pages hold 20 rows.

![The Live rooms list with search, a locked filter and per-room inspect buttons](https://docs.colyseus.io/admin/rooms-list.webp)

The underlying `GET /admin-api/rooms` returns one object per room:

```json
{
    "roomId": "QcxWRrptI",
    "name": "race",
    "clients": 6,
    "maxClients": 8,            // null when uncapped
    "locked": false,
    "private": false,
    "createdAt": "2026-08-20T20:45:15.000Z",
    "elapsedTime": 52113,       // ms since createdAt
    "processId": "RxW29a6gr",   // which Node process hosts the room
    "publicAddress": null
}
```

Clicking through to a room opens the detail page. It shows a stat strip (clients, locked status, uptime, state size in bytes), the client list, and the state tree with a search box. The room's `metadata` appears when set, and the action buttons sit at the top. The page polls every 2 seconds and pauses while you edit a value.

![The room inspector: clients with session ids and user emails, the live state tree, and the Lock and Dispose buttons](https://docs.colyseus.io/admin/room-inspector.webp)

The client list comes from the room itself (`GET /admin-api/rooms/:roomId` calls `Room#getInspectorView()`). Each entry carries the `sessionId` and the join time. When your `onAuth` returned a user, the entry also carries the `userId` / `userEmail` read from `client.auth`, and the email links to the user's show page. A green dot marks sessions whose id appears as a key in the state tree.

## Actions

Every mutation listed here is recorded to the [audit log](https://docs.colyseus.io/admin/resources.md#audit-log) with `resource: "rooms"` and the room id as `target_id`. The payload always includes the operator's `ip` and `userAgent` next to the fields named below.

### Kick a client

Drop a single client from a room with an optional reason (120 characters max). The room closes the connection with code `4000` (`CloseCode.CONSENTED`) and the reason in the close frame. On the client, `room.onLeave((code, reason) => …)` runs and the SDK does not try to reconnect. On the server, the `onLeave` hook sees a consented leave.

![The kick confirmation dialog with the optional reason field](https://docs.colyseus.io/admin/kick-dialog.webp)

Records `action: "room.kick"` with payload `{ sessionId, reason }`.

### Lock / unlock

Toggle the room's `locked` flag through `Room#lock()` / `Room#unlock()`. Locked rooms are skipped by the matchmaker and `joinById` fails on them. Locking is useful for draining a room (let current clients finish; no new joins) or holding it for a private match.

Records `action: "room.lock"` or `"room.unlock"`.

### Edit state

The detail page renders the room's state tree as JSON. Click a leaf value to change it in place, or remove an entry from a map or array. Edits are applied to the live `Schema` instance inside the room process, so they reach every connected client on the next patch. The editor is deliberately narrow. You can change leaf values and delete entries; you cannot add keys, change a value's type, or replace a whole object. Direct edits are useful for adjusting in-flight match state (revert a bug, grant a permission, set a flag) without a server restart.

> **Warning:**
>
> State edits are immediate and broadcast to all connected clients. A path that does not resolve is a silent no-op: the request still answers `200` and writes an audit row. Use sparingly and prefer adding a dedicated custom action for repeatable workflows (see [Resources → Custom actions](https://docs.colyseus.io/admin/resources.md#custom-actions)).

Records `action: "room.state.edit"` with `{ path, value }`, or `action: "room.state.delete"` with `{ path }`. `path` is the array of keys from the root, for example `["racers", "T6eCaDKmv", "lap"]`.

### Force-dispose

Terminate a room immediately, regardless of its current state. The panel calls `Room#disconnect()` and returns without waiting for it, so the `200` arrives before the clients have actually closed. All clients are disconnected with `CloseCode.CONSENTED`; the room is removed from the matchmaker when its `onDispose` finishes.

Records `action: "room.dispose"`, also when the room was already gone.

## REST endpoints

| Method | Path | Body | Gate | Audit action |
|---|---|---|---|---|
| `GET` | `/admin-api/rooms` | — | `list` | — |
| `GET` | `/admin-api/rooms/:roomId` | — | `read` | — |
| `GET` | `/admin-api/rooms/by-user/:userId` | — | `read` | — |
| `DELETE` | `/admin-api/rooms/:roomId/clients/:sessionId` | `{ reason? }` | `update` | `room.kick` |
| `PATCH` | `/admin-api/rooms/:roomId` | `{ locked: boolean }` | `update` | `room.lock` / `room.unlock` |
| `PATCH` | `/admin-api/rooms/:roomId/state` | `{ path, value }` | `update` | `room.state.edit` |
| `DELETE` | `/admin-api/rooms/:roomId/state` | `{ path }` | `update` | `room.state.delete` |
| `DELETE` | `/admin-api/rooms/:roomId` | — | `delete` | `room.dispose` |

`by-user` lists the rooms a user is currently connected to (`{ roomId, roomName, sessionId, joinedAt, processId }`, newest first) and powers the **Active sessions** tab on the user's show page. It reads the index that [`TrackUserSessionsPlugin`](https://docs.colyseus.io/room/plugins/track-user-sessions.md) maintains, so rooms without that plugin never appear there. A room that is not reachable answers `404`.

```sh
# lock a room, then kick one client with a reason
curl -b cookies.txt -X PATCH http://localhost:2567/admin-api/rooms/QcxWRrptI \
     -H 'content-type: application/json' -d '{"locked":true}'
curl -b cookies.txt -X DELETE http://localhost:2567/admin-api/rooms/QcxWRrptI/clients/T6eCaDKmv \
     -H 'content-type: application/json' -d '{"reason":"Maintenance in 5 minutes"}'
```

## Multi-process visibility

Listing comes from `matchMaker.query()`, so the table shows whatever the [matchmaker driver](https://docs.colyseus.io/server/driver.md) knows. Every other call (inspect, kick, lock, state edits, dispose) goes through `matchMaker.remoteRoomCall()`, which reaches rooms on other processes over the [presence](https://docs.colyseus.io/server/presence.md) layer. Both have to be shared for the inspector to work across a cluster:

| Driver | Presence | Result |
|---|---|---|
| `LocalDriver` (default) | `LocalPresence` (default) | Only rooms on the current process. Fine for development. |
| `RedisDriver`, `PostgresDriver`, `MongooseDriver`, or `DatabaseDriver` from `@colyseus/database` | `LocalPresence` | Every room is listed, but rooms on other processes answer `404` on the detail page and every action times out. |
| Any shared driver | `RedisPresence` | All rooms across all processes, fully operable. Recommended for production. |

If you don't see rooms you expect, confirm the driver is shared across processes. If you see them but can't open them, confirm the presence is shared too.

## RBAC

The inspector uses a synthetic `rooms` resource for the standard role rules:

- **Admin**: full read + all actions.
- **Mod**: no access without the `rooms` scope. Assign with `db.moderation.assignMod(userId, "rooms")`. Scoped mods get read plus kick, lock and state edits. Dispose stays admin-only (it maps to the `delete` action, which mods never have).
- **User**: cannot open the panel UI (403), but the list and inspect endpoints still answer.

> **Warning:**
>
> The `user` role passes the `list` and `read` gates. Any registered player who can sign in at `/admin-api/auth/login` can therefore open every room. The answer includes live state, metadata, and the emails of the connected clients. See [Authentication → Roles](https://docs.colyseus.io/admin/authentication.md#roles) for the mitigation until the package closes this.

## Next steps

- [Resources & CRUD](https://docs.colyseus.io/admin/resources.md): custom actions, policies, and the audit log.
- [Authentication & RBAC](https://docs.colyseus.io/admin/authentication.md): sessions and role assignment.
- [Server → Driver](https://docs.colyseus.io/server/driver.md) and [Server → Presence](https://docs.colyseus.io/server/presence.md): the two pieces that decide cluster-wide visibility.

---
Source: https://docs.colyseus.io/admin/rooms


# Authentication

Colyseus authenticates clients on two surfaces: **room joins** (via an `onAuth` hook) and **HTTP routes** (via middleware). The official [`@colyseus/auth`](https://docs.colyseus.io/auth/module.md) module powers both surfaces and pairs with [`@colyseus/database`](https://docs.colyseus.io/database.md) for a zero-config user store, automatic route mounting, and revocation-aware sessions.

> **Note:**
>
> **Fastest setup:** add a `GameDatabase` to `defineServer` and `@colyseus/auth` wires itself: user store, register/login routes, ban gating, and revocation-aware JWTs, all from one option. → [Database → Authentication](https://docs.colyseus.io/database/authentication.md)

## Common scenarios

- [Authenticate a room join](https://docs.colyseus.io/auth/room.md): Verify JWTs and reject revoked sessions in your room's `onAuth` hook. The database integration handles revocation automatically.
- [Protect an HTTP endpoint](https://docs.colyseus.io/auth/http.md): Gate any HTTP route behind a valid JWT with `auth.middleware()`, which works for both Express handlers and the typed `createEndpoint` HTTP routes.
- [Revoke a session or force-logout](https://docs.colyseus.io/database/authentication.md): Atomic ban with `tokenVersion` bump (existing JWTs rejected on the next room join), or call `bumpTokenVersion()` standalone for non-ban revocations like password change.
- [Bring your own database](https://docs.colyseus.io/auth/module.md#backend-api): Implement `@colyseus/auth`'s backend callbacks against your own storage. The `@colyseus/database` integration is optional. Every flow works without it.
- [OAuth, anonymous login, password reset](https://docs.colyseus.io/auth/module.md): 200+ OAuth providers (Discord, Google, X, …), anonymous registration, and forgot/reset password flows with customizable email templates.
- [Customize individual callbacks](https://docs.colyseus.io/database/authentication.md#customizing-callbacks): Override specific hooks (e.g. add an invite-code check on registration) while keeping the rest of the database integration intact.
- [Use the frontend client SDK](https://docs.colyseus.io/auth/module.md#frontend-api): Typed client methods for register, sign-in (email/password, anonymous, OAuth), password reset, and sign-out. The auth token is sent automatically.

---

## Next Steps

- [Database](https://docs.colyseus.io/database.md) - The zero-config user store behind `@colyseus/auth`
- [Room Lifecycle → On Auth](https://docs.colyseus.io/room/lifecycle.md#on-auth) - The hook where room-join authentication runs
- [Admin Panel](https://docs.colyseus.io/admin.md) - Inspect users and revoke sessions from a dashboard

---
Source: https://docs.colyseus.io/auth


# HTTP Middleware

If you are using the HTTP API, you can authenticate your requests using the `Authorization` header.

## Client SDK: Set the auth token

```js filename="client.js"
// set the auth token
client.auth.token = "YOUR AUTH TOKEN";
```

> **Note:**
>
> If you are using the `@colyseus/auth` module, this token is managed automatically. See [Authentication → Module](https://docs.colyseus.io/auth/module.md).

## Client SDK: Make HTTP requests

The HTTP requests contain the auth token in the `Authorization` header.

```js filename="client.js"
client.http.get("/profile").then((response) => {
    console.log(response.data);
});
```

## Server: Validate the auth token

If you are using the `@colyseus/auth` module, `auth.middleware()` works in both the [HTTP Routes](https://docs.colyseus.io/server/http-routes.md) system (`createEndpoint` / `createMiddleware`) and as an Express middleware. The decoded JWT payload is exposed on `ctx.context.auth` (HTTP routes) or `req.auth` (Express).

**HTTP Routes (createEndpoint)**

```ts filename="src/endpoints/profile.ts"
import { createEndpoint } from "colyseus";
import { auth } from "@colyseus/auth";

export const profile = createEndpoint("/profile", {
    method: "GET",
    use: [auth.middleware()],
}, async (ctx) => {
    console.log("authenticated user:", ctx.context.auth);
    return ctx.context.auth;
});
```

    See [HTTP Routes](https://docs.colyseus.io/server/http-routes.md) for how endpoints are mounted via `createRouter`.

**Express middleware**

```ts filename="src/app.config.ts"
import { defineServer } from "colyseus";
import { auth } from "@colyseus/auth";

const server = defineServer({
    // ...
    express: (app) => {
        app.use("/profile", auth.middleware(), (req, res) => {
            console.log("authenticated user:", req.auth);
            res.json(req.auth);
        });
    }
    // ...
});
```

**Custom authentication**

```ts filename="src/app.config.ts"
function yourAuthMiddleware (req, res, next) {
    const authorization = req.headers.authorization;
    // TODO: validate the "authorization" token here
    next();
}

app.use("/profile", yourAuthMiddleware, (req, res) => {
    // handle the request
});
```

> **Warning:**
>
> `tokenVersion`-based revocation (`db.auth.ban()`, `db.auth.bumpTokenVersion()`) is enforced on **room joins**. `auth.middleware()` only verifies the JWT's signature and expiry. A revoked-but-unexpired token still passes HTTP routes; if a route must observe revocation immediately, check `db.auth.isBanned()` / the `tokenVersion` claim yourself inside the handler. See [Database → Authentication](https://docs.colyseus.io/database/authentication.md).

---
Source: https://docs.colyseus.io/auth/http


# Auth Module

> **Warning:**
>
> This module is in beta - Feedback is welcome on [colyseus/colyseus#660](https://github.com/colyseus/colyseus/issues/660).

> **Note:**
>
> **Using [`@colyseus/database`](https://docs.colyseus.io/database.md)?** It wires up the user store, registration/login routes, ban gating, and session revocation for you, so you can skip the user-store [Backend API](#backend-api) callbacks below. Email delivery (`onForgotPassword`, `onSendEmailConfirmation`, `onEmailConfirmed`) is still yours to wire. See [Database → Authentication](https://docs.colyseus.io/database/authentication.md) for the integration overview.

The `@colyseus/auth` module is highly configurable and allows you to implement your own authentication backend.

The module does not provide a database or email sending capabilities. Instead, it provides callbacks that you can implement to query your database, send emails, and handle OAuth providers.

- [Frontend API](#frontend-api)
- [Backend API](#backend-api)

## Features

- Frontend APIs (via `client.auth`)
- Email/Password Authentication
- Anonymous Authentication
- Forgot Password + Password Reset
- OAuth 2.0 providers (_200+ supported providers, including Discord, Google, Twitter, etc._)

> **Note:**
>
> **Example Project** - The [Webgame Template](https://github.com/colyseus/webgame-template) project contains a complete usage example of `@colyseus/auth` for both backend and frontend.

## Installation

Install the `@colyseus/auth` module:

```sh npm2yarn
npm install --save @colyseus/auth
```

### Bind the `auth` routes to Express

```ts filename="src/app.config.ts"
import { auth } from "@colyseus/auth";
import { defineServer } from "colyseus";

const server = defineServer({
// ...
    express: (app) => {
        // ...
        app.use(auth.prefix, auth.routes());
        // ...
    },
// ...
});
```

### Required Environment Secrets

It is required to provide the following environment variables to your application:

- `JWT_SECRET` - Used to sign the JWT token.
- `SESSION_SECRET` - Used to sign the OAuth state cookie. Recommended for OAuth; falls back to `JWT_SECRET` when unset.

> **Note:**
>
> **How to generate a random string** - You may use the following command to generate a random string `openssl rand -base64 32`. Alternatively, you can use [an online strong password generator](https://1password.com/password-generator/).

> **Warning:**
>
> **`AUTH_SALT` is legacy.** Required only when upgrading an existing deployment from a version prior to 0.18. The legacy `scrypt`-based hasher reads it to verify passwords created before the upgrade. New 0.18 projects don't need it; the default hasher derives its own per-password salt.

> **Important:**
>
> **Keep Your Secrets Safe!**
>
> The exposure of these secrets may lead to security breaches on your application. Make sure to never expose them publicly, and limit the number of people in your team who have access to them.
>
> If any of these secrets are compromised, you must rotate them immediately. The implications of rotating them are:
>
> - Rotating `JWT_SECRET` will invalidate all JWT tokens. Users will need to login again.
> - Rotating `SESSION_SECRET` will invalidate all session cookies. (only used during OAuth flow)
> - Rotating `AUTH_SALT` (legacy upgrades only) will invalidate every pre-upgrade password hash. Users created before the upgrade will need to reset their password.

### Backend Configuration

Create a configuration file for the `@colyseus/auth` module. The following example shows how to configure the module to use a fake database. You should replace the methods with your own database queries.

```ts filename="src/config/auth.ts"
import { auth } from "@colyseus/auth";

auth.backend_url = "http://localhost:2567";

const fakeDatabase = [];

auth.settings.onFindUserByEmail = async function (email) {
    return fakeDatabase.find((entry) => entry.email === email);
}

auth.settings.onRegisterWithEmailAndPassword = async function (email, password, options) {
    const entry = { email, password, ...options };
    fakeDatabase.push(entry);
    return entry;
}

auth.settings.onRegisterAnonymously = async function (options) {
    const anonymousEntry = { anonymous: true, ...options };
    return anonymousEntry;
}

auth.settings.onForgotPassword = async function (email: string, html: string/* , resetLink: string */) {
    await resend.emails.send({
        to: email,
        subject: '[Your project]: Reset password',
        from: 'xxx@your-game.io',
        html: html
    });
}

auth.settings.onResetPassword = async function (email: string, password: string) {
    const entry = fakeDatabase.find((entry) => entry.email === email);
    entry.password = password;
    return true;
}

auth.settings.onSendEmailConfirmation = async function(email, html, link) {
    await resend.emails.send({
        to: email,
        subject: '[Your project]: Confirm your email address',
        from: 'no-reply@your-game.io',
        html: html
    });
}

auth.settings.onEmailConfirmed = async function(email) {
    const entry = fakeDatabase.find((entry) => entry.email === email);
    entry.verified = true;
    return true;
}

auth.oauth.addProvider('discord', {
    key: "XXXXXXXXXXXXXXXXXX", // Client ID
    secret: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", // Client Secret
    scope: ['identify', 'email'],
});
```

---

## Frontend API

### Register With Email and Password

Register a new user with email/password and return userdata. The user will be automatically logged in after registration. This method modifies the `client.auth.token` property.

The `options` argument may contain user data you can use when creating the user's account.

**Client API**

```js
try {
    const userdata = await client.auth.registerWithEmailAndPassword(email, password);
    console.log(userdata);

} catch (e) {
    console.error(e.message);
}
```

**Backend config**

```ts filename="src/config/auth.ts"
import { auth } from "@colyseus/auth";
// ...

auth.settings.onFindUserByEmail = async function (email) {
    return await User.query().selectAll().where("email", "=", email).executeTakeFirst();
}

auth.settings.onRegisterWithEmailAndPassword = async function (email, password, options) {
    return await User.insert({ email, password });
}
```

### Sign In With Email and Password

Sign in with email/password and return userdata. This method modifies the `client.auth.token` property.

**Client API**

```js filename="client.js"
try {
    const userdata = await client.auth.signInWithEmailAndPassword(email, password);
    console.log(userdata);

} catch (e) {
    console.error(e.message);
}
```

**Backend config**

```ts filename="src/config/auth.ts"
import { auth } from "@colyseus/auth";
// ...

auth.settings.onFindUserByEmail = async function (email) {
    return await User.query().selectAll().where("email", "=", email).executeTakeFirst();
}
```

### Sign In Anonymously

Sign in anonymously and return anonymous userdata. This method modifies the `client.auth.token` property.

**Client API**

```js filename="client.js"
try {
    const userdata = await client.auth.signInAnonymously();
    console.log(userdata);

} catch (e) {
    console.error(e.message);
}
```

**Backend config**

```ts filename="src/config/auth.ts"
import { auth } from "@colyseus/auth";
// ...

auth.settings.onRegisterAnonymously = async function (options) {
    const userId = await User.insert({ anonymous: true });
    return { userId };
}
```

### Sign In With OAuth Provider

Sign in with OAuth provider and return userdata. This method modifies the `client.auth.token` property.

**Client API**

```js filename="client.js"
try {
    const userdata = await client.auth.signInWithProvider('discord');
    console.log(userdata);

} catch (e) {
    console.error(e.message);
}
```

**Backend config**

Each provider requires a different configuration. See the [OAuth providers](#oauth-providers-discord-google-x-etc) section for more information.

```ts filename="src/config/auth.ts"
import { auth } from "@colyseus/auth";
// ...
auth.oauth.addProvider('[PROVIDER-ID]', {
    key: "XXXXXXXXXXXXXXXXXX", // Client ID
    secret: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", // Client Secret
    scope: ['identify', 'email'],
});
```

> **Note:**
>
> **The OAuth Authentication Flow**
>
> - A popup window opens `/auth/provider/[PROVIDER-ID]`
> - The user is redirected to the OAuth provider's website
> - The user authenticates with the OAuth provider
> - The user is redirected back to `/auth/provider/[PROVIDER-ID]/callback` (see [OAuth Provider Callback](#oauth-callback))
> - The popup window is closed and userdata is returned

### Send Password Reset Email

Send an email to the user with a link to reset their password.

**Client API**

```js filename="client.js"
try {
    const result = await client.auth.sendPasswordResetEmail('user@domain.io');
    console.log(result);

} catch (e) {
    console.error(e.message);
}
```

**Backend config**

```ts filename="src/config/auth.ts"
import { auth } from "@colyseus/auth";
// ...

auth.settings.onForgotPassword = async function (email: string, html: string/* , resetLink: string */) {
    await resend.emails.send({
        to: email,
        subject: '[Your project]: Reset password',
        from: 'no-reply@your-domain.io',
        html: html
    });
}
```

### Get User Data

Get the current user's data. This method does not modify the `client.auth.token` property.

**Client API**

Fetch the current user's data from the server.

```js filename="client.js"
try {
    const userdata = await client.auth.getUserData();
    console.log(userdata);

} catch (e) {
    console.error(e.message);
}
```

**Backend config**

You may customize the `onParseToken` callback to include additional user data for the frontend.

```ts filename="src/config/auth.ts"
import { auth } from "@colyseus/auth";
// ...

auth.settings.onParseToken = async function (userdata) {
    return userdata;
}
```

### On Auth State Change

Define a callback that is triggered when internal auth state changes. It only triggers as a response from `client.auth` method calls - this is not a realtime subscription.

```ts filename="client.js"
client.auth.onChange(function(authData) {
    console.log(authData.user);
    console.log(authData.token);
});
```

### Sign Out

Clear the authentication token from the frontend.

```typescript
client.auth.signOut();
```

### Auth Token

The authentication token is automatically sent to the server on every request. Operations that result in a user being logged in will set the `client.auth.token` property, which is a JWT token containing the user's data. The contents of this token are

```ts filename="client.ts"
client.auth.token = "xxxx";
```

> **Note:**
>
> The JWT token is stored in the `localStorage` of the browser.

---

## Backend API

Implement these callbacks when you're bringing your own database. With [`@colyseus/database`](https://docs.colyseus.io/database.md), they're wired automatically. See [Database & Persistence → Authentication](https://docs.colyseus.io/database/authentication.md).

### Backend URL

The public backend URL. Setting `auth.backend_url` is recommended for security. The value is auto-detected upon the first request if not set.

The backend URL is used to:

- Redirect the user to reset their password
- Redirect the user to confirm their email address
- Build the OAuth provider's callback URL

 ```ts filename="src/config/auth.ts"
 import { auth } from "@colyseus/auth";
 
 if (process.env.NODE_ENV === "production") {
    auth.backend_url = "https://your-game.io";
 
 } else {
    auth.backend_url = "http://localhost:2567";
 }
 ```

### Email/Password Authentication

In order to allow email/password authentication, you must implement the following callbacks:

- `auth.settings.onFindUserByEmail`: to query your database for the user's by its email address
- `auth.settings.onRegisterWithEmailAndPassword`: to insert a new user into your database

#### On Find User By Email

Use this callback to query your database for the user's by its email address. (The database module is not provided by this module, you must provide your own.)

**Return value**: The function should return the user entry from the database, including the `password` field. All fields except `password` will be encoded in the JWT token. At minimum, return the user's `id` and `password`, though additional fields can be included for convenience

**Error**: If the function returns `null` or `undefined`, the user will receive an `invalid_credentials` error. Alternatively, you can throw a custom error using `throw new Error("your_error_message")`.

```typescript
import { auth } from "@colyseus/auth";

auth.settings.onFindUserByEmail = async function (email) {
    return await User.query().selectAll().where("email", "=", email).executeTakeFirst();
}
```

### On Register With Email And Password

Use this callback to insert a new user into your database.

The password provided is already hashed (with `Hash.make`). To change the hashing algorithm, set [`Hash.algorithm`](#on-hash-password).

If an error is thrown, its message will be sent to the client.

```typescript
import { auth } from "@colyseus/auth";

auth.settings.onRegisterWithEmailAndPassword = async function (email, password, options) {
    return await User.insert({ email, password });
}
```

### Anonymous Authentication

Anonymous authentication is enabled by default. You may customize how the anonymous user is created by providing the `onRegisterAnonymously` callback.

By default, the anonymous user will have the following fields on its JWT token payload:

```typescript
{
  "anonymous": true
  "anonymousId": "vRSN1FbtZx5uo19hKSqA1", // 21 characters
}
```

#### On Register Anonymously

You may use this callback to customize the JWT token payload for anonymous users. The fields returned by this callback will be available in the JWT token as payload.

On the example below the anonymous user is being inserted into the database, and its `userId` is being returned as payload.

```typescript
import { generateId } from "colyseus";
import { auth } from "@colyseus/auth";

auth.settings.onRegisterAnonymously = async function (options) {
    const userId = await User.insert({ anonymous: true });
    return { userId };
}
```

### Email Verification

You may enable email verification by providing both `onSendEmailConfirmation` and `onEmailConfirmed` callbacks.

You are responsible for limiting user access to your application until their email is verified.

> **Note:**
>
> **Email verification is not mandatory** - Users are allowed to login without verifying their email address. If you require email verification, you must validate if the user's email is verified on your application.

#### On Send Email Confirmation

Use this callback to send the email verification to the user.

| Argument | Description |
|------|-------------|
| `email` | the email address of the user |
| `html` | the HTML contents of the email (uses the `address-confirmation-email.html` template) |
| `link` | the URL to confirm the email address (optional, the template already includes this URL) |

```typescript
import { auth } from "@colyseus/auth";

auth.settings.onSendEmailConfirmation = async function(email, html, link) {
    // send email to the user (example using resend.com)
    await resend.emails.send({
        to: email,
        subject: '[Your project]: Confirm your email address',
        from: 'no-reply@your-domain.io',
        html: htmlContents,
    });
}
```

#### On Email Confirmed

Use this callback to update the user's database record as verified.

| Argument | Description |
|------|-------------|
| `email` | the email address of the user |

```typescript
import { auth } from "@colyseus/auth";

auth.settings.onEmailConfirmed = async function(email) {
    // update user database record as verified
    await User.update({ verified: true }).where("email", "=", email).execute();
}
```

### Forgot Password

To enable "Forgot Password" feature, you must provide the following callbacks:

- `auth.settings.onForgotPassword`: to send the email to the user
- `auth.settings.onResetPassword`: to update the user's password

> **Note:**
>
> The link to reset the password is sent to the user's email address. The link contains a JWT token with the user's email address as payload. The user is then redirected to a page where they can enter a new password. The token expires in 30 minutes and can't be re-used.

#### On Forgot Password

Use this callback to send the "forgot password" email to the user. The email template used is `reset-password-email.html`.

```typescript
import { auth } from "@colyseus/auth";

auth.settings.onForgotPassword = async function (email: string, html: string/* , resetLink: string */) {
  await resend.emails.send({
    to: email,
    subject: '[Your project]: Reset password',
    from: 'no-reply@your-domain.io',
    html: html
  });
}
```

#### On Reset Password

Use this callback to update the user's password. The password is already hashed.

```typescript
import { auth } from "@colyseus/auth";

auth.settings.onResetPassword = async function (email: string, password: string) {
  await User.update({ password }).where("email", "=", email).execute();
}
```

### OAuth Providers (Discord, Google, X, etc)

In order to enable OAuth authentication, you must add at least one OAuth provider, and implement the [OAuth Callback](#oauth-callback) callback.

> **Note:**
>
> **200+ OAuth 2.0 providers supported**
>
> This module leverages the hard work of [simov](https://github.com/simov/) on his [grant](https://github.com/simov/grant) open-source module, which supports 200+ OAuth 2.0 providers.
>
> Check out the original [Grant Playground](https://grant.outofindex.com/) to experiment with scopes and OAuth configuration.

#### Add OAuth Provider

Add an OAuth provider to the authentication module.

| Argument | Description |
|------|-------------|
| `providerId` | the provider ID (e.g. "discord", "google", "twitter", etc) |
| `config` | the provider options, may vary depending on the provider (see below) |

```typescript
import { auth } from "@colyseus/auth";

auth.oauth.addProvider('[PROVIDER-ID]', {
  key: "XXXXXXXXXXXXXXXXXX", // Client ID
  secret: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", // Client Secret
  scope: ['identify', 'email'],
});
```

#### OAuth Callback

Register a callback to handle the OAuth provider's response.

The callback should return the user's data, which will be stored in the JWT token.

| Argument | Description |
|------|-------------|
| `data` | the OAuth data (e.g. `profile`, `access_token`, etc) |
| `providerId` | the provider ID (e.g. `"discord"`, `"google"`, `"twitter"`, etc) |

You must configure the "Redirect URL" on the OAuth provider's dashboard to point to the following URL:

```
https://[YOUR-DOMAIN]/auth/provider/[PROVIDER-ID]/callback
```

> **Note:**
>
> **Redirect URL on different environments** - It is recommended that you create a different OAuth application for development and production environments. This way you can configure the "Redirect URL" to point to `http://localhost:2567/auth/provider/[PROVIDER-ID]/callback` during development, and `https://[YOUR-DOMAIN]/auth/provider/[PROVIDER-ID]/callback` on production.

```typescript
import { auth } from "@colyseus/auth";

auth.oauth.onCallback(async (data, provider) => {
    const profile = data.profile;
    return await User.upsert({
        discord_id: profile.id,
        name: profile.global_name || profile.username,
        locale: profile.locale,
        email: profile.email,
    });
});
```

**Example: Discord**

To enable Discord authentication, you must create a new application at [Discord Developer Portal](https://discord.com/developers/applications).

    Under the _"Settings -> OAuth2"_ you will find the Client ID (`key`) and Client Secret (`secret`), that must be used to configure the provider:

```ts filename="src/config/auth.ts"
auth.oauth.addProvider('discord', {
    key: "XXXXXXXXXXXXXXXXXX", // Client ID
    secret: "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", // Client Secret
    scope: ['identify', 'email'],
});
```

    You will also need to configure the "Redirect URL" so Discord can redirect the user back to your application after authentication. The URL must be in the following format:

```
https://[YOUR-DOMAIN]/auth/provider/discord/callback
```

---

### Advanced Settings

You may customize the following settings:

- `auth.settings.onParseToken`: to parse JWT token provided by the frontend
- `auth.settings.onGenerateToken`: to generate the auth token

#### On Parse Token

Use this callback to modify the user's data before sending it to the frontend during the [Get User Data](#get-user-data) call.

```typescript
import { auth } from "@colyseus/auth";

auth.settings.onParseToken = async function (data) {
    return data;
}
```

#### On Generate Token

Use this callback to customize the token generation from the user's data.

```typescript
import { auth, JWT } from "@colyseus/auth";

auth.settings.onGenerateToken = async function (userdata) {
    return JWT.sign(userdata);
}
```

#### On Hash Password

Password hashing is customized through the `Hash` class. The default algorithm is `scrypt`, with `sha1` available as the only other built-in:

```ts filename="src/config/auth.ts"
import { Hash } from "@colyseus/auth";

Hash.algorithm = "sha1"; // default: "scrypt"
```

> **Warning:**
>
> The `auth.settings.onHashPassword` callback exists on the settings object but is **not invoked by any endpoint in 0.18**, so overriding it has no effect. Use `Hash.algorithm` / `Hash.algorithms` instead.

---

### Protecting an HTTP route

You may protect an HTTP route via the `auth.middleware()` middleware. Only authenticated users will be able to access the route.

```typescript
app.get("/protected", auth.middleware(), (req: Request, res) => {
    res.json(req.auth);
});
```

---

### Customizing the Email Templates

If you need to customize the email templates, you must provide your own templates under the `html` directory. You can copy the default templates from the `@colyseus/auth` package, and modify them as needed.

```
my-colyseus-app/
  src/
    ...
    index.ts
  html/
    address-confirmation-email.html
    address-confirmation.html
    reset-password-email.html
    reset-password-form.html
  package.json
```

#### Email Confirmation Template

This template is used to send the email confirmation link to the user when they register with email/password. When the user clicks on the link, they are redirected to the _Email Confirmation Page_.

- [ Email Template ↗](https://github.com/colyseus/colyseus/tree/master/packages/auth/html/address-confirmation-email.html) - (`html/address-confirmation-email.html`)
- [ Web Page Template ↗](https://github.com/colyseus/colyseus/tree/master/packages/auth/html/address-confirmation.html) - (`html/address-confirmation.html`)

#### Reset Password Template

This template is used to send the reset password link to the user when they request to reset their password. When the user clicks on the link, they are redirected to the _Reset Password Page_.

-  [ Email Template ↗](https://github.com/colyseus/colyseus/tree/master/packages/auth/html/reset-password-email.html) - (`html/reset-password-email.html` )
-  [ Web Page Template ↗](https://github.com/colyseus/colyseus/tree/master/packages/auth/html/reset-password-form.html) - (`html/reset-password-form.html`)

---

### Upgrading and Linking User Accounts

You may use the contents of the previous active auth token (`upgradingToken`) when registering an user via email/password or OAuth.

- Upgrade an anonymous user to an email/password or OAuth account
- Link multiple OAuth providers to the same account

**Upgrade with email/password**

```ts filename="src/config/auth.ts"
import { auth } from "@colyseus/auth";

auth.settings.onRegisterWithEmailAndPassword = async function (email, password, options) {
    /**
     * options.upgradingToken contains the previous token payload
     * you can use its contents to link the user's account
     */
    options.upgradingToken
}
```

**Upgrade with OAuth provider**

```ts filename="src/config/auth.ts"
import { auth } from "@colyseus/auth";

auth.oauth.onCallback(async (data, provider) => {
    /**
     * data.upgradingToken contains the previous token payload
     * you can use its contents to link the user's account
     */
    data.upgradingToken
});
```

---
Source: https://docs.colyseus.io/auth/module


# Room Authentication

You can authenticate your users using the `onAuth` method in your room. This method is called before `onJoin`, and it is responsible for validating the client's request to join a room.

- If `onAuth()` returns a [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy) value, `onJoin()` is going to be called with the returned value as the third argument.
- If `onAuth()` returns a [falsy](https://developer.mozilla.org/en-US/docs/Glossary/Falsy) value, the client is immediatelly rejected, causing the matchmaking function call from the frontend to fail.
- You may also throw a `ServerError` to expose a custom error to be handled in the frontend.

With the `colyseus` bundle (which includes `@colyseus/auth`), the default **static** `onAuth` verifies the client's JWT. A malformed or expired token is rejected with `AUTH_FAILED`. A client that sends no token passes through with no auth data.

> **Warning:**
>
> **Static `onAuth` runs first, and short-circuits the instance `onAuth`.** The static hook runs at matchmake time, and whatever it returns becomes `client.auth`. When it produced a payload (any token-bearing client), the **instance** `onAuth` is skipped entirely. Override the *static* `onAuth` when you need custom token validation; use the instance form only for rooms whose clients join without tokens.

> **Note:**
>
> **Using [`@colyseus/database`](https://docs.colyseus.io/database.md)?** The default static `onAuth` also enforces `tokenVersion`-based revocation. `db.auth.ban()` and `db.auth.bumpTokenVersion()` both reject stale tokens on the next room join. See [Database → Authentication](https://docs.colyseus.io/database/authentication.md).

## Server: `onAuth` method

**Static onAuth (recommended)**

The `static onAuth` is recommended because it does not require the room instance to be created before authenticating the client.

    > **Note:**
>
> If you need to access the room instance during the authentication process, use the instance `onAuth` method.

```ts {5} filename="src/rooms/MyRoom.ts"
import { Room } from "colyseus";
import { JWT } from "@colyseus/auth";

class MyRoom extends Room {
    static async onAuth (token, options, context) {
        // validate the token
        const userdata = await JWT.verify(token);

        // return userdata
        return userdata;
    }
}
```

**Instance onAuth**

The instance `onAuth` method is called after the room instance is created, so it can read room properties: connected clients, room state. Remember it only runs when the static `onAuth` produced no payload (see the warning above), so use it for room-specific checks on token-less clients, not for token validation:

```ts {5} filename="src/rooms/MyRoom.ts"
import { Room, ServerError } from "colyseus";

class MyRoom extends Room {
    async onAuth (client, options, context) {
        // room-specific gate, e.g. reject spectators once the match started
        if (this.state.phase !== "lobby" && !options.spectator) {
            throw new ServerError(400, "match already in progress");
        }
        return true;
    }
}
```

## Server: `onJoin` method

Get the user data during the `onJoin` method via the `client.auth` property.

```ts {5} filename="src/rooms/MyRoom.ts"
import { Room } from "colyseus";
// ...
class MyRoom extends Room {
    // ...
    async onJoin (client, options, auth) {
        console.log(auth); // contains the "userdata" returned by onAuth
        console.log(client.auth); // shorthand/equivalent to `auth`
    }
}
```

## Client SDK: Setting the auth token

The `client.auth.token` property is used to set the authentication token. This token will be sent as an `Authorization` header in all HTTP requests to the server.

```js filename="client.js"
// set the auth token
client.auth.token = "YOUR AUTH TOKEN";
```

> **Note:**
>
> If you are using the `@colyseus/auth` module, this token is managed automatically. See [Authentication → Module](https://docs.colyseus.io/auth/module.md).

## Client SDK: Requesting to join a Room

Matchmaking requests will contain the auth token.

```js filename="client.js"
client.joinOrCreate("my_room").then((room) => {
    console.log(room);
});
```

## With `@colyseus/database`

When the [`@colyseus/database`](https://docs.colyseus.io/database/authentication.md) integration is active, the default `onAuth` verifies the JWT and enforces `tokenVersion`-based revocation. Bans and explicit `bumpTokenVersion()` calls both reject stale tokens automatically. Override the **static** `onAuth` only for room-specific logic (for example, surfacing the ban reason in the close frame instead of a generic AUTH_FAILED). Note that overriding it replaces the default, so you re-do the token verification yourself:

```ts {2-3,7-13} filename="src/rooms/MyRoom.ts"
import { Room, ServerError } from "colyseus";
import { JWT } from "@colyseus/auth";
import { db } from "../app.config";

class MyRoom extends Room {
    static async onAuth(token, options, context) {
        const payload = await JWT.verify(token); // throws on invalid/expired
        const { banned, reason } = await db.auth.isBanned(payload.id);
        if (banned) {
            throw new ServerError(403, reason ?? "You are banned.");
        }
        return payload; // becomes client.auth
    }
}
```

## `onAuth` Context

The third argument of the `onAuth` method is the `context` object. Both `static onAuth` and `onAuth` methods receive the same `context` object as the third argument.

The `context` object has the following properties:

- `context.token` - the authentication token sent by the client.
- `context.headers` - the headers sent by the client.
- `context.ip` - the IP address of the client.
- `context.req` - the matchmaking HTTP request, on `static onAuth` only.

### Accessing the Auth Token

The authentication token is available in the `context.token` property.

```ts {3} filename="src/rooms/MyRoom.ts"
// ...
async onAuth(client, options, context) {
    console.log(context.token);
}
// ...
```

### Accessing the request headers

The request headers are available in the `context.headers` property.

```ts {3} filename="src/rooms/MyRoom.ts"
// ...
async onAuth(client, options, context) {
    console.log(context.headers);
}
// ...
```

### Accessing the client IP address

The client IP address is available in the `context.ip` property, as a single
address. Colyseus reads it from `x-real-ip`, then the first entry of
`x-forwarded-for`, then `x-client-ip`, and falls back to the address of the
connection itself. The property is `undefined` when no source provides one.

```ts {3} filename="src/rooms/MyRoom.ts"
// ...
async onAuth(client, options, context) {
    console.log(context.ip);
}
// ...
```

It contains the value of the `X-Real-IP` header, if available. If not, it falls back to the `X-Forwarded-For` header, and finally to the request object's `remoteAddress` property.

---
Source: https://docs.colyseus.io/auth/room


# Colyseus Cloud - Premium Managed Hosting

[Colyseus Cloud](https://cloud.colyseus.io/) provides a managed infrastructure for your Colyseus application, made by the same team behind Colyseus Framework.

Colyseus Cloud is the easiest way to deploy your Colyseus servers. Your server can be up and ready for production in less than 15 minutes.

Colyseus Cloud uses NGINX, PM2, and requires you to use the `defineServer()`
function from `colyseus` for easy integration with its infrastructure.

![Colyseus Cloud Dashboard](https://docs.colyseus.io/cloud/dashboard.png)

## Project template

In order to deploy your Colyseus application to Colyseus Cloud, you need to follow the project template from `npm create colyseus-app@latest` command:

![Project structure](https://docs.colyseus.io/cloud/project-structure.png)

The key important configurations the template provide are:

1. Usage of `defineServer()` from `colyseus` to start the application
2. An `ecosystem.config.js` file at the root of the project (with the `"script"` pointing to your application's entrypoint)

**src/app.config.ts**

```ts filename="src/app.config.ts"
import { defineServer, defineRoom } from "colyseus";
import { MyRoom } from "./rooms/MyRoom";

const server = defineServer({
    rooms: {
        my_room: defineRoom(MyRoom),
    },
    express: (app) => {
        // ...
    },
    beforeListen: () => {
        // ...
    }
});
```

**ecosystem.config.js**

```js {6} filename="ecosystem.config.js"
const os = require('os');

module.exports = {
    apps : [{
        name: "colyseus-app",
        script: 'build/index.js',
        time: true,
        watch: false,
        instances: os.cpus().length,
        exec_mode: 'fork',
        wait_ready: true,
    }],
};
```

---

## Deploying your application

From your terminal, run the following command to deploy your application to Colyseus Cloud.

```sh filename="Terminal"
npx @colyseus/cloud deploy
```

You will be redirected to your browser, where you will be asked to select which application you want to deploy.

To deploy on every push instead, connect your GitHub repository. See [Continuous Deployment](https://docs.colyseus.io/cloud/continuous-deployment.md).

The first deployment generates a `.colyseus-cloud.json` file at the root of your project with credentials capable of deploying your application in the future. Keep this file safe!

#### Available command-line options

- `--env [env]`: The deployment environment. Default is `production`. (The `.colyseus-cloud.json` file stores the configuration per environment.)
- `--remote [remote]`: Force a specific git remote to deploy from. Value is stored on `.colyseus-cloud.json`
- `--branch [branch]`: Force a specific git branch to deploy from. Value is stored on `.colyseus-cloud.json`
- `--reset`: Reset application selection for deployment
- `--preview`: Open web interface to preview the deployment.

---

## Customizing build steps

By default, Colyseus Cloud is going to build your backend code using the `build` script from your `package.json` file:

You may customize how your backend is built by updating the **"Build Command"** in your Colyseus Cloud application settings, under **"Build settings"**.

```json filename="package.json"
{
  "scripts": {
    "build": "tsc"
  }
}
```

---
Source: https://docs.colyseus.io/cloud


# Cloud API

The Colyseus Cloud API gives read-only access to what the dashboard shows: your applications' status, metrics, egress, deploys and logs, and your billing summary. Use it to feed your own dashboards or monitoring tools.

> **Note:**
>
> **Beta.** Every team can use the API. Tell us what you'd like it to cover at [support@colyseus.io](mailto:support@colyseus.io).

---

## Quickstart

### Create a token

Create a token under **API tokens** in the dashboard ([open your API tokens](https://cloud-prod.colyseus.io/settings/api-tokens)). It's shown only once, so keep it somewhere safe.

Run this, paste the token and press Enter. It keeps the token out of your shell history:

```sh filename="Terminal"
read -rs COLYSEUS_CLOUD_TOKEN && export COLYSEUS_CLOUD_TOKEN
```

### Find your application's slug

```sh filename="Terminal"
curl https://cloud-prod.colyseus.io/api/v1/applications \
  -H "Authorization: Bearer $COLYSEUS_CLOUD_TOKEN"
```

Each application's `slug`, such as `1234-my-game`, goes in the URLs of the other endpoints.

### Read its current metrics

```sh filename="Terminal"
curl https://cloud-prod.colyseus.io/api/v1/applications/1234-my-game/metrics/current \
  -H "Authorization: Bearer $COLYSEUS_CLOUD_TOKEN"
```

---

## Authentication

Owners and admins create tokens under **API tokens** in the dashboard. A token can read every application of the team and the team's billing summary, and nothing else: it cannot deploy or change settings.

A token is shown only once. It doesn't expire, but it stops working when the person who created it leaves the team, is removed from it, or stops being an owner or admin. Any owner or admin can also delete it, which revokes it immediately.

Send the token in the `Authorization` header, as `Bearer <token>`.

---

## Endpoints

The base URL is `https://cloud-prod.colyseus.io/api/v1`. All times are ISO 8601 in UTC. Applications are addressed by their slug, as returned by `/applications`. The slug stays the same when you rename the application.

| Endpoint | Returns |
|---|---|
| [`GET /applications`](#list-applications) | Your applications, with their regions, plans and instances. |
| [`GET /applications/{slug}/metrics/current`](#current-metrics) | Each instance's latest CCU, rooms, CPU, memory and processes. |
| [`GET /applications/{slug}/metrics`](#metrics-history) | The same per location, by minute or by day. |
| [`GET /applications/{slug}/egress`](#egress) | Network traffic per location and per day. |
| [`GET /applications/{slug}/deploys`](#deploys) | Recent deploys, and each one's output. |
| [`GET /billing`](#billing) | Your subscriptions and account balance. |
| [`GET /applications/{slug}/instances/{id}/logs`](#instance-logs) | An instance's latest server logs. |

### List applications

`GET /api/v1/applications`

Your team's applications, with their locations (region, endpoint, plan) and the instances in each location.

```json
{
  "data": [{
    "id": 1234,
    "slug": "1234-my-game",
    "name": "My Game",
    "maintenance_mode": false,
    "created_at": "2026-08-01T09:30:00Z",
    "locations": [{
      "id": 567,
      "region": { "code": "fra", "city": "Frankfurt", "country": "DE" },
      "status": "ready",
      "scale_strategy": "vertical",
      "endpoint": "https://de-fra-1a2b3c4d.colyseus.dev",
      "plan": { "vcpus": 1, "ram_mb": 1024, "transfer_gb": 1024 },
      "instances": [{
        "id": 890,
        "endpoint": "https://de-fra-1a2b3c4d.colyseus.dev",
        "status": "ready",
        "deploy_status": "deployed",
        "deployed_at": "2026-09-24T14:02:11Z"
      }]
    }]
  }]
}
```

Use `slug` in every application URL below, and an instance's `id` to read its [logs](#instance-logs).

`scale_strategy` is `vertical` (one instance) or `horizontal` (several instances behind a load balancer). A location's or instance's `status` is one of `pending`, `provisioning`, `installing`, `ready`, `error`, `destroying`, `resizing`, `unpaid` or `parked` (an application that hasn't deployed in its first month has its server removed until its first deploy). An instance's `deploy_status` takes the [deploy](#deploys) values, or is `null`. `endpoint` is `null` until the location or instance has an address.

`maintenance_mode` is `true` while the application's maintenance mode is on in the dashboard. `plan.transfer_gb` is the monthly transfer the plan includes per instance; [Egress](#egress) has your usage.

### Current metrics

`GET /api/v1/applications/{slug}/metrics/current`

Returns each instance's latest sample (instances report once a minute) and totals per location. In the totals, CCU and rooms are summed, while CPU and memory are the busiest instance's. An instance that hasn't reported in the last 5 minutes has `null` values and is left out of the totals. A location whose instances all went quiet has `null` totals.

```json
{
  "application": "1234-my-game",
  "window_minutes": 5,
  "locations": [{
    "id": 567,
    "region": "fra",
    "totals": { "ccu": 18, "rooms": 4, "cpu_percent": 12.5, "memory_percent": 41.2 },
    "instances": [{
      "id": 890,
      "sampled_at": "2026-09-25T10:41:00Z",
      "ccu": 18,
      "rooms": 4,
      "cpu_percent": 12.5,
      "memory_percent": 41.2,
      "processes": [{
        "id": 0,
        "status": "online",
        "started_at": "2026-09-24T14:02:05Z",
        "restarts": 0,
        "cpu_percent": 12.5,
        "memory_mb": 210.4,
        "ccu": 18,
        "rooms": 4,
        "node_version": "24.1.0"
      }]
    }]
  }]
}
```

`memory_percent` is relative to the plan's RAM (`plan.ram_mb` in `/applications`).

`processes` lists the instance's server processes as they last reported, like the Stats page: `status` is `online`, `launching`, `stopping`, `stopped`, `waiting restart` or `errored`, and `restarts` is the process manager's restart counter for it. It is empty when the instance hasn't reported in the last 5 minutes.

### Metrics history

`GET /api/v1/applications/{slug}/metrics`

| Parameter | Description |
|---|---|
| `resolution` | `minute` (default) or `day`. |
| `from`, `to` | ISO 8601 times. One without an offset is read as UTC. Defaults to the last 24 hours (`minute`) or the last 30 days (`day`). A `minute` window can span at most 24 hours. |
| `location_id` | Only this location. |

Each point covers one location, aggregated like the current totals: CCU and rooms are summed across instances, CPU and memory are the busiest instance's. A `day` point adds up each instance's own peak of that day. Its CCU can therefore exceed what the location reached at any single moment.

With `resolution=day`, `from` and `to` are whole days (a time of day is ignored), and `from`, `to` and each point's `time` are midnight UTC. `to` is inclusive at both resolutions.

Metrics are kept for 35 days. A `from` further back returns a `422`.

```json
{
  "application": "1234-my-game",
  "resolution": "minute",
  "from": "2026-09-24T10:41:00Z",
  "to": "2026-09-25T10:41:00Z",
  "locations": [{
    "id": 567,
    "region": "fra",
    "points": [
      { "time": "2026-09-24T10:41:00Z", "ccu": 20, "rooms": 5, "cpu_percent": 14.1, "memory_percent": 40.8 }
    ]
  }]
}
```

### Egress

`GET /api/v1/applications/{slug}/egress`

Network traffic per location and per day, summed across its instances.

| Parameter | Description |
|---|---|
| `from`, `to` | Dates (`YYYY-MM-DD`). Defaults to the last 30 days. Egress is kept for 35 days. |

```json
{
  "application": "1234-my-game",
  "from": "2026-08-31",
  "to": "2026-09-29",
  "collected_at": "2026-09-29T15:20:04Z",
  "locations": [{
    "id": 567,
    "region": "fra",
    "outgoing_bytes": 48318382080,
    "incoming_bytes": 5368709120,
    "days": [
      { "date": "2026-09-28", "outgoing_bytes": 1610612736, "incoming_bytes": 178956970 }
    ]
  }]
}
```

We copy these figures from our infrastructure provider every hour; `collected_at` says when, and is `null` before the first copy. The latest day keeps growing until it ends. Only instances' traffic is counted: a multi-instance location's load balancer isn't included. Egress is not billed.

### Deploys

`GET /api/v1/applications/{slug}/deploys?limit=20` lists the most recent deploys first. `limit` goes from 1 to 50.

```json
{
  "application": "1234-my-game",
  "data": [{
    "id": 4321,
    "status": "deployed",
    "branch": "main",
    "commit": "9fceb02",
    "message": "Fix matchmaking timeout",
    "started_at": "2026-09-24T14:00:03Z",
    "finished_at": "2026-09-24T14:02:11Z"
  }]
}
```

`status` is one of:

- `none`: no instance was ready to take the deploy.
- `enqueued`: queued, not started yet.
- `deploying`
- `deployed`
- `failed`: this includes a deploy superseded by a newer one before it finished.

`commit` is the short commit hash, as the dashboard shows it. `commit` and `message` are `null` until the deploy has fetched the code. `started_at` is when the deploy was triggered. `finished_at` is `null` until the deploy is `deployed` or `failed`.

`GET /api/v1/applications/{slug}/deploys/{id}` returns one deploy, under `data`, with one more field: `output`, the build and deploy output as plain text.

```json
{
  "data": {
    "id": 4321,
    "status": "deployed",
    "branch": "main",
    "commit": "9fceb02",
    "message": "Fix matchmaking timeout",
    "started_at": "2026-09-24T14:00:03Z",
    "finished_at": "2026-09-24T14:02:11Z",
    "output": "[00:01] Installing dependencies...\nadded 246 packages in 7s\n[00:09] Deployed."
  }
}
```

`output` follows a running deploy. It is kept for 30 days, and always for the application's 10 most recent deploys; past that, `output` is `null`. Deploys older than a year are deleted and return a `404`.

### Billing

`GET /api/v1/billing`

Your subscriptions and account balance, as on the Billing page.

```json
{
  "account": {
    "currency": "usd",
    "credit_balance": 25,
    "balance_due": 0,
    "unused_time_credit": 3.5
  },
  "applications": [{
    "id": 1234,
    "slug": "1234-my-game",
    "name": "My Game",
    "subscription": {
      "status": "active",
      "monthly_price": 18,
      "current_period_end": "2026-10-01T00:00:00Z",
      "cancel_at_period_end": false
    }
  }],
  "fetched_at": "2026-09-29T15:02:11Z"
}
```

- `account` is the billing account of your team's owner, so its balance is shared with any other team they own. It is `null` if the owner has no billing account yet.
- Amounts are in `account.currency` units (dollars, not cents). `credit_balance` is prepaid credit that pays future invoices; `balance_due` is owed and added to the next one. `unused_time_credit` comes from downgrades and cancellations, and applies to the next invoice.
- `subscription.status` is `active`, `past_due`, `unpaid`, `incomplete`, `incomplete_expired`, `trialing` or `canceled`, or the subscription is `null` if the application has none. `monthly_price` is the list price in `account.currency`, before discounts and taxes.

If billing information can't be fetched, you get a `503` with code `billing_unavailable`.

### Instance logs

`GET /api/v1/applications/{slug}/instances/{id}/logs`

The latest lines of an instance's server logs, as `text/plain`. Errors are still JSON.

| Parameter | Description |
|---|---|
| `lines` | Up to `500`. Rounded up to 100 or 500. Default `100`. |
| `stream` | `all` (default), `out` (stdout only) or `err` (stderr only). |

The response keeps the newest 256 KB of output, with colour codes stripped.

This endpoint reads the logs from the instance itself, so it allows 2 requests per minute per team, one at a time per instance. For continuous log collection, send your logs from your server code to your logging service instead.

---

## Limits and freshness

Responses are cached for as long as the data stays current, and their `Cache-Control` header says for how long. Polling faster than this returns the same data.

Every endpoint draws from one budget of 60 requests per minute per team, shared by all of the team's tokens. Metrics history and instance logs have a tighter limit of their own on top, and still count toward the 60.

| Endpoint | Refreshes every | Requests per minute |
|---|---|---|
| `/applications` | 60 s | 60, shared |
| `/metrics/current` | 30 s | 60, shared |
| `/metrics` | 60 s (`minute`), 10 min (`day`) | 10 |
| `/egress` | 10 min | 60, shared |
| `/deploys` | 15 s | 60, shared |
| `/billing` | 10 min | 60, shared |
| `/instances/{id}/logs` | 60 s | 2 |

Rate-limited responses carry `X-RateLimit-Limit` and `X-RateLimit-Remaining`, for the tightest limit on that endpoint. Past a limit, you get a `429` with a `Retry-After` header in seconds. A cached answer still counts toward the limit.

### Polling

Between requests, wait for as long as `Cache-Control` says. After a `429` or a `5xx`, wait for as long as `Retry-After` says. Wait at least a few seconds either way, in case a header is missing or isn't a number of seconds:

```js filename="poll.mjs"
const BASE_URL = "https://cloud-prod.colyseus.io/api/v1";
const headers = { Authorization: `Bearer ${process.env.COLYSEUS_CLOUD_TOKEN}` };

// at least 5 s, and the fallback when the header is missing or a date
const wait = (value, fallback) => Math.max(5, Number(value) || fallback);

async function poll(path, onData) {
  while (true) {
    const response = await fetch(BASE_URL + path, { headers });
    let seconds;

    if (response.ok) {
      onData(await response.json());
      seconds = wait(response.headers.get("cache-control")?.match(/max-age=(\d+)/)?.[1], 60);
    } else if (response.status === 429 || response.status >= 500) {
      seconds = wait(response.headers.get("retry-after"), 30);
    } else {
      throw new Error(`${response.status}: ${await response.text()}`);
    }

    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
  }
}

poll("/applications/1234-my-game/metrics/current", (metrics) => {
  for (const location of metrics.locations) {
    console.log(location.region, location.totals?.ccu ?? "no recent data");
  }
});
```

---

## Errors

Errors have the same shape and a stable `code`:

```json
{ "error": { "code": "rate_limited", "message": "Too many requests. Retry after the number of seconds in the Retry-After header." } }
```

| Status | `code` | Meaning |
|---|---|---|
| 401 | `unauthenticated` | Missing, invalid or revoked token. |
| 404 | `not_found` | No such application, deploy or instance in your team. |
| 405 | `method_not_allowed` | The API only answers `GET`. |
| 409 | `instance_not_ready` | The instance isn't running, so its logs can't be read. |
| 422 | `invalid_request` | A parameter is invalid; `error.fields` maps each one to its messages. |
| 429 | `rate_limited`, `busy` | Retry after `Retry-After` seconds. |
| 500 | `server_error` | Something failed on our side. |
| 502 | `instance_unreachable` | The instance didn't answer the log request. |
| 503 | `timeout`, `busy`, `unavailable`, `billing_unavailable` | Temporary; retry after `Retry-After` seconds. |

Under heavy load, the proxy in front of the API can answer a `429`, `502` or `504` itself, as plain text rather than JSON. Treat those as temporary too.

---
Source: https://docs.colyseus.io/cloud/api


# Compute Plans

### Low Performance

The Low Performance is powered by previous generation Intel CPUs and regular SSD.

_(Recommended for development environments.)_

### High Frequency (Recommended)

The High Frequency (Recommended) is powered by 3GHz+ Intel Xeon CPUs and NVMe SSD

_(The recommended plan for most production environments.)_

### High Performance

The High Performance is powered by new generations of Intel Xeon CPUs and NVMe SSD.

_(Availability of High Frequency and High Performance plans vary according to the region selected.)_

### Dedicated (Enterprise)

The Dedicated (Enterprise) run atop fully dedicated, new generation AMD EPYC vCPUs and NVMe SSD.

_(Performance here should be consistent but not necessarily faster than the High Frequency.)_

---
Source: https://docs.colyseus.io/cloud/compute-plans


# Continuous Deployment

Colyseus Cloud can deploy your server every time you push to GitHub. You connect your repository once, and each push to the selected branch deploys to all your regions.

## Deploying from GitHub

1. Open your application's **Settings**, then the **Build & deploy** tab.
2. Under **Deploy from GitHub**, click **Connect GitHub**.
3. Install the Colyseus Cloud GitHub App on your repository.
4. Pick the repository and the branch to deploy.
5. Click **Connect and deploy**.

From then on, every push to that branch deploys your server.

## Choosing which pushes deploy

A repository often holds more than the server: a frontend, docs, art. A push that only changes those doesn't need a deploy. The **Root directory** and **Watch paths** settings, in the **Build settings** card of the same tab, decide which pushes deploy.

Watch paths only filter pushes from GitHub. A deploy you start from the CLI or from the panel always runs.

### Root directory

The **Root directory** is the folder that holds your server's `package.json` and `ecosystem.config.js`. When it is a subfolder, such as `server/`, only pushes that change a file inside it deploy.

### Watch paths

**Watch paths** add more paths that trigger a deploy, one per line. Use them when your server depends on files outside its root directory, such as a folder shared with your frontend:

```txt filename="Watch paths"
shared/**
package.json
```

With the root directory `server/`, a push deploys when it changes a file in `server/` or `shared/`, or the `package.json` at the repository root.

Paths are relative to the repository root, not to the root directory. Each line can be:

| Pattern | Matches |
| --- | --- |
| `shared/**` or `shared/` | Every file in `shared/` and its subfolders. |
| `package.json` | That file. When the path is a folder, every file inside it. |
| `*.proto` | Every `.proto` file, in any folder. `*` also matches `/`. |

### Excluding paths

Start a line with `!` to leave a path out. A push that only changes files you left out doesn't deploy.

Exclusions are the way to filter pushes when the root directory must stay `/`. A pnpm or npm workspace is the common case, because the lockfile and `ecosystem.config.js` sit at the repository root:

```txt filename="Watch paths"
!apps/client/**
!docs/**
```

With the root directory `/`, these lines skip a push that only changes the frontend or the docs. A push that changes `apps/server/`, `packages/` or the lockfile still deploys, even when it also changes the frontend.

While the root directory is `/`, every file is watched already. So a line without `!` only matters after an exclusion, to bring part of it back.

### Order of lines

The root directory counts as the first line. When several lines match a file, the last one decides:

```txt filename="Watch paths"
!apps/**
apps/server/**
```

Here a change in `apps/server/` deploys, and a change anywhere else in `apps/` doesn't. In the opposite order, `!apps/**` would leave out `apps/server/` too.

## Using GitHub Actions

> **Note:**
>
> Deploying from GitHub needs no workflow. Use GitHub Actions when a step must run before the deploy, such as your tests.

When you make your first deployment from your development environment to the Colyseus Cloud, you will receive a `.colyseus-cloud.json` file. This file contains the `applicationId` and `token` that you will use to deploy your server from your CI/CD pipeline.

Do **not** push `.colyseus-cloud.json` to your repository, as it contains sensitive information. Instead, you can use GitHub Secrets to store this information and use it in your GitHub Actions workflow:

- `APPLICATION_ID`: The `applicationId` from your `.colyseus-cloud.json` file.
- `TOKEN`: The `token` from your `.colyseus-cloud.json` file.

![Repository Settings](https://docs.colyseus.io/cloud/continuous-deployment.png)

### Example Workflow

Here is an example of a GitHub Actions workflow that deploys your server to the Colyseus Cloud when you push to the `main` branch.

```yaml filename=".github/workflows/colyseus-cloud-deploy.yml"
name: Deploy to Colyseus Cloud

on:
    push:
        branches:
            - main

jobs:
    deploy:
        runs-on: ubuntu-latest
        env:
            applicationId: ${{ secrets.APPLICATION_ID }}
            token: ${{ secrets.TOKEN }}
        steps:
            - uses: actions/checkout@v4
            - name: Use Node.js
              uses: actions/setup-node@v4
              with:
                  node-version: '20.x'
                  registry-url: 'https://registry.npmjs.org'
            - name: Trigger deployment
              run: |
                  npm install -g @colyseus/cloud
                  npx @colyseus/cloud deploy --applicationId $applicationId --token $token
```

---
Source: https://docs.colyseus.io/cloud/continuous-deployment


# Add-on: DDoS Protection

Adds an extra layer of protection to keep your hosting infrastructure online and operating even when they are the target of attacks.

When enabled, our DDoS Protection system monitors network traffic and routes malicious activity to our attack mitigation farm. Routing starts after a DDoS event is detected, generally within 60 seconds.

The DDoS mitigation system protects your cloud server at both Layer 3 and Layer 4. Mitigation adds no latency and never sends your traffic to a third party. The system adds 10 Gbps of mitigation capacity per instance and safeguards all attached IPv4 addresses.

---

## Frequently Asked Questions

**How does DDoS protection work?**

Colyseus Cloud DDoS system works by dynamically routing traffic from your server when an attack is detected. Attack detection is fully automated based on proprietary detection algorithms, filtering attack traffic while clean traffic can reach your servers.

**How is traffic filtered during a DDoS attack?**

When a DDoS attack is detected, incoming traffic is re-routed to our cloud provider's Attack Mitigation Farm (AMF). The AMF filters traffic based on specific attributes of the current attack. Clean traffic is tunneled directly to your server in the same data center, so no packets ever leave our premium low-latency network. A third-party mitigation service would typically route your packets outside it.

**What IP protocol layers are supported by DDoS protection?**

Our DDoS protection works against Layer 3 and Layer 4 attacks.

**Does Colyseus Cloud protect against both TCP and UDP attacks?**

Yes.

**In which locations is DDoS Protection available?**

DDoS Protection is available in all locations.

---
Source: https://docs.colyseus.io/cloud/ddos-protection


# Environment Variables and Secrets

Colyseus Cloud allows you to safely store your secrets and environment variables via Application Settings page:

![Environment Variables](https://docs.colyseus.io/cloud/environment-variables.png)

Values are encrypted and only visible to team members of your application.

> **Warning:**
>
> **Do not commit your secrets to your repository.** When you commit a secret key to your repository, it is exposed to anyone with access to your repository. This exposure can lead to your account being compromised, and your keys being used maliciously.

---

### Development and Production environments

Colyseus loads your `.env` files automatically, depending on the `NODE_ENV` environment variable. The usage of `.env` files is optional.

- `.env.development`: When testing from your local machine
- `.env.production`: When deployed to Colyseus Cloud
- `.env.{REGION}.production`: When deployed to Colyseus Cloud, depending on the region where your server has been provisioned. Region-based environment variables have precedence over `.env.production`.

---

### Region-based Environment Variables

Colyseus Cloud provides region-based environment variables, depending on where your application is deployed:

- `process.env.REGION` - the region where your server has been provisioned.
- `process.env.COUNTRY` - the country where your server has been provisioned.

#### Region codes

| Region | `process.env.REGION` |
|-|-|
| Europe | `'EU'` |
| North America | `'NA'` |
| Asia | `'AS'` |
| Africa | `'AF'` |
| Australia | `'AU'` |
| South America | `'SA'` |

#### Country codes

| Country | `process.env.COUNTRY` |
|-|-|
| Australia | `'AU'` |
| Brazil | `'BR'` |
| Canada | `'CA'` |
| Chile | `'CL'` |
| Germany | `'DE'` |
| Spain | `'ES'` |
| France | `'FR'` |
| United Kingdom | `'GB'` |
| Israel | `'IL'` |
| India | `'IN'` |
| Japan | `'JP'` |
| South Korea | `'KR'` |
| Mexico | `'MX'` |
| Netherlands | `'NL'` |
| Poland | `'PL'` |
| Sweden | `'SE'` |
| Singapore | `'SG'` |
| United States | `'US'` |
| South Africa | `'ZA'` |

---
Source: https://docs.colyseus.io/cloud/environment-variables


# Pricing & Billing

> See the [Pricing Simulator](https://colyseus.io/pricing/) for more details.

Colyseus Cloud uses a subscription-based billing model with upfront provisioning and proration for flexibility.

When you provision a server instance, the cost for the selected compute plan is charged upfront for the billing cycle (monthly).

If you delete an instance before the end of the billing cycle, the unused time is credited to your account. These credits are automatically applied to your next invoice, reducing your costs.

Suppose you provision an instance for \$100/month and delete it after 15 days. Half of the instance cost (\$50) is credited for use on future deployments.

---

---
Source: https://docs.colyseus.io/cloud/pricing-billing


# Private NPM Registry

If you rely on private NPM packages from your organization, you need to configure authentication to access them during deployment. To do so, create a local `~/.npmrc` file in your project root.

## Example: Private NPM Registry from GitHub

For packages published under your GitHub organization (e.g., `@your-company/package-name`):

```txt filename=".npmrc"
@your-org-name:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=YOUR_GITHUB_TOKEN
```

**Configuration steps:**

1. Replace `@your-org-name` with your actual GitHub organization or username
2. Replace `YOUR_GITHUB_TOKEN` with your GitHub personal access token that has `read:packages` permission
3. Place this `.npmrc` file in your project root directory

This configuration tells npm to use GitHub's package registry for all packages under your organization's scope. All other packages still come from the default npm registry.

---
Source: https://docs.colyseus.io/cloud/private-npm-registry


# Troubleshooting "Deploy failed" errors

Here you will find the most common scenarios where a deployment can fail.

When a deployment fails, you will see the following at the bottom of your last
"deployment log":

```txt {5}
Error Output:
================
...
Deploy failed
Deploy failed with exit code: 1
```

---

## The `node_modules` folder should not be on git

 **Symptom:** "Permission denied" errors as shown below:

**rimraf: Permission denied**

```txt {3}
Error Output:
================
sh: 1: rimraf: Permission denied
  post-deploy hook failed
Deploy failed
Deploy failed with exit code: 1
```

**tsc: Permission denied**

```txt {3}
Error Output:
================
sh: 1: tsc: Permission denied
  post-deploy hook failed
Deploy failed
Deploy failed with exit code: 1
```

**colyseus-post-deploy: Permission denied**

```txt {3}
Error Output:
================
sh: 1: colyseus-post-deploy: Permission denied
  post-deploy hook failed
Deploy failed
Deploy failed with exit code: 1
```

 **Solution:** Remove the `node_modules` directory from your git repository,

```txt
git rm -r node_modules
git commit -m "removing node modules"
git push
```

Then, try to deploy again.

---

## Not having the `package.json` in the root of your git project

 **Symptom:** `ENOENT: no such file or directory, open '/home/deploy/source/package.json'`

```txt {7}
Error Output:
================
npm ERR! code ENOENT
npm ERR! syscall open
npm ERR! path /home/deploy/source/package.json
npm ERR! errno -2
npm ERR! enoent ENOENT: no such file or directory, open '/home/deploy/source/package.json'
npm ERR! enoent This is related to npm not being able to find a file.
npm ERR! enoent

npm ERR! A complete log of this run can be found in:
npm ERR!     /home/deploy/.npm/_logs/2023-07-17T18_31_07_252Z-debug-0.log
  post-deploy hook failed
Deploy failed
Deploy failed with exit code: 1
```

 **Possible solutions:**

1. Move your server files to the git root path.
2. Alternatively, update the "Root Directory" from your Application's "Settings" page, under "Build settings":

![](https://docs.colyseus.io/cloud/troubleshoot-build-settings.png)

---

## Missing, or bad `ecosystem.config.js` file

 **Symptom:** The following error message `Process list empty, cannot save empty list`

``` hl_lines="1"
Error: Process list empty, cannot save empty list
    at fin (/usr/lib/node_modules/pm2/lib/API/Startup.js:448:23)
    at ex (/usr/lib/node_modules/pm2/lib/API/Startup.js:492:30)
    at /usr/lib/node_modules/pm2/lib/API/Startup.js:500:9
    at /usr/lib/node_modules/pm2/node_modules/pm2-axon-rpc/lib/client.js:45:10
    at Parser.<anonymous> (/usr/lib/node_modules/pm2/node_modules/pm2-axon/lib/sockets/req.js:67:8)
    at Parser.emit (node:events:514:28)
    at Parser._write (/usr/lib/node_modules/pm2/node_modules/amp/lib/stream.js:91:16)
    at writeOrBuffer (node:internal/streams/writable:392:12)
    at _write (node:internal/streams/writable:333:10)
    at Writable.write (node:internal/streams/writable:337:10)
```

 **Solution:** Make sure you have an `ecosystem.config.js` (or `ecosystem.config.cjs`) file at the root of the project - with the `"script"` pointing to your application's entrypoint.

```js {6} filename="ecosystem.config.js"
const os = require('os');

module.exports = {
    apps : [{
        name: "colyseus-app",
        script: 'build/index.js',
        time: true,
        watch: false,
        instances: os.cpus().length,
        exec_mode: 'fork',
        wait_ready: true,
    }],
};
```

---

## TypeScript compilation errors

If you see TypeScript compilation errors like the example below, read the
[TypeScript compilation errors](https://docs.colyseus.io/cloud/typescript-compilation-errors.md) article, as it
explains how to fix them.

``` hl_lines="1 2 3"
src/app.config.ts(3,28): error TS2307: Cannot find module '@colyseus/playground' or its corresponding type declarations.
src/app.config.ts(25,34): error TS7006: Parameter 'req' implicitly has an 'any' type.
src/app.config.ts(25,39): error TS7006: Parameter 'res' implicitly has an 'any' type.

...

Error Output:
================
  post-deploy hook failed
Deploy failed
Deploy failed with exit code: 1
```

---
Source: https://docs.colyseus.io/cloud/troubleshooting


# TypeScript/Compilation errors

If you haven't created your Colyseus application via `npm create colyseus-app@latest`, make sure your `tsconfig.json` is configured as follows:

```json filename="tsconfig.json"
{
  "compilerOptions": {
    "outDir": "build",
    "target": "ESNext",
    "module": "CommonJS",
    "moduleResolution": "node",
    "strict": true,
    "allowJs": true,
    "strictNullChecks": false,
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "useDefineForClassFields": false
  },
  "include": [
    "src"
  ]
}
```

Make sure you are able to compile your application locally before deploying it to Colyseus Cloud:

```sh filename="Terminal"
npm run build
```

---

## Running `tsx` directly in production (not recommended)

You may run `tsx` directly in production, by updating the following configuration in your `ecosystem.config.js` file:

```diff filename="ecosystem.config.js"
module.exports = {
   apps : [{
     // ...
-    script: 'build/index.js',
+    script: 'src/index.ts',
+    interpreter: 'node',
+    interpreterArgs: '--import tsx',
     // ...
```

You'll also need to skip the build step by updating `package.json`:

```diff filename="package.json"
  "scripts": {
-    "build": "npm run clean && tsc",
+    "build": "exit 0"
```

---

## Disabling TypeScript strict mode (not recommended)

You can disable TypeScript strict mode by modifying the following configuration to your `tsconfig.json`. (This is not recommend as it will make your application more prone to runtime errors.)

```json filename="tsconfig.json"
{
  "compilerOptions": {
    // ...
    "strict": false,
    "skipLibCheck": true,
  }
}
```

---

## Monorepo setup (advanced)

If you are using a monorepo setup, we recommend using the `pnpm` package manager instead of `npm`. (See [pnpm docs](https://pnpm.io/workspaces) for more information)

```sh filename="Terminal"
npm install -g pnpm
```

#### Configure your workspaces

`pnpm` requires you to configure your workspaces in a `pnpm-workspace.yaml` file. See example below:

```yaml filename="pnpm-workspace.yaml"
packages:
  # all packages in direct subdirs of packages/
  - 'packages/*'
  # all packages in subdirs of components/
  - 'components/**'
  # exclude packages that are inside test directories
  - '!**/test/**'
```

#### Installing dependencies

Before installing your dependencies with `pnpm`, make sure to remove `node_modules` and `package-lock.json` from your previous package manager from your project.

```sh filename="Terminal"
pnpm install
```

**Push `pnpm-lock.yaml` and `pnpm-workspace.yaml`**

Make sure to push the `pnpm-lock.yaml` and `pnpm-workspace.yaml` files to your repository, so Colyseus Cloud can install your dependencies correctly.

---
Source: https://docs.colyseus.io/cloud/typescript-compilation-errors


# Welcome to the Colyseus Community!

> **Warning:**
>
> This space is dedicated to community projects and community content. [Help us improve this section](https://github.com/colyseus/docs/tree/master/pages/community.mdx).

- [Join Discord](http://chat.colyseus.io)
- [Join Forum](https://forum.colyseus.io)
- [Colyseus on GitHub](https://github.com/colyseus/)
- [Colyseus on LinkedIn](https://www.linkedin.com/company/colyseus/)
- [Colyseus on YouTube](https://www.youtube.com/@colyseus)

---

## Games

Games developed by the community. They are open-source and can be used as a reference for your own projects. Feel free to submit yours.

- [Real-Time PvP Battle](https://github.com/heronoa/turnbased-pvp-colyseus)

- [Multiplayer Blackjack](https://github.com/stopnoanime/21-online)

- [Geofind - Guessing Game](https://github.com/posixpascal/geofind)

## Tutorials

- [dev.to: How I Created an Online Multiplayer Game Using Colyseus](https://dev.to/konmaz/how-i-created-an-online-multiplayer-game-using-colyseus-npf)

## Videos

- [ 2D Multiplayer Card Game Template with Godot & Colyseus](https://www.youtube.com/watch?v=9QtQ5iXj2U0)
- [ 2D Multiplayer Card Game Templates with Colyseus, Unity, Phaser, & Defold](https://www.youtube.com/watch?v=NylOh_PVCsc)
- [ Building Team Thinking Games At Synthesis](https://gitnation.com/contents/building-team-thinking-games-at-synthesis)
- [ Building an online multiplayer browser game with Haxe and Colyseus](https://www.youtube.com/watch?v=5XaGzRH5Y7I)
- [ Multiplayer Tic-Tac-Toe in Colyseus & Phaser](https://www.youtube.com/playlist?list=PLNwtXgWIx3rhOmsJOkUFRiFQg8pPFPDqy)
- [ Multiplayer Game Design Colyseus and Unity](https://www.youtube.com/playlist?list=PLxgtJR7f0RBK_yGDSbPuspqMR-oEi1S25)

---
Source: https://docs.colyseus.io/community


# Database

The recommended way to persist game data in Colyseus is **`@colyseus/database`**, the official persistence layer built on version [1.0.0-rc](#drizzle-version) of [Drizzle ORM](https://orm.drizzle.team/). A single typed connection backs player accounts, cloud saves, leaderboards, live configs, analytics, moderation, and matchmaking.

A single `GameDatabase` instance exposes:

- **`db.auth`**: user store for [ `@colyseus/auth`](https://docs.colyseus.io/auth/module.md): bans, session revocation, password management
- **`db.saves`**: versioned cloud saves with optimistic locking
- **`db.leaderboards`**: keep-best scores, seasons, top-N and around-me queries
- **`db.configs`**: typed, hot-reloadable live-ops configuration
- **`db.analytics`** / **`db.moderation`** / **`db.notes`**: event tracking, roles, and player notes
- **`db.segments`**: declarative player cohorts for targeting
- **[`DatabaseDriver`](https://docs.colyseus.io/server/driver.md#database-driver)**: a matchmaking driver reusing the same connection

Colyseus itself remains database-agnostic: if your project needs a different stack, [bring your own database](https://docs.colyseus.io/database/bring-your-own.md) and query it directly from your rooms.

> **Note:**
>
> `@colyseus/database` was introduced in Colyseus 0.18. Feedback is welcome on the [public roadmap](https://docs.colyseus.io/roadmap.md).

## Installation

```sh npm2yarn
npm install --save @colyseus/database
```

For PostgreSQL, also install `postgres` ([postgres-js](https://github.com/porsager/postgres)):

```sh npm2yarn
npm install --save postgres
```

> **Warning:**
>
> A `postgres://` connection string always opens postgres-js, never `pg` (node-postgres). Drizzle's own PostgreSQL guide installs `pg`, so check which one you have. To keep `pg`, open the pool yourself and pass it as [`db`](#use-an-existing-drizzle-instance).

For embedded PGlite, install `@electric-sql/pglite` instead:

```sh npm2yarn
npm install --save @electric-sql/pglite
```

### Drizzle version

`@colyseus/database` is built on the 1.0 release candidate of Drizzle ORM and declares `drizzle-orm` as a peer dependency. Install it from the `rc` dist-tag, alongside `drizzle-kit` if you generate migrations. npm's `latest` is still the 0.x line, and its column builders fail inside the table factory with `colBuilder.build(...).postBuild is not a function`.

```sh npm2yarn
npm install --save drizzle-orm@rc
npm install --save-dev drizzle-kit@rc
```

Keep a single copy of `drizzle-orm` in `node_modules`. With two copies, the code still runs. `tsc` then rejects `eq(db.tables.users.id, …)` and every other place where a column from one copy meets a query builder from the other. `npm ls drizzle-orm` shows any duplicate.

## Quick start

Construct a `GameDatabase` and pass it to `defineServer` via the `database` option. The server boots the database (running migrations) before it starts listening, and automatically mounts the [`@colyseus/auth`](https://docs.colyseus.io/auth/module.md) routes when that package is installed.

```ts {2,5} filename="src/app.config.ts"
import { defineServer } from "colyseus";
import { GameDatabase } from "@colyseus/database";

export const db = new GameDatabase({
    connectionString: process.env.DATABASE_URL,
});

export default defineServer({
    database: db,
    // ...rooms, routes, etc.
});
```

Export the `db` instance so your rooms can import it. Inside any room lifecycle method, the services are ready to use:

```ts filename="src/rooms/MyRoom.ts"
import { Room } from "colyseus";
import { db } from "../app.config";

export class MyRoom extends Room {
    async onJoin(client) {
        // client.auth was populated by the default static onAuth,
        // which already rejects banned/revoked tokens automatically.
        await db.saves.load(client.auth.id);
    }
}
```

## Dialects & connection strings

The dialect is auto-detected from the connection string. When omitted, SQLite is used with the default file `colyseus.db`.

| Connection string | Dialect | Notes |
|---|---|---|
| _(omitted)_ or `./game.db` | SQLite | File-based; great for development |
| `:memory:` | SQLite | Ephemeral; useful for tests |
| `postgres://…` / `postgresql://…` | PostgreSQL | Production; requires the `postgres` package (postgres-js, not `pg`) |
| `pglite://./data` / `pglite://:memory:` | PGlite | Embedded Postgres, no external server |

```ts filename="src/app.config.ts"
// SQLite (development): defaults to colyseus.db
new GameDatabase();

// PostgreSQL (production)
new GameDatabase({ connectionString: process.env.DATABASE_URL });

// Embedded PGlite, file-backed
new GameDatabase({ dialect: "pglite", connectionString: "pglite://./data" });
```

### Use an existing Drizzle instance

Pass `db` to reuse a Drizzle instance you already opened. Use this option to run on `pg` (node-postgres), or to share one pool with the rest of your app. `connectionString` is ignored, and the dialect is read from the instance unless you pass `dialect`.

```ts filename="src/app.config.ts"
import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";
import { GameDatabase } from "@colyseus/database";

const pool = new Pool({ connectionString: process.env.DATABASE_URL });

export const db = new GameDatabase({
    db: drizzle({ client: pool }),
});
```

`migrations: "auto"` runs through the instance's own client, so any driver Drizzle supports works: postgres-js, node-postgres, PGlite, or `node:sqlite`. An instance that exposes no client (an HTTP proxy driver, for example) needs `migrations: "skip"` or `{ files }`. The connection stays yours: `shutdown()` closes only connections the package opened itself.

## Migrations

The `migrations` option controls how the schema is applied at boot:

- **`"auto"`** _(default)_: creates missing tables with their primary keys, foreign keys, `UNIQUE` and `CHECK` constraints, adds missing columns to existing tables, and creates missing indexes on every boot. Idempotent and convenient for development. It never drops a column, changes a type, or adds a constraint to a table that already exists. See [Constraints and indexes](https://docs.colyseus.io/database/schemas.md#constraints-and-indexes).
- **`"skip"`**: does nothing; you manage the schema externally (e.g. a `drizzle-kit migrate` step in CI before the server starts).
- **`{ files: "./drizzle" }`**: runs SQL migration files generated by `drizzle-kit`. Drizzle tracks applied migrations, so reruns are safe. See [Migrations with drizzle-kit](https://docs.colyseus.io/database/schemas.md#migrations-with-drizzle-kit).

```ts filename="src/app.config.ts"
new GameDatabase({
    connectionString: process.env.DATABASE_URL,
    migrations: "skip", // schema applied by CI
});
```

## Matchmaking driver

Reuse the same connection as your [matchmaking driver](https://docs.colyseus.io/server/driver.md#database-driver) (one pool for everything, no separate Redis required):

```ts {2,8} filename="src/app.config.ts"
import { defineServer } from "colyseus";
import { GameDatabase, DatabaseDriver } from "@colyseus/database";

export const db = new GameDatabase({ connectionString: process.env.DATABASE_URL });

export default defineServer({
    database: db,
    driver: new DatabaseDriver(), // adopts the GameDatabase connection
});
```

Without options, the driver binds to the most recently constructed `GameDatabase`. With more than one instance in the process, pass it explicitly: `new DatabaseDriver({ database: db })`. Custom room-cache columns and the standalone (no `GameDatabase`) mode are covered on the [Driver](https://docs.colyseus.io/server/driver.md#database-driver) page.

## Next steps

- [Authentication](https://docs.colyseus.io/database/authentication.md): the built-in `@colyseus/auth` integration (auto-mounted routes, ban gating, JWT revocation, admin helpers).
- [Services](https://docs.colyseus.io/database/services.md): cloud saves, leaderboards, live configs, analytics, moderation, notes, and the matching room plugins.
- [Customizing built-in table schemas](https://docs.colyseus.io/database/schemas.md): extend the package's drizzle tables with your own columns, constraints, and indexes.
- [Bring your own database](https://docs.colyseus.io/database/bring-your-own.md): ORMs, query builders, Firebase, and the `onAuth`/`onLeave` integration patterns.

---
Source: https://docs.colyseus.io/database


# Authentication

When [`@colyseus/auth`](https://docs.colyseus.io/auth/module.md) is installed alongside `@colyseus/database` and you pass `database:` to `defineServer`, the database becomes the user store and all auth routes mount automatically. The only callbacks left to write are the email-delivery ones.

**What's wired automatically:**

- **HTTP routes**: every endpoint from `@colyseus/auth` (register, login, forgot/reset password, OAuth callback) is spread into your router under the configured prefix.
- **User store**: `db.auth.settings` supplies the user-store [Backend API](https://docs.colyseus.io/auth/module.md#backend-api) callbacks (`onFindUserByEmail`, `onRegisterWithEmailAndPassword`, `onRegisterAnonymously`, `onResetPassword`, `onOAuthProviderCallback`, `onCheckBanned`). **Email delivery is not included**: wire `onForgotPassword` (and `onSendEmailConfirmation` / `onEmailConfirmed` if you use email verification) yourself, or those flows silently no-op.
- **Ban gating at login**: `onCheckBanned` rejects banned users and surfaces `{ reason, until }` from the row.
- **JWT session revocation**: JWTs carry a `tokenVersion` claim. `db.auth.ban()` bumps the version together with the ban fields, so every JWT issued before the ban is rejected **on its next room join**. HTTP routes verify only signature and expiry (see [HTTP API Auth](https://docs.colyseus.io/auth/http.md)). Call `db.auth.bumpTokenVersion(userId)` on its own for password changes, "sign out everywhere", and forced rotation.
- **Password-hash handoff**: `@colyseus/auth` hashes passwords before they reach the database; the DB never sees plaintext.

The same env secrets (`JWT_SECRET`, `SESSION_SECRET`) still apply. See [Auth Module → Required Environment Secrets](https://docs.colyseus.io/auth/module.md#required-environment-secrets).

## Minimal setup

Once `database:` is set on `defineServer`, the auth integration is live. No additional wiring is required:

```ts {2,6} filename="src/app.config.ts"
import { defineServer } from "colyseus";
import { GameDatabase } from "@colyseus/database";

export const db = new GameDatabase({ connectionString: process.env.DATABASE_URL });

export default defineServer({
    database: db, // ← wires @colyseus/auth routes + user store automatically
});
```

## Admin & moderation helpers

`db.auth` exposes account-management methods called from admin tooling or moderation flows:

```ts
await db.auth.ban(userId, { reason: "cheating", until: new Date(Date.now() + 86_400_000) });
const status = await db.auth.isBanned(userId); // { banned, reason?, until? }
await db.auth.unban(userId);

// Force-log-out: previously issued JWTs are rejected on the next room join
await db.auth.bumpTokenVersion(userId);
```

## Customizing callbacks

To wrap or replace individual callbacks, override keys on the `auth.settings` singleton **after** the server has started listening. `listen()` copies `db.auth.settings` into `auth.settings`, so an override applied earlier is overwritten. The example below adds an invite-code check during registration:

```ts filename="src/index.ts"
import { listen } from "@colyseus/tools";
import { auth } from "@colyseus/auth";
import app from "./app.config";

listen(app).then(() => {
    // after listen(): wrap the database-provided callback
    const original = auth.settings.onRegisterWithEmailAndPassword;
    auth.settings.onRegisterWithEmailAndPassword = async (email, password, options) => {
        if (options.inviteCode !== process.env.INVITE_CODE) {
            throw new Error("invalid invite code");
        }
        return original(email, password, options);
    };
});
```

`options` is the object the client passes as the third argument of `client.auth.registerWithEmailAndPassword(email, password, { inviteCode })` (the `options` field of the `POST /auth/register` body). A thrown error reaches the client as a `401` with the message.

See the [Backend API](https://docs.colyseus.io/auth/module.md#backend-api) catalog for the full list of hooks. Assign onto `auth.settings`, not `db.auth.settings`, whose getter returns a fresh throwaway object on every access.

> **Note:**
>
> Not using `@colyseus/database`? See [Auth Module](https://docs.colyseus.io/auth/module.md) for the manual setup: implement the [Backend API](https://docs.colyseus.io/auth/module.md#backend-api) callbacks against your own database.

---
Source: https://docs.colyseus.io/database/authentication


# Bring your own database

`@colyseus/database` is the recommended path, but Colyseus does not require it. Any database or Node.js module works. Query it directly from your room's lifecycle methods.

If you go this route, we still recommend [Drizzle ORM](https://orm.drizzle.team/) (what `@colyseus/database` is built on). Other commonly used tools:

## ORMs (Object-Relational Mappers)

ORMs are known for abstracting the database layer and providing a more object-oriented approach.

- [DrizzleORM](https://orm.drizzle.team/)
- [MikroORM](https://mikro-orm.io/)
- [Prisma](http://www.prisma.io/)
- [Sequelize](https://sequelize.org/)
- [TypeORM](https://typeorm.io/)

## Query builders

Query builders are known for their simplicity and flexibility.

- [Kysely](https://kysely.dev/)
- [Knex](https://knexjs.org/)

## Backend-as-a-Service

[Firebase](https://firebase.google.com/) (Firestore / Realtime Database) is a common choice when you want managed persistence, authentication, and hosting without running your own database. Use the [Firebase Admin SDK](https://firebase.google.com/docs/admin/setup) from your server and call it from the room lifecycle methods below, just like any other database client.

## Usage patterns with Colyseus

### Query the database in `onAuth()`

Fetch user data from the join `options` the client sends, or from the authentication token.

```ts filename="src/rooms/MyRoom.ts"
// db: your own client (pg, knex, prisma, ...)
async onAuth(client, options) {
    const user = await db.query('SELECT * FROM users WHERE id = ?', [options.userId]);
    return user;
}

async onJoin (client, options) {
    // ...
    await db.query('UPDATE users SET online = true WHERE id = ?', [client.auth.id]);
}
```

### Update the database in `onLeave()`

Update the database when the client leaves the room.

```ts filename="src/rooms/MyRoom.ts"
// ...
async onLeave(client, consented) {
    // ...
    await db.query('UPDATE users SET online = false WHERE id = ?', [client.auth.id]);
}
```

---
Source: https://docs.colyseus.io/database/bring-your-own


# Customizing built-in table schemas

Every service in `@colyseus/database` is backed by a Drizzle table you can extend with your own columns, constraints, and indexes. Use the per-dialect `tables` factory to build a table from the built-in columns plus yours, then pass it via the `schemas` option. Services keep working and return your custom columns with full type inference.

The examples import column builders from `drizzle-orm`. Install it from the `rc` dist-tag, as described under [Drizzle version](https://docs.colyseus.io/database.md#drizzle-version).

## Built-in tables

| Key | Physical table | Used by | Purpose |
|---|---|---|---|
| `users` | `colyseus_users` | `db.auth` + [`@colyseus/auth`](https://docs.colyseus.io/auth/module.md) | Player accounts (email, password hash, anonymous flag, ban fields, token version) |
| `configs` | `colyseus_configs` | `db.configs` | Live-ops config key/value store |
| `cloudSaves` | `colyseus_cloud_saves` | `db.saves` | Per-user, per-slot save data with version |
| `leaderboards` | `colyseus_leaderboards` | `db.leaderboards` | Leaderboard definitions |
| `leaderboardEntries` | `colyseus_leaderboard_entries` | `db.leaderboards` | Score rows per (board, user, season) |
| `analyticsEvents` | `colyseus_analytics_events` | `db.analytics` | Event log written by `track()` |
| `roles` | `colyseus_roles` | `db.moderation` | Moderation roles + scoped collection permissions |
| `userNotes` | `colyseus_user_notes` | `db.notes` | Admin notes attached to users |
| `adminAudit` | `colyseus_admin_audit` | `db.audit` | Admin action audit log |
| `roomCaches` | `colyseus_room_caches` | [`DatabaseDriver`](https://docs.colyseus.io/server/driver.md#database-driver) | Matchmaker room cache (driver-owned; customize via the driver's `schema` option, not `schemas`) |

## Example: extending `users`

**SQLite**

```ts filename="src/db/schema.ts"
import { tables } from "@colyseus/database";
import { text, integer } from "drizzle-orm/sqlite-core";

export const users = tables.sqlite.users("colyseus_users", {
    displayName: text("display_name"),
    level: integer("level").notNull().default(1),
});
```

```ts filename="src/app.config.ts"
import { GameDatabase } from "@colyseus/database";
import { users } from "./db/schema";

export const db = new GameDatabase({
    connectionString: "./game.db",
    schemas: { users },
});
```

**PostgreSQL**

```ts filename="src/db/schema.ts"
import { tables } from "@colyseus/database";
import { text, integer } from "drizzle-orm/pg-core";

export const users = tables.pg.users("colyseus_users", {
    displayName: text("display_name"),
    level: integer("level").notNull().default(1),
});
```

```ts filename="src/app.config.ts"
import { GameDatabase } from "@colyseus/database";
import { users } from "./db/schema";

export const db = new GameDatabase({
    connectionString: process.env.DATABASE_URL, // postgres://…
    schemas: { users },
});
```

The first argument is the physical table name. `"colyseus_users"` keeps the default name, so existing rows stay in place. Any other name creates a new, empty table: the rows in the built-in one are not migrated.

The factory is available on both dialects: `tables.sqlite.<name>` with column builders from `drizzle-orm/sqlite-core`, and `tables.pg.<name>` with `drizzle-orm/pg-core`. The tabs on this page remember your choice.

The resolved tables are available as `db.tables.<key>` (`db.tables.users` is the table you passed). The raw Drizzle instance is `db.drizzle`, typed against your schema, for any query the services don't cover:

```ts
import { eq } from "drizzle-orm";

await db.drizzle.update(db.tables.users)
    .set({ displayName: "Alice" })
    .where(eq(db.tables.users.id, userId));
```

> **Warning:**
>
> The built-in inserts (`/auth/register`, `/auth/anonymous`, OAuth sign-in) fill the built-in columns only. Give custom columns a default or keep them nullable, or those routes fail with a `NOT NULL` error.

## Constraints and indexes

The factory's third argument mirrors `sqliteTable()` / `pgTable()`: a callback that receives the built columns and returns indexes, `CHECK` constraints, and `UNIQUE` constraints. The example below adds a handle that is unique regardless of case, so `JohnSmith` and `johnsmith` cannot coexist:

**SQLite**

```ts filename="src/db/schema.ts"
import { tables } from "@colyseus/database";
import { text, uniqueIndex, check } from "drizzle-orm/sqlite-core";
import { sql } from "drizzle-orm";

export const users = tables.sqlite.users("colyseus_users", {
    handle: text("handle"),
    handleLower: text("handle_lower"),
}, (t) => [
    uniqueIndex("users_handle_lower_idx").on(t.handleLower),
    check("users_handle_lower_chk", sql`${t.handleLower} = lower(${t.handle})`),
]);
```

**PostgreSQL**

```ts filename="src/db/schema.ts"
import { tables } from "@colyseus/database";
import { text, uniqueIndex, check } from "drizzle-orm/pg-core";
import { sql } from "drizzle-orm";

export const users = tables.pg.users("colyseus_users", {
    handle: text("handle"),
    handleLower: text("handle_lower"),
}, (t) => [
    uniqueIndex("users_handle_lower_idx").on(t.handleLower),
    check("users_handle_lower_chk", sql`${t.handleLower} = lower(${t.handle})`),
]);
```

Write both columns together to keep the check satisfied:

```ts
await db.drizzle.update(db.tables.users)
    .set({ handle, handleLower: handle.toLowerCase() })
    .where(eq(db.tables.users.id, userId));
// a second user with the handle "johnsmith" now fails with a UNIQUE error
```

`migrations: "auto"` applies these in two ways:

- **When the table is created**: `UNIQUE` (column-level `.unique()` and `unique().on(...)`) and `CHECK` constraints are part of `CREATE TABLE`. They are not added to a table that already exists.
- **On every boot**: `index()` and `uniqueIndex()` run as `CREATE INDEX IF NOT EXISTS`, so an index declared later still reaches an existing table.

Prefer `uniqueIndex()` over `.unique()` for a table that may already exist in production. For any other change to an existing table, use [drizzle-kit migrations](#migrations-with-drizzle-kit).

> **Warning:**
>
> The PostgreSQL factory's third argument currently fails type-checking. `tsc` rejects `.on(t.handleLower)` with "Property 'dimensions' is missing", although the code runs. Until the fix ships, use the [hand-rolled `pgTable` form](#hand-rolled-tables-with-columns), which type-checks. SQLite is not affected.

## Hand-rolled tables with `columns`

For full control, spread the column maps (`columns.sqlite.<name>` / `columns.pg.<name>`) into your own `sqliteTable(...)` / `pgTable(...)`. The factory does the same internally:

**SQLite**

```ts filename="src/db/schema.ts"
import { columns } from "@colyseus/database";
import { sqliteTable, text, uniqueIndex, check } from "drizzle-orm/sqlite-core";
import { sql } from "drizzle-orm";

export const users = sqliteTable("colyseus_users", {
    ...columns.sqlite.users,
    handle: text("handle"),
    handleLower: text("handle_lower"),
}, (t) => [
    uniqueIndex("users_handle_lower_idx").on(t.handleLower),
    check("users_handle_lower_chk", sql`${t.handleLower} = lower(${t.handle})`),
]);
```

**PostgreSQL**

```ts filename="src/db/schema.ts"
import { columns } from "@colyseus/database";
import { pgTable, text, uniqueIndex, check } from "drizzle-orm/pg-core";
import { sql } from "drizzle-orm";

export const users = pgTable("colyseus_users", {
    ...columns.pg.users,
    handle: text("handle"),
    handleLower: text("handle_lower"),
}, (t) => [
    uniqueIndex("users_handle_lower_idx").on(t.handleLower),
    check("users_handle_lower_chk", sql`${t.handleLower} = lower(${t.handle})`),
]);
```

`cloudSaves` and `leaderboardEntries` have composite primary keys: `(userId, slot)` and `(boardId, userId, season)`. When you hand-roll those two, add the `primaryKey(...)` yourself. The factory adds it for you.

> **Warning:**
>
> Spread `columns.sqlite.users` / `columns.pg.users`, not the `tables.*` factories. Those are functions, so spreading them adds no columns. The server still boots. The first login or room join then fails with `TypeError: Cannot convert undefined or null to object`. The table has none of the built-in columns.

## Migrations with drizzle-kit

For production schemas, generate SQL migrations with drizzle-kit and apply them with `migrations: { files }`. drizzle-kit reads every table exported from one schema file. Re-export the tables you did not customize from `@colyseus/database/sqlite-defaults` (or `@colyseus/database/pg-defaults`). That way drizzle-kit generates them too:

**SQLite**

```ts filename="src/db/schema.ts"
import { tables } from "@colyseus/database";
import { text, uniqueIndex, check } from "drizzle-orm/sqlite-core";
import { sql } from "drizzle-orm";

export const users = tables.sqlite.users("colyseus_users", {
    handle: text("handle"),
    handleLower: text("handle_lower"),
}, (t) => [
    uniqueIndex("users_handle_lower_idx").on(t.handleLower),
    check("users_handle_lower_chk", sql`${t.handleLower} = lower(${t.handle})`),
]);

export {
    configs, cloudSaves, leaderboards, leaderboardEntries,
    analyticsEvents, roles, userNotes, adminAudit,
} from "@colyseus/database/sqlite-defaults";
```

```ts filename="drizzle.config.ts"
import { defineConfig } from "drizzle-kit";

export default defineConfig({
    dialect: "sqlite",
    schema: "./src/db/schema.ts",
    out: "./drizzle",
    dbCredentials: { url: "./colyseus.db" },
});
```

**PostgreSQL**

```ts filename="src/db/schema.ts"
import { tables } from "@colyseus/database";
import { text, uniqueIndex, check } from "drizzle-orm/pg-core";
import { sql } from "drizzle-orm";

export const users = tables.pg.users("colyseus_users", {
    handle: text("handle"),
    handleLower: text("handle_lower"),
}, (t) => [
    uniqueIndex("users_handle_lower_idx").on(t.handleLower),
    check("users_handle_lower_chk", sql`${t.handleLower} = lower(${t.handle})`),
]);

export {
    configs, cloudSaves, leaderboards, leaderboardEntries,
    analyticsEvents, roles, userNotes, adminAudit,
} from "@colyseus/database/pg-defaults";
```

```ts filename="drizzle.config.ts"
import { defineConfig } from "drizzle-kit";

export default defineConfig({
    dialect: "postgresql",
    schema: "./src/db/schema.ts",
    out: "./drizzle",
    dbCredentials: { url: process.env.DATABASE_URL! },
});
```

With `drizzle-kit@rc` installed (see [Drizzle version](https://docs.colyseus.io/database.md#drizzle-version)), generate the migration:

```sh
npx drizzle-kit generate
```

The generated `migration.sql` contains every table, including the unique index and the check constraint. Point `GameDatabase` at the folder:

**SQLite**

```ts filename="src/app.config.ts"
import { GameDatabase } from "@colyseus/database";
import * as schema from "./db/schema";

export const db = new GameDatabase({
    connectionString: "./colyseus.db",
    schemas: schema,
    migrations: { files: "./drizzle" },
});
```

**PostgreSQL**

```ts filename="src/app.config.ts"
import { GameDatabase } from "@colyseus/database";
import * as schema from "./db/schema";

export const db = new GameDatabase({
    connectionString: process.env.DATABASE_URL,
    schemas: schema,
    migrations: { files: "./drizzle" },
});
```

Drizzle records applied migrations in its own table, so every boot re-runs safely. After a schema change, run `drizzle-kit generate` again and commit the new folder.

---
Source: https://docs.colyseus.io/database/schemas


# Services

Each `GameDatabase` instance exposes a set of services, read-and-write APIs over the built-in tables. All examples below assume the exported `db` instance from the [Quick start](https://docs.colyseus.io/database.md#quick-start).

## Cloud saves

Per-user save data with monotonic versioning. The `slot` is optional and defaults to `0`. Pass a different slot for multiple save files per player. Pass an `expectedVersion` for optimistic locking; a stale write throws `VersionConflictError`.

```ts
import { VersionConflictError } from "@colyseus/database";

// save(userId, data, slot = 0, expectedVersion?)
const { version } = await db.saves.save(userId, { hp: 100, level: 7 });

const save = await db.saves.load(userId); // { data, version } | null

try {
    // pass the expected version for optimistic locking
    await db.saves.save(userId, newData, 0, version);
} catch (e) {
    if (e instanceof VersionConflictError) {
        // another write landed in between: reload and merge
    }
}

await db.saves.listSlots(userId); // [{ slot, version, updatedAt }]
await db.saves.delete(userId);    // delete slot 0 for this user
```

## Leaderboards

Keep-best scoring with optional seasons.

```ts
await db.leaderboards.ensure("global", "Global Leaderboard");
await db.leaderboards.submit("global", userId, 1750);          // only kept if it beats the current best
await db.leaderboards.submit("global", userId, 999, "season-1"); // isolated per season

const top = await db.leaderboards.top("global", 10);
const nearby = await db.leaderboards.aroundMe("global", userId, 5);
```

## Live configs

Declare typed configuration keys with [Standard Schema](https://standardschema.dev/) validators (Zod, Valibot, etc.) via `defineConfigs`. Values are validated on write and cached in memory. When a `presence` is provided, the cache is invalidated across all server instances when a value changes (e.g. from an admin panel).

A key with no row yet resolves to the schema's default. With Zod 4, use `.prefault({})` on the object: `.default({})` returns `{}` as-is, without the field defaults.

```ts filename="src/app.config.ts"
import { defineServer, RedisPresence } from "colyseus";
import { GameDatabase, defineConfigs } from "@colyseus/database";
import { z } from "zod";

const configs = defineConfigs({
    matchmaking: z.object({
        minPlayers: z.number().int().default(2),
        maxPlayers: z.number().int().default(10),
    }).prefault({}), // no row yet: parse {} so the field defaults fill in
});

export const db = new GameDatabase({
    connectionString: process.env.DATABASE_URL,
    configsRegistry: configs,
    presence: new RedisPresence(), // cross-instance invalidation (optional)
});
```

```ts filename="src/rooms/Lobby.ts"
const mm = await db.configs.get("matchmaking"); // typed: { minPlayers, maxPlayers }

const unsubscribe = db.configs.subscribe("matchmaking", (value) => {
    // re-applied live whenever an admin changes it
});
```

## Analytics, moderation & notes

```ts
await db.analytics.track("match_completed", userId, { mode: "ranked", durationMs: 312_000 });

await db.moderation.setRole(userId, "mod");
await db.moderation.assignMod(userId, "guilds");    // mods act only on assigned collections
await db.moderation.can(userId, "read", "guilds");   // true
await db.moderation.can(userId, "delete", "guilds"); // false: "delete" is admin-only

await db.notes.add(userId, "Refunded once on 2026-04-12", authorId);
await db.notes.deleteAllForUser(userId); // GDPR cleanup
```

## Room plugins

For common patterns, `@colyseus/database` ships [Room Plugins](https://docs.colyseus.io/room/plugins.md) that wire the services above into the room lifecycle:

- **`CloudSavesPlugin`**: load a player's save on join, persist it on leave
- **`LeaderboardsPlugin`**: submit scores to one board
- **`AnalyticsPlugin`**: track room `create`/`join`/`leave`/`dispose` events

Plugin hooks run in a fixed order relative to the room's own hooks. The plugin's `onJoin` runs **before** the room's `onJoin`, and its `onLeave` runs **after** the room's `onLeave`. A room that creates the player entry in `onJoin` and removes it in `onLeave` therefore has no entry when the automatic load or save runs. Turn the automatic hooks off and call the plugin from the room, after creating the entry and before removing it:

```ts filename="src/rooms/MyRoom.ts"
import { Room, definePlugins } from "colyseus";
import { CloudSavesPlugin, LeaderboardsPlugin, AnalyticsPlugin } from "@colyseus/database";
import { GameState, Player } from "./schema";
import { db } from "../app.config";

export class MyRoom extends Room {
    state = new GameState();

    plugins = definePlugins([
        new CloudSavesPlugin({
            database: db,
            onJoin: "none",  // load after this room creates the player (see onJoin below)
            onLeave: "none", // save before this room removes it (see onLeave below)
            payload: (room, client) => room.state.players.get(client.sessionId).toJSON(),
            apply: (room, client, data) => room.state.players.get(client.sessionId).assign(data),
        }),
        new LeaderboardsPlugin({ database: db, boardId: "arena", submitOn: "none" }),
        new AnalyticsPlugin({ database: db, prefix: "arena", track: ["join", "leave"] }),
    ]);

    async onJoin(client) {
        this.state.players.set(client.sessionId, new Player());
        await this.plugins.cloudSaves.manualLoad(client);
    }

    async onLeave(client) {
        const player = this.state.players.get(client.sessionId);
        await this.plugins.cloudSaves.manualSave(client);
        await this.plugins.leaderboards.submitScore(client, player.score);
        this.state.players.delete(client.sessionId);
    }
}
```

The plugins resolve the user id from `client.auth.id` (set by the default `onAuth` of `@colyseus/auth`); pass `resolveUserId` to read it from elsewhere. `AnalyticsPlugin` needs no per-player state, so its automatic hooks work as-is: the example above writes `arena.join` and `arena.leave` rows.

`LeaderboardsPlugin`'s default `submitOn: "dispose"` submits the score of every client still connected when the room disposes. A room that disposes after its last player left has no clients by then, so submit from `onLeave` as above.

See [Room Plugins](https://docs.colyseus.io/room/plugins.md) for how plugins attach and expose methods.

---
Source: https://docs.colyseus.io/database/services


# Deploying your Colyseus server

Deploying Colyseus is no different than deploying a regular Node.js application. [See DigitalOcean's guide for the general setup](https://www.digitalocean.com/community/tutorials/how-to-set-up-a-node-js-application-for-production-on-ubuntu-22-04). Scaling to multiple processes or machines requires extra steps. See [Scalability](https://docs.colyseus.io/scalability.md).

> **Warning:**
>
> Consider using [Colyseus Cloud](https://cloud.colyseus.io/) to deploy and scale your Colyseus servers. Every item on the checklist below is handled for you.

- [Scalability](https://docs.colyseus.io/scalability.md)
- [Colyseus Cloud](https://docs.colyseus.io/cloud.md)

## Production checklist

- **Compile your TypeScript**: run `tsc` at deploy time and start the compiled entrypoint with plain `node`. The official template compiles to `build/index.js`. Do not run `tsx`/`ts-node` in production ([why](https://docs.colyseus.io/cloud/typescript-compilation-errors.md#running-tsx-directly-in-production-not-recommended)).
- **Set `NODE_ENV=production`**: dependencies and error verbosity behave accordingly, and `server.simulateLatency()` must never run in production.
- **Run under a process manager**: [PM2](https://pm2.keymetrics.io/) restarts crashed processes and plays well with Colyseus:

```js filename="ecosystem.config.js"
const os = require('os');

module.exports = {
    apps: [{
        name: "colyseus-app",
        script: 'build/index.js',
        time: true,
        watch: false,
        instances: os.cpus().length,
        exec_mode: 'fork',        // IMPORTANT: DO NOT use 'cluster' mode.
        wait_ready: true,
    }],
};
```

- **Serve over HTTPS**: put a reverse proxy in front (Nginx or Apache below) with a certificate from [Let's Encrypt](https://letsencrypt.org). The SDK connects via `https://` and upgrades to secure WebSockets (`wss://`) automatically.
- **Let deploys drain gracefully**: Colyseus registers a [graceful shutdown](https://docs.colyseus.io/server/graceful-shutdown.md) routine on `SIGTERM`/`SIGINT`: rooms are notified, clients receive `SERVER_SHUTDOWN` (`4001`), and the process exits when empty.
- **Expose a health check**: a plain [HTTP route](https://docs.colyseus.io/server/http-routes.md) returning `200` lets your load balancer or uptime monitor probe each process.
- **More than one process or machine?**: you need a shared `presence` and `driver`, and a public address per process. Follow [Scalability](https://docs.colyseus.io/scalability.md).

---

## Self-hosting on [Vultr](https://www.vultr.com/?ref=9632185-9J)

A pre-configured Colyseus server is available on [Vultr Marketplace](https://www.vultr.com/marketplace/apps/colyseus/?ref=9632185-9J). It's a good option if you want to self-host your Colyseus server.

This server is configured with:

- Node.js LTS
- PM2
- Nginx
- FREE `colyseus.dev` subdomain with SSL (Let's Encrypt)

Follow the instructions at Vultr Marketplace to start your server.

---

## Nginx configuration

When self-hosting, it is recommended to use `nginx` and `pm2` in your production environment.

### Nginx configuration

```conf filename="/etc/nginx/sites-available/yourdomain.com"
server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://localhost:2567;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
        include proxy_params;
    }
}
```

### Nginx configuration with SSL

It's recommended to acquire your certificate from [LetsEncrypt](https://letsencrypt.org).

```conf filename="/etc/nginx/sites-available/yourdomain.com"
server {
    listen 80;
    listen 443 ssl;
    server_name yourdomain.com;

    ssl_certificate /path/to/your/cert.crt;
    ssl_certificate_key /path/to/your/cert.key;

    location / {
        proxy_pass http://localhost:2567;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
        include proxy_params;
    }
}
```

> **Note:**
>
> Sticky sessions are **not** required: the seat reservation already binds each client to the process that created its room. For proxying multiple processes, see [Scalability → NGINX](https://docs.colyseus.io/scalability.md#use-nginx-as-a-reverse-proxy) or the [Traefik Load Balancer](https://docs.colyseus.io/scalability/traefik.md).

---

## Apache configuration

Here's how to use Apache as a proxy to your Node.js Colyseus app. (Thanks [tomkleine](https://github.com/tomkleine)!)

Install the required Apache modules:

```sh filename="Terminal"
sudo a2enmod ssl
sudo a2enmod proxy
sudo a2enmod proxy_http
sudo a2enmod proxy_html
sudo a2enmod proxy_wstunnel
```

Virtual host configuration:

```conf filename="/etc/apache2/sites-available/yourdomain.com.conf"
<VirtualHost *:80>
    ServerName servername.xyz
    # Redirect all requests received from port 80 to the HTTPS variant (force ssl)
    RewriteEngine On
    RewriteRule ^(.*)$ https://%{HTTP_HOST}$1 [R=301,L]
</VirtualHost>

<VirtualHost *:443>
    ServerName servername.xyz

    # enable SSL
    SSLEngine On
    SSLCertificateFile          /PATH/TO/CERT/FILE
    SSLCertificateKeyFile       /PATH/TO/PRIVATE/KEY/FILE

    #
    # setup the proxy to forward websocket requests properly to a normal websocket
    # and vice versa, so there's no need to change the colyseus library or the
    # server for that matter
    #
    # note: this proxy automatically converts the secure websocket (wss)

    RewriteEngine On
    RewriteCond %{HTTP:UPGRADE} ^WebSocket$           [NC,OR]
    RewriteCond %{HTTP:CONNECTION} ^Upgrade$          [NC]
    RewriteRule .* ws://127.0.0.1:APP-PORT-HERE%{REQUEST_URI}  [P,QSA,L]

    # setup the proxy to forward all https requests to http backend
    # (also automatic conversion from https to http and vice versa)

    ProxyPass "/" "http://localhost:APP-PORT-HERE/"
    ProxyPassReverse "/" "http://localhost:APP-PORT-HERE/"

</VirtualHost>
```

---

## Docker

### Requirements

- Download and install [Docker](https://www.docker.com/)
- `package.json` and `package-lock.json` are in the project.
- Set up the `npm start` command so it starts the server

### Create `Dockerfile` in the root of the Colyseus project

```dockerfile filename="Dockerfile"
FROM node:22

ENV PORT 2567

WORKDIR /usr/src/app

# A wildcard is used to ensure both package.json AND package-lock.json are copied
COPY package*.json ./

RUN npm ci
# run this for production
# npm ci --only=production

COPY . .

EXPOSE 2567

CMD [ "npm", "start" ]
```

### Create `.dockerignore` file in the same directory

```txt filename=".dockerignore"
node_modules
npm-debug.log
```

This will prevent your local modules and debug logs from being copied onto your Docker image and possibly overwriting modules installed within your image.

### Build Docker Image

Go to the directory that has your Dockerfile and run the following command to build the Docker image. The -t flag lets you tag your image so it's easier to find later using the docker images command:

```sh filename="Terminal"
docker build -t <your username>/colyseus-server .
```

### Confirm Image Build

Your image will now be listed by Docker with following command:

```sh filename="Terminal"
docker images
```

Output:

```txt
# Example
REPOSITORY                         TAG        ID              CREATED
node                               22         1934b0b038d1    About a minute ago
<your username>/colyseus-server    latest     d64d3505b0d2    About a minute ago
```

### Run the Docker Image

Run the Docker Image with following command:

```sh filename="Terminal"
docker run -p 2567:2567 -d <your username>/colyseus-server
```

Running your image with -d runs the container in detached mode, leaving the container running in the background. The -p flag redirects a public port to a private port inside the container.

### Done

Done, now you can connect to the server with `localhost:2567`

### More information:

- [Official Node.js Docker Image](https://hub.docker.com/_/node/)
- [Node.js Docker Best Practices Guide](https://github.com/nodejs/docker-node/blob/master/docs/BestPractices.md)

---
Source: https://docs.colyseus.io/deployment


# Frequently Asked Questions

## Performance & Scaling

### How many CCU can a Colyseus server handle?

The maximum number of concurrent users (CCU) a Colyseus server can handle depends on several factors:

- **CPU**: How intensive your game loop and message handlers are. Complex physics or AI calculations will limit CCU.
- **RAM**: Each connection and room state consumes memory. A typical connection uses ~2-5KB, but this grows with your state size. Monitor memory usage to avoid OOM crashes.
- **Bandwidth**: The frequency and size of state patches sent to clients. Use [State View](https://docs.colyseus.io/state/view.md) to reduce per-client traffic.
- **File descriptors**: Linux servers default to ~1024 open connections. This limit can be increased via `ulimit -n` (e.g., `ulimit -n 65535`), but ensure your hardware can handle the load.

As a baseline, a small cloud server (1 vCPU, 1GB RAM) can typically handle 1,000-2,000 concurrent connections for simple games. For complex games with large state, expect fewer. Always load test your specific use case.

### How can I improve performance?

- **Reduce state size**: Only include data that needs to be synchronized. Use messages for transient data.
- **Optimize patch rate**: The default `patchRate` is 50ms. Increase it if your game doesn't need frequent updates.
- **Use State View**: Limit what each client sees using [State View](https://docs.colyseus.io/state/view.md) to reduce bandwidth per client.
- **Profile your room code**: Avoid heavy computations.

[Optimizing State](https://docs.colyseus.io/state/optimization.md) covers what a patch costs in bytes, and which field types, schema shapes and collection operations make it smaller.

### Does Colyseus help me with client-prediction?

Yes. Colyseus 0.18 ships first-class **client-side prediction and lag compensation**: `room.input()` / `Predict` on the client, `defineInput()` / `setFixedTimestep()` / `allowRewindState()` on the server. See [Netcode](https://docs.colyseus.io/netcode.md) for the full stack. To learn the underlying concepts from scratch, the [Phaser tutorial](https://docs.colyseus.io/learn/tutorial/phaser/client-predicted-input.md) builds them by hand.

---

## Connection Issues

### I'm getting `"Error: seat reservation expired"`, what does it mean?

This error means that the client was not able to effectively connect with the server's room in time.

**This error may appear in a few scenarios:**

- Server is under heavy load and by the time it can respond to a WebSocket connection request, the "seat reservation" code has already expired. [You may increase the seat reservation time limit](https://docs.colyseus.io/matchmaker.md#reserve-a-seat-for) to remedy this.
- You have mixed Colyseus package versions in your `package.json` (between `0.14.x` and `0.15.x`, for example).
  Make sure to only use packages under `0.15.x` (if you are using version 0.15)
  or `0.14.x` (if you are using version 0.14). The exact patch version does not
  matter, but major and minor do.
- When using multiple Node.js processes, your [scalability configuration](https://docs.colyseus.io/scalability.md) may not be correct. Make sure to follow scalability instructions.

### How do I handle reconnection?

When a client disconnects (e.g., closed browser tab), you can allow them to reconnect to the same room:

1. Store the `room.reconnectionToken` on the client after joining
2. Use `client.reconnect(reconnectionToken)` to rejoin
3. On the server, set `allowReconnection` in `onLeave`:

```ts {7}
import { CloseCode } from "colyseus";
// ...

async onLeave(client, code) {
    if (code !== CloseCode.CONSENTED) {
        // Allow reconnection for 30 seconds
        await this.allowReconnection(client, 30);
    }
}
```

---

## State Synchronization

### Why is my room state not synchronizing with the client?

If you define your state with [`@type()` decorators](https://docs.colyseus.io/state/schema/decorators.md) and target ES2022/ESNext in TypeScript, set `"useDefineForClassFields": false` in your tsconfig. This flag makes sure the decorators define property accessors properly. (The [`schema()` builder](https://docs.colyseus.io/state/schema.md) does not need any tsconfig flags.)

```json filename="tsconfig.json"
{
    "compilerOptions": {
        "useDefineForClassFields": false,
        "experimentalDecorators": true
    }
}
```

> **Note:**
>
> See [colyseus/colyseus#510](https://github.com/colyseus/colyseus/issues/510) for more details.

### How can I sync data only to a specific client?

Support for per-client state visibility was introduced in version `0.16`. You can use the `StateView` class to control which parts of the state are visible to each client. See [State View](https://docs.colyseus.io/state/view.md) for more details.

### When should I use state vs messages?

| Use **State** when... | Use **Messages** when... |
|-----------------------|--------------------------|
| Data needs to persist | Event is one-time |
| All/new clients need the value | Only current clients care |
| Data changes frequently | Triggering an action/effect |
| Example: positions, scores | Example: chat, events |

---

## TypeScript Errors

### I'm getting this error: `Class constructor Room cannot be invoked without 'new'"`, what should I do?

This error appears when the `target` in your `tsconfig.json` is below `es2015`. The official template uses `ESNext`:

```json filename="tsconfig.json"
{
    "compilerOptions": {
        "target": "ESNext"
    }
}
```

### TypeScript decorators aren't working

Ensure these settings in your `tsconfig.json` (see [Decorators](https://docs.colyseus.io/state/schema/decorators.md) for details):

```json filename="tsconfig.json"
{
    "compilerOptions": {
        "experimentalDecorators": true,
        "useDefineForClassFields": false
    }
}
```

---

## Unity SDK

### Unity WebSocket connection drops during debugging

If you set a breakpoint while the WebSocket connection is open, the connection closes automatically after 3 seconds due to inactivity. To prevent this, use `pingInterval: 0` during development:

```ts filename="app.config.ts"
import { defineServer } from "colyseus";
import { WebSocketTransport } from "@colyseus/ws-transport";

const server = defineServer({
    transport: new WebSocketTransport({
        pingInterval: 0, // Disable for debugging
    }),
});
```

> **Warning:**
>
> Remember to set `pingInterval` back to a positive value (default: 3000) in production.

### How do I test multiple Unity clients locally?

Starting with Unity 6000.1.0b1, use [Multiplayer Play Mode](https://docs-multiplayer.unity3d.com/mppm/current/about/). For older versions, use [ParrelSync](https://github.com/VeriorPies/ParrelSync).

---

## Rooms & Architecture

### When should I create separate room types?

Create separate room types when:
- Different game modes have different logic (e.g., `BattleRoom`, `LobbyRoom`)
- Different state structures are needed
- Different max players or configurations

Reuse room types when:
- The same game can have multiple instances (most common case)
- Only configuration differs (pass options on join)

### Can rooms communicate with each other?

Yes, using [Presence](https://docs.colyseus.io/server/presence.md). Rooms can publish/subscribe to channels to coordinate across instances:

```ts
// In Room A
this.presence.publish("game-events", { type: "tournament-start" });

// In Room B
this.presence.subscribe("game-events", (message) => {
    console.log("Received:", message);
});
```

### How do I persist room data?

Rooms are ephemeral by default. To persist data:
- Use a database (Postgres, MongoDB, Redis) to save game state
- Load state in `onCreate()`, save in `onDispose()`
- See [Database](https://docs.colyseus.io/database.md) for integration guides

---
Source: https://docs.colyseus.io/faq


# Getting Started

A Colyseus game has two parts: a server that runs your game rooms, and a client that connects to them. Set them up in this order.

### Create a server

Scaffold a Node.js server with one command, then add a first room to it. Every client SDK below connects to this server.

- [Create a Server](https://docs.colyseus.io/getting-started/server.md)

### Connect a client

Colyseus is unopinionated about the game engine or framework you use in the frontend. Pick the official SDK for your platform:

- [TypeScript](https://docs.colyseus.io/getting-started/typescript.md)
- [React](https://docs.colyseus.io/getting-started/react.md)
- [Unity](https://docs.colyseus.io/getting-started/unity.md)
- [MonoGame](https://docs.colyseus.io/getting-started/monogame.md)
- [Godot](https://docs.colyseus.io/getting-started/godot.md)
- [Defold Engine](https://docs.colyseus.io/getting-started/defold.md)
- [Construct 3](https://docs.colyseus.io/getting-started/construct3.md)
- [GameMaker](https://docs.colyseus.io/getting-started/gamemaker.md)
- [Cocos Creator](https://docs.colyseus.io/getting-started/cocos.md)
- [Haxe](https://docs.colyseus.io/getting-started/haxe.md)
- [Flutter](https://docs.colyseus.io/getting-started/flutter.md)
- [Swift](https://docs.colyseus.io/getting-started/swift.md)
- [Native SDK (C)](https://docs.colyseus.io/getting-started/native-sdk.md)
- [Discord Activity](https://docs.colyseus.io/getting-started/discord-activity.md)
- [WeChat](https://docs.colyseus.io/getting-started/wechat.md)

## 🤖 Using an AI coding agent

Most models learned Colyseus from material older than 0.18. Without guidance, they write `colyseus.js` imports, `Room<MyState>` generics and `client.id`. The [Colyseus skill](https://github.com/colyseus/skill) keeps the agent on the current APIs and has it check your installed version before writing any Room or Schema code. Install it for Claude Code, Codex, Cursor, Gemini CLI, Copilot or any other agent that supports skills:

``` bash filename="Terminal"
npx skills add colyseus/skill            # this project
npx skills add colyseus/skill --global   # every project
```

The skill activates on its own when a task involves Colyseus. Bundled docs cover the areas agents get wrong most (state, rooms, the client SDK, netcode), with links to the rest.

Without the skill, point the agent at [llms.txt](https://docs.colyseus.io/llms.txt). Every page is also served as raw markdown: append `.md` to its URL, e.g. [`/room.md`](https://docs.colyseus.io/room.md).

---
Source: https://docs.colyseus.io/getting-started


# Cocos Creator 3

[Cocos Creator](https://cocos.com/creator) is a Cross-Platform 2D/3D Game Creation Tool.

The Colyseus SDK for Cocos Creator works in the same way as the [JavaScript / TypeScript SDK](https://docs.colyseus.io/getting-started/typescript.md). The major difference is how to [import it from a TypeScript Component](#importing-from-the-extension) asset from Cocos Creator.

> **Note:**
>
> **Example project:** Check out the [Tic Tac Toe Example](https://github.com/colyseus/cocos-demo-tictactoe).

## Installation

### Install the Extension

- [Open the Cocos Store](https://store.cocos.com/app/en/detail/5086) (Menu: "Extension" &raquo; "Store")
- Search for "Colyseus SDK"
- Download the extension
- Decompress the zip file to `<path_to_your_project>/extensions/`
![image](https://user-images.githubusercontent.com/42052366/130320623-9b1e556b-4fe1-44a6-b0d7-1e44cc231555.png)
- Start up Cocos Creator, open extention manager (Menu: "Extension" &raquo; "Extension Manager")
- Click "search for plugins" button on the "Project" tab
- Enable the "colyseus-sdk" plugin
![image](https://user-images.githubusercontent.com/42052366/130320703-74e6ea85-e217-462a-ac77-01e933475257.png)

### Update your `tsconfig.json` file

Make sure you have `"esModuleInterop": true` under `"compilerOptions"`:

```json
  // ...

  /* Add your custom configuration here. */
  "compilerOptions": {
    // ...
    "esModuleInterop": true
    // ...
  }
  // ...
```

Reboot your Cocos Creator editor.

### Importing from the extension

You must import Colyseus from its extension path:

```typescript
import Colyseus from 'db://colyseus-sdk/colyseus.js';
```

Below is a more elaborate example you can copy and paste into your project.

Save the contents below as `NetworkManager.ts` under your `assets` folder.

```typescript
import { _decorator, Component, Node } from 'cc';
const { ccclass, property } = _decorator;

import Colyseus from 'db://colyseus-sdk/colyseus.js';

@ccclass('NetworkManager')
export class NetworkManager extends Component {
    @property hostname = "localhost";
    @property port = 2567;
    @property useSSL = false;

    client!: Colyseus.Client;
    room!: Colyseus.Room;

    start () {
        // Instantiate Colyseus Client
        // connects into (ws|wss)://hostname[:port]
        this.client = new Colyseus.Client(`${this.useSSL ? "wss" : "ws"}://${this.hostname}${([443, 80].includes(this.port) || this.useSSL) ? "" : `:${this.port}`}`);

        // Connect into the room
        this.connect();
    }

    async connect() {
        try {
            this.room = await this.client.joinOrCreate("my_room");

            console.log("joined successfully!");
            console.log("user's sessionId:", this.room.sessionId);

            this.room.onStateChange((state) => {
                console.log("onStateChange: ", state);
            });

            this.room.onLeave((code) => {
                console.log("onLeave:", code);
            });

        } catch (e) {
            console.error(e);
        }
    }
}
```

You can now attach `NetworkManager` as a Component on any Node from Cocos Creator.

Because we're using the `@property` decorator above, you can edit the `hostname`, `port` and `useSSL` from Cocos Creator editor:

![Colyseus SDK on TypeScript Component](https://docs.colyseus.io/cocos/cocos-creator-component.png)
![login](https://docs.colyseus.io/cocos/logged_in.jpg)

---

## Alternative: How to manually add the `colyseus.js` file into your project (without the extension)

- [Download the latest `colyseus-sdk.zip` release from GitHub](https://github.com/colyseus/colyseus/releases?q=%22%40colyseus%2Fsdk%22&expanded=true).
- Unzip the `colyseus-sdk.zip` file into the `assets/` folder.
- Move both `colyseus-cocos-creator.js` and `colyseus.d.ts` files into your Cocos Creator project's `scripts` folder.
- Click on the `colyseus-cocos-creator.js` file from the Assets panel, and enable to "Import As Plugin" (see image below)
- **TypeScript**: require it using `import Colyseus from "./colyseus-cocos-creator.js";`
- **JavaScript**: require it using `const Colyseus = require("./colyseus-cocos-creator.js");`

![Import as plugin](https://docs.colyseus.io/cocos/cocos-creator-import-as-plugin.png)

## Next Steps

- [Client SDK API Reference](https://docs.colyseus.io/sdk.md) - Full API documentation for all methods, events, and room operations
- [State Synchronization](https://docs.colyseus.io/state.md) - Understanding Schema definitions
- [Room API](https://docs.colyseus.io/room.md) - Server-side room implementation

---
Source: https://docs.colyseus.io/getting-started/cocos


# Construct 3

> **Note:**
>
> [Launch Construct3 FREE TRIAL here](https://www.construct.net/a/429195?t=construct3freetrial).

## Installation

- [ Download Construct 3 SDK](https://www.construct.net/en/make-games/addons/111/colyseus-multiplayer-sdk) ([ View source-code](https://github.com/colyseus/colyseus-construct3))

The plugin version must match your server's major version. Plugin `0.18.0.x` speaks the Colyseus 0.18 protocol and cannot connect to 0.17 servers.

| Plugin version | Colyseus server version |
|----------------|-------------------------|
| `0.18.0.x`     | `0.18.x`                |
| `0.17.0.x`     | `0.17.x`                |

> **Warning:**
>
> **You need a server to use Colyseus!**
>
> Construct has well-known existing features to "host" a multiplayer session from the frontend. This is not possible when using Colyseus. Colyseus is an authoritative **server**, written in Node.js. You can't let your frontend host the rooms directly.

## Example project

Please explore this demonstration project to understand how to use Colyseus with Construct3.

- [ Download `.c3p` and server files](https://github.com/colyseus/construct3-demo/archive/refs/heads/master.zip) ([ View source-code](https://github.com/colyseus/construct3-demo))
- Open the `RawUsage.c3p` file on [Construct3 Editor ↗](https://www.construct.net/a/429195?t=construct3).
- Start the local server by running `npm install` and then `npm start` on the `server` folder.

The example project covers the core concepts of using Colyseus with Construct 3:

### Joining a Room

Use the "Join Room" action to connect to a room on the server. Once connected, you can listen for incoming messages using "On Message" triggers, and handle disconnection with "On Leave".

![](https://docs.colyseus.io/construct3/join-room-handle-messages.png)

### Listening for changes in the State

Use "On State Change" to react whenever the server updates the room state. Access individual state properties using the expression syntax to read synchronized values like scores, positions, or game phase.

![](https://docs.colyseus.io/construct3/state-change.png)

### Listening for add/remove events on Maps and Arrays within the State

Track when items are added to or removed from collections (Maps and Arrays) in the state. These events are essential for handling dynamic lists like players joining/leaving or inventory changes.

![](https://docs.colyseus.io/construct3/state-items-add-or-remove.png)

## Request/Response

> **Note:**
>
> Requires plugin `0.18.0.0` or later and a Colyseus 0.18 server.

"Send request" works like "Send message", but waits for the server's reply. The server answers by [returning a value from its message handler](https://docs.colyseus.io/room.md#responding-to-a-message-requestresponse), or turns the request down with `ctx.reject(reason)`.

Every request carries a **Tag** of your choice, so the reply can be matched back to the request that produced it, the same way the HTTP actions work.

| ACE | Type | Description |
|-----|------|-------------|
| Send request | Action | Sends `Type` with `Message` and waits for the reply. |
| Send JSON request | Action | Same, with the payload written as a JSON string, e.g. `Colyseus.JSON("{ userId: 42 }")`. |
| On Room Response | Trigger | The server replied. Read the reply with `ResponseValue` / `ResponseValueAt`. |
| On Room Request Error | Trigger | The server rejected the request, the handler threw, no handler exists, the connection dropped, or no reply arrived within 10 seconds. |
| Request was rejected | Condition | True inside "On Room Request Error" when the server called `ctx.reject(reason)`. The reason is available through `ResponseValue`. |
| `ResponseTag` | Expression | Tag of the last reply or error. |
| `ResponseValue` | Expression | The reply. Objects are returned as JSON strings. |
| `ResponseValueAt("path")` | Expression | A nested value of the reply, e.g. `ResponseValueAt("profile.name")`. |
| `ResponseValueType` | Expression | `"number"`, `"string"`, `"boolean"`, `"object"` or `"undefined"`. |

A deliberate rejection is part of your game's flow, not a failure: it triggers "On Room Request Error" but **not** "On Error (any)". Handler errors, missing handlers, disconnects and timeouts trigger both, and `ErrorMessage` describes what went wrong.

On the server, the same `messages` handlers serve both plain messages and requests:

```ts filename="MyRoom.ts"
messages = {
    "get-profile": async (client, { userId }) => {
        return await db.profiles.findById(userId); // → "On Room Response"
    },
    "buy-item": (client, { itemId }, ctx) => {
        const item = shop.get(itemId);
        if (!item) return ctx.reject({ reason: "unknown-item" }); // → "On Room Request Error" + "Request was rejected"
        return { balance: item.buy(client) };
    },
}
```

## Room Clock

> **Note:**
>
> Requires plugin `0.18.0.0` or later and a Colyseus 0.18 server.

The room keeps a clock synchronized with the server, which you can read from expressions:

| Expression | Description |
|------------|-------------|
| `ServerNow` | Estimated current server time, in milliseconds. |
| `RenderNow` | Smoothed server time, suitable for interpolating remote entities. |
| `RoundTripTime` | Measured round-trip time to the room, in milliseconds. |
| `Jitter` | Variation of the round-trip time, in milliseconds. |

The clock only synchronizes on rooms that call [`defineInput()`](https://docs.colyseus.io/netcode/server-input.md) on the server. On any other room, `ServerNow` and `RenderNow` return the local time, and `RoundTripTime` and `Jitter` return `0`. All four return `-1` while not connected to a room. For a one-off measurement on any room, use the "Get Room Ping" action and the `CurrentPing` expression instead.

## Next Steps

- [Client SDK API Reference](https://docs.colyseus.io/sdk.md) - Full API documentation for all methods, events, and room operations
- [Request/Response](https://docs.colyseus.io/sdk.md#requestresponse) - How requests and replies work in the SDK
- [State Synchronization](https://docs.colyseus.io/state.md) - Understanding Schema definitions
- [Room API](https://docs.colyseus.io/room.md) - Server-side room implementation

---
Source: https://docs.colyseus.io/getting-started/construct3


# Defold Engine

The Colyseus SDK for Defold supports all major platforms, including:

- HTML5,
- iOS,
- Android
- Native (Mac, and Windows.)

## Install package

From your `game.project` file, add the following Dependencies to your project:

```txt
https://github.com/colyseus/colyseus-defold/archive/0.18.zip
```

```txt
https://github.com/defold/extension-websocket/archive/4.2.1.zip
```

Now, select **Project** ▸ **Fetch Libraries** to update library dependencies. Two folders with the library names should appear in your Defold project, indicating the libraries have been imported correctly.

> **Note:**
>
> Read more about [Setting up library dependencies](https://defold.com/manuals/libraries/#setting-up-library-dependencies) on Defold documentation.

## SDK Example Project

The [colyseus-defold](https://github.com/colyseus/colyseus-defold) repository contains a raw example project that demonstrates the SDK features. To run the example:

1. Clone the repository: `git clone https://github.com/colyseus/colyseus-defold.git`
2. Open the project in Defold Editor

### Running the test server locally

To run the test server locally, you will need to run the following commands in your terminal:

```sh filename="Terminal"
git clone https://github.com/colyseus/sdks-test-server
cd sdks-test-server
npm install
npm start
```

> **Note:**
>
> You can see the source code for the test server [here](https://github.com/colyseus/sdks-test-server).

You should be able to see the server running at `http://localhost:2567`, and the example project will be able to connect to it.

## Quick Example

> **Note:**
>
> The state schema and messages in this example come from the room built in [Create a Server](https://docs.colyseus.io/getting-started/server.md). Start that server before you run it.

This example shows how to connect to a room, listen for state changes, send messages, and leave the room.

```lua filename="network.script"
local ColyseusSDK = require("colyseus.sdk")

local client
local room
local callbacks

function init(self)
    client = ColyseusSDK.Client("ws://localhost:2567")

    client:join_or_create("my_room", {}, function(err, _room)
        if err then
            print("JOIN ERROR: " .. err)
            return
        end

        room = _room
        print("Joined room: " .. room.room_id)

        -- Get state callbacks handler
        callbacks = ColyseusSDK.callbacks(room)

        -- Listen for players being added
        callbacks:on_add("players", function(player, sessionId)
            print("Player joined: " .. sessionId)

            callbacks:listen(player, "x", function(currentX, previousX)
                print("Player " .. sessionId .. " x: " .. tostring(currentX))
            end)
        end)

        -- Listen for players being removed
        callbacks:on_remove("players", function(player, sessionId)
            print("Player left: " .. sessionId)
        end)

        -- Send a message to the server
        room:send("move", { x = 10, y = 20 })

        -- Listen for messages from the server
        room:on_message("chat", function(message)
            print("Chat: " .. message)
        end)

        room:on_leave(function(code)
            print("Left room: " .. code)
        end)
    end)
end
```

## Client-side prediction

Colyseus 0.18 ships the full netcode stack for Defold. You get input on a fixed
timestep, rollback-and-replay reconciliation of your own entity, and
interpolation of the entities you don't control. [Client Prediction &
Reconciliation](https://docs.colyseus.io/netcode/client-prediction.md) covers it in depth. Every example
there has a **Lua** tab. The Defold-shaped loop:

```lua filename="network.script"
local Predict = require("colyseus.predict.predict")

local predict = Predict.get(room)
local input = room:input()

-- Entities you DON'T control: interpolated, rendered 100ms in the past.
predict:attach_all("players", { mode = "lerp", fields = { "x", "y" } })

-- Your own entity: predicted immediately, rolled back and replayed on each ack.
local me = predict:sim({
    input = input,
    world = { paddle = room.state.players[room.session_id], puck = room.state.puck },
    step = function(ctx, world, cmd)   -- the SAME function the server runs
        apply_input(world, cmd, ctx.dt)
    end,
    smooth_ms = 65,
})

function update(self, dt)
    -- tick() FIRST: it advances the render clock every value() read below uses,
    -- and returns how many fixed input steps are due this frame.
    local steps = predict:tick()
    for _ = 1, steps do
        input.data.dx, input.data.dy = move_axis()
        input:send()
    end
    draw(predict:value(room.state.puck, "x"), predict:value(room.state.puck, "y"))
end
```

`Predict.get(room, options)` takes the same options as an attach and uses them
as defaults, so `Predict.get(room, { mode = "lerp", delay = 100 })` lets every
attach name only its fields.

> **Note:**
>
> **Translating the JavaScript examples.** The Lua surface is the same API in
> Defold spelling. Methods and option keys are `snake_case` (`attach_all`,
> `smooth_ms`, `render_delay`, `on_predict`, `unique_by`). Method calls use
> `:`, so a callback context reads `ctx:predict(channel, payload)`.

## SDK API

Navigate to the [ Client SDK](https://docs.colyseus.io/sdk.md) for API Reference, and select the **Lua (Defold)** tab.

## FAQ

### Defold Editor is not opening the project!

If you placed your server directory inside the Defold project directory, the Defold Editor might fail to load the project. You can fix this by adding the server directory to the `.defignore` file.

```txt filename=".defignore"
/server
```

### "I can't connect to the local server!"

When running on localhost, make sure no other service is running on port 80.
Otherwise the client won't connect to the specified port number.

Alternatively, you can bind the Colyseus server to port 80.

**WSL2 Users**

When running the colyseus server inside WSL2, you won't be able to use `localhost` as the hostname.
You'll need to get the WSL2 machine's IP by using `wsl hostname -I` and use that IP.

### "How do I point a build at a different server?"

`os.getenv()` returns `nil` on HTML5, so the endpoint cannot come from the
environment there. Put it in `game.project` and read it with
`sys.get_config_string`, which works on every platform:

```txt filename="game.project"
[colyseus]
endpoint = ws://localhost:2567
```

```lua
local endpoint = sys.get_config_string("colyseus.endpoint", "ws://localhost:2567")
client = ColyseusSDK.Client(endpoint)
```

Bundling overrides it without touching the file:

```sh filename="Terminal"
java -jar bob.jar --config=colyseus.endpoint=wss://your-server.example.com \
    resolve build bundle
```

### "`reconnect()` is not working on iOS!"

If you lock your phone, all WebSocket connections will be closed. You can call `reconnect()` to reestablish the session, which needs a workaround for iOS:

```lua
function window_callback(self, event, data)
    if event == window.WINDOW_EVENT_FOCUS_GAINED then
        -- iOS workaround to re-active WebSocket connection after phone is unlocked
        room:send("whatever")
    end
end

window.set_listener(window_callback)
```

## Next Steps

- [Client SDK API Reference](https://docs.colyseus.io/sdk.md) - Full API documentation (select the **Lua (Defold)** tab)
- [Client Prediction & Reconciliation](https://docs.colyseus.io/netcode/client-prediction.md) - Input, rollback and interpolation
- [Server Input & Timestep](https://docs.colyseus.io/netcode/server-input.md) - The server half of the netcode stack
- [State Synchronization](https://docs.colyseus.io/state.md) - Understanding Schema definitions
- [Room API](https://docs.colyseus.io/room.md) - Server-side room implementation

---
Source: https://docs.colyseus.io/getting-started/defold


# Discord Activity

[This Project Template](https://github.com/colyseus/discord-activity) is a starting point for crafting HTML5 multiplayer Discord Activities.

![Video](https://docs.colyseus.io/tutorial/discord/video.gif)

> **Note:**
>
> Check out the [Discord Activity Examples](https://docs.colyseus.io/learn/examples/discord.md) to see how to use the Discord Activity SDK with Colyseus.

## Project Structure

The frontend and backend are separated into two different modules.

- `apps/client/` - Has the frontend project, using Pixi.js and Vite
- `apps/server/` - Has the backend project, using Colyseus (Node.js)

## Environment variables

Both the `client` and `server` projects need environment variables configured from your Discord Activity.

- `apps/client/.env` - Should contain your "OAuth2 → Client ID" under `VITE_DISCORD_CLIENT_ID`.
- `apps/server/.env` - Should contain your "OAuth2 → Client ID" under `DISCORD_CLIENT_ID` and "OAuth2 → Client Secret" under `DISCORD_CLIENT_SECRET`.

## Testing your local Discord Activity

In order to test your Discord Activity locally, you need to expose your local server to the public internet.

We will need to open 3 terminal windows to run the server, client, and the `cloudflared` tunnel.

1. Start the server

```
npm run start:server
```

2. Start the client

```
npm run start:client
```

3. Use `cloudflared` or `ngrok` for exposing your local server to a public URL _([see complete tutorial here](https://discord.com/developers/docs/activities/building-an-activity#step-4-running-your-app-in-discord))._

During development, there's no need to expose the `server` to the public internet - only the `client`. Our Vite development server proxies the `/colyseus` requests to our local server.

```
npm run cloudflared
```

![cloudflared-screenshot](https://docs.colyseus.io/tutorial/discord/cloudflared-screenshot.png)

You will need to update your Discord Activity's "OAuth2 → Redirect URL" and "URL Mappings → Target" to the URL provided by `cloudflared`:

![](https://docs.colyseus.io/tutorial/discord/settings-oauth.png)
![](https://docs.colyseus.io/tutorial/discord/settings-url-mappings.png)

> **Warning:**
>
> Each time you run `cloudflared`, it will generate a new URL. Be sure to update your Discord Activity's "OAuth2 → Redirect URL" and "URL Mappings → Target" to the new URL.

_(Be sure to complete all the steps listed [here](https://discord.com/developers/docs/activities/building-an-activity) to ensure your development setup is working as expected.)_

---

### Using [Colyseus Cloud](https://colyseus.io/cloud-managed-hosting/)

When using Colyseus Cloud with Scalability, you must configure the following URL Mappings:

![Production URL Mappings](https://docs.colyseus.io/tutorial/discord/production-url-mappings.png)

When instantiating the `Client` SDK, you should do as follows:

- `new Client('https://[subdomain].colyseus.cloud')`

---

## Deploying your Discord Activity

When deploying your Discord Activity, you will generally need to deploy the `client` and `server` projects separately, under their own public URLs.

> **Note:**
>
> You can use services like Vercel, Netlify, or Heroku to deploy your client project. For the server project, use [Colyseus Cloud](https://colyseus.io/cloud-managed-hosting/), [Vultr](https://www.vultr.com/marketplace/apps/colyseus/?ref=8013231), AWS, or DigitalOcean.

You will need to configure your Discord Activity's URLs:

- "OAuth2 → Redirect URL" to point to your deployed **client** project.
- "URL Mappings → Root Mapping / Target" to point to your deployed **client** project.
- "URL Mappings → Prefix `/colyseus` / Target" to point to your deployed **server** project.

## Next Steps

- [Client SDK API Reference](https://docs.colyseus.io/sdk.md) - Full API documentation for all methods, events, and room operations
- [State Synchronization](https://docs.colyseus.io/state.md) - Understanding Schema definitions
- [Room API](https://docs.colyseus.io/room.md) - Server-side room implementation

---
Source: https://docs.colyseus.io/getting-started/discord-activity


# Flutter

> **Warning:**
>
> The Flutter SDK is in **beta**, and may not be stable. Please [report any issues you find](https://github.com/colyseus/native-sdk/issues).

The Flutter SDK is `dart:ffi` bindings over the shared [Colyseus Native SDK](https://github.com/colyseus/native-sdk), which provides cross-platform support for Colyseus across different engines. The work on Native SDK is still in progress, so expect some breaking changes as we go.

## Platforms

- macOS (10.15+)
- iOS (13.0+)
- Android (API 21+)
- Linux (x86_64)
- Windows (x86_64)

Web is not supported. That target needs the SDK's Emscripten build and a different transport.

The package requires Dart `3.3.0` or newer and Flutter `3.19.0` or newer. Prebuilt native libraries ship inside the package, so there is no toolchain to install.

## Installation

```sh filename="Terminal"
flutter pub add colyseus
```

Then import the single entry point:

```dart
import 'package:colyseus/colyseus.dart';
```

### macOS and iOS

Both platforms need the outbound-network entitlement, `com.apple.security.network.client`. Add it to **both** `macos/Runner/DebugProfile.entitlements` and `macos/Runner/Release.entitlements`:

```xml filename="macos/Runner/Release.entitlements"
<key>com.apple.security.network.client</key>
<true/>
```

> **Warning:**
>
> `flutter create` does not add the entitlement. Without it every connection fails silently inside the sandbox, with no error to catch.

### Android

The plugin declares no permissions of its own, so your app must request internet access:

```xml filename="android/app/src/main/AndroidManifest.xml"
<uses-permission android:name="android.permission.INTERNET"/>
```

## Project Setup

By default the SDK polls the network on its own 16 ms timer, and you can join a room without any further setup.

Games that render every frame should drive the SDK instead. Set `Colyseus.autoPoll` to `false` once, then call `Colyseus.pump()` at the top of your frame callback. Decoding, prediction and rendering then all observe the same state within a frame:

```dart filename="lib/game.dart"
class _GameState extends State<Game> with SingleTickerProviderStateMixin {
  late final Ticker _ticker;

  @override
  void initState() {
    super.initState();

    Colyseus.autoPoll = false; // the app owns the frame from here on
    _ticker = createTicker(_onFrame)..start();
  }

  void _onFrame(Duration _) {
    Colyseus.pump(); // decode inbound traffic, then deliver listeners

    // read room state and draw
  }

  @override
  void dispose() {
    _ticker.dispose();
    super.dispose();
  }
}
```

## Quick Example

> **Note:**
>
> The state schema and messages in this example come from the room built in [Create a Server](https://docs.colyseus.io/getting-started/server.md). Start that server before you run it.

This example shows how to connect to a room, listen for state changes, send messages and leave the room.

```dart filename="lib/network.dart"
import 'package:colyseus/colyseus.dart';

ColyseusClient? client;
ColyseusRoom? room;

Future<void> connect() async {
  client = ColyseusClient('ws://localhost:2567');

  // Options are optional, and are JSON-encoded before they are sent.
  final joined =
      await client!.joinOrCreate('my_room', options: {'name': 'Player 1'});
  room = joined;

  print('Joined ${joined.name} (${joined.id}) as ${joined.sessionId}');

  joined.onStateChange.listen((_) {
    final players = joined.state?.getMap('players');
    print('players: ${players?.length ?? 0}');
  });

  joined.onMessage('chat').listen((message) => print('chat: $message'));

  joined.onError.listen((e) => print('error ${e.code}: ${e.message}'));
  joined.onLeave.listen((code) => print('left with code $code'));

  joined.send('move', {'x': 10, 'y': 20});
}

Future<void> disconnect() async {
  await room?.leave();

  // Dispose the room before the client: the room owns the decoder and any
  // prediction layers built over it.
  room?.dispose();
  client?.dispose();
}
```

Every join method returns a `Future<ColyseusRoom>`. `options:` is JSON-encoded and sent to the server; `stateType:` types the room (see [Reading State](#reading-state)):

| Method | Description |
| --- | --- |
| `joinOrCreate(roomName, options: ..., stateType: ...)` | Join an available room, or create one |
| `join(roomName, ...)` | Join an existing room only |
| `create(roomName, ...)` | Always create a new room |
| `joinById(roomId, ...)` | Join a specific room by its id |
| `reconnect(reconnectionToken, stateType: ...)` | Rejoin a room this client was dropped from |
| `consumeSeatReservation(reservation, stateType: ...)` | Join with a seat your backend reserved; read it with `SeatReservation.fromJson()`. See [Consuming a Seat Reservation](https://docs.colyseus.io/sdk.md#consuming-a-seat-reservation). Requires 0.18.5 |

> **Note:**
>
> The join future resolves as soon as the server confirms the seat, which can happen before the first state patch arrives. Code that looks for its own entity in the state should wait for `onStateChange` rather than reading immediately.

## Sending Messages

```dart
room.send('move', {'x': 10, 'y': 20}); // Map, List, String, num, bool or null
room.send('ready');                    // payload is optional

room.sendInt(1, [10, 20]);             // numeric message type
room.sendBytes('snapshot', bytes);     // raw Uint8List
```

## Receiving Messages

Room events are Dart broadcast streams, so you subscribe with `listen` instead of assigning a handler:

```dart
room.onMessage('chat').listen((data) {
  print(data['text']);
});

// Every message, whatever its type.
room.onMessageAny.listen((entry) {
  print('${entry.key}: ${entry.value}');
});
```

The room exposes these listeners:

| Listener | Type | Fires when |
| --- | --- | --- |
| `onJoin` | `Stream<void>` | the client is seated in the room |
| `onStateChange` | `Stream<void>` | a state patch has been applied |
| `onMessage(type)` | `Stream<dynamic>` | the server sends a message of `type` |
| `onMessageAny` | `Stream<MapEntry<String, dynamic>>` | the server sends any message |
| `onError` | `Stream<ColyseusError>` | the server reports an error, with `code` and `message` |
| `onLeave` | `Stream<int>` | the room closes, carrying the close code |
| `onDrop` | `Stream<ColyseusError>` | the connection drops and automatic reconnection starts |
| `onReconnect` | `Stream<void>` | automatic reconnection succeeds |

## Reading State

Generate one Dart class per schema from your server's types. Codegen is optional, and it buys type safety and autocomplete in your IDE:

```sh filename="Terminal"
npx schema-codegen src/rooms/schema/* --dart --bundle --output ../client/lib/gen/
```

> **Note:**
>
> See the full [State Schema Codegen documentation](https://docs.colyseus.io/state/callbacks.md#frontend-schema-generation) for more options and details.

Join with the generated root class, the Dart spelling of C#'s `JoinOrCreate<MyRoomState>("my_room")`. The room is then typed end to end: `room.state` is a `MyRoomState?`, and `onStateChange` fires with it after every patch.

```dart
import 'gen/schema.dart';

final room = await client.joinOrCreate('my_room', stateType: MyRoomState.new);
final state = await room.onStateChange.first;   // MyRoomState, first patch

for (final entry in state.players.entries) {
  print('${entry.key}: ${entry.value.x}, ${entry.value.y}');
}

final me = state.players[room.sessionId]!;
print(me.hp);
```

Reading `room.state` every frame is the intended pattern. The room keeps the wrapper while the underlying instance lives and rebuilds it on reconnect, when the decoder replaces the whole state. `room.stateAs(OtherClass.new)` still exists for narrowing the root to a class other than the room's own `stateType:`.

### Without codegen

The same state reads dynamically. `room.state` is the root instance; collections come back as `SchemaMap` and `SchemaArray`:

```dart
final players = room.state!.getMap('players')!;

for (final entry in players.entries) {
  final player = entry.value as SchemaInstance;
  print('${entry.key}: ${player['x']}, ${player['y']}');
}

final me = players[room.sessionId] as SchemaInstance;
print(me['hp']);
```

| Accessor | Returns |
| --- | --- |
| `instance['field']` | the field value, typed from the schema |
| `instance.getMap('field')` | a `SchemaMap`, or null |
| `instance.getArray('field')` | a `SchemaArray`, or null |
| `instance.getRef('field')` | a nested `SchemaInstance`, or null |
| `instance.fieldNames` | every field declared on the type |

> **Warning:**
>
> Schema handles are raw native pointers. The decoder frees and replaces instances on a full resync or a reconnect. Read instances afresh from `room.state` rather than caching one across frames; the typed wrappers handle this for you.

### Fast reads

`SchemaInstance` looks a field up by name on every read, which is fine for occasional access. A step function running dozens of times per frame during rollback replay wants `SchemaView` instead. A view resolves each name once, then costs a single leaf call per access:

```dart
final view = SchemaView(me.handle);

final x = view['x'];              // double; booleans read as 0 or 1
final alive = view.getBool('alive');
final name = view.getString('name');

view['x'] = view['x'] + view['vx'] * dt;
```

Re-create views for decoded state when `onReconnect` fires, for the same reason instances must be re-read.

## State Callbacks

Schema callbacks live on their own object, obtained with `Callbacks.get(room)`, and follow the C# SDK's shape. Registration takes the field to observe, and collection handlers receive `(key, value)`. Passing a generated getter's value (`state.players`) is the Dart equivalent of C#'s `OnAdd(s => s.players, ...)`. The wrapper records which field it came from, so the registration binds to the field itself:

```dart
final callbacks = Callbacks.get(room);
final state = room.state!;   // joined with stateType: MyRoomState.new

callbacks.listen(state, 'currentTurn', (String value, String? previous) {
  print('turn: $previous -> $value');
});

callbacks.onAdd(state.players, (sessionId, player) {
  print('+ player joined: $sessionId');

  callbacks.listen(player, 'hp', (double hp, double? previous) {
    print('$sessionId hp: $previous -> $hp');
  });

  callbacks.onChange(player, () {
    print('$sessionId changed');
  });
});

callbacks.onRemove(state.players, (sessionId, player) {
  print('- player left: $sessionId');
});

callbacks.listenRef(state, 'host', Player.new, (host) {
  print('host changed: $host');
});
```

Map keys arrive as `String` and array indexes as `int`, both statically typed from the collection. The same registrations work by field name, with no generated classes:

```dart
callbacks.listen(room.state!, 'currentTurn', (value, previous) { ... });

callbacks.onAddByName(room.state!, 'players', (key, value) {
  callbacks.listen(value as SchemaInstance, 'hp', (hp, previous) { ... });
});

callbacks.onRemoveByName(room.state!, 'players', (key, value) { ... });
```

Registration replays what already decoded, so a late subscription still sees every player and `listen` fires with the current value (pass `immediate: false` to skip the replay). Each call returns a `StreamSubscription`; cancelling it releases the native callback.

## Prediction

Waiting for the server to confirm your own movement costs a round trip. The predict layer applies each input immediately and reconciles when the server disagrees. See [Client Prediction](https://docs.colyseus.io/netcode/client-prediction.md) for the concepts. Your room class must declare [`defineInput()`](https://docs.colyseus.io/netcode/server-input.md) before any of this works.

```dart filename="lib/gameplay.dart"
Colyseus.autoPoll = false; // the app drives the frame

final predict = Predict.get(room);
final input = room.input()!;

// Other players are smoothed, since their inputs aren't yours to predict.
predict.attachAll('players',
    config: {'x': PredictMode.damped, 'y': PredictMode.damped},
    exceptKey: room.sessionId);

// Yours is predicted and reconciled.
final me = room.state!.players[room.sessionId]!;
final recon = predict.reconciler(me,
  input: input,
  fields: const ['x', 'y', 'vx', 'vy'],
  step: (ctx, state, cmd) => stepPlayer(state, cmd, ctx.dt), // shared with the server
);

void onFrame() {
  Colyseus.pump();                    // decode inbound, deliver events

  final steps = predict.tick();       // reads room.clock.now for you
  for (var i = 0; i < steps; i++) {
    input.data['moveX'] = keyboard.x;
    input.send();                     // applied locally right away
  }

  draw(recon.value('x'), recon.value('y'));
}
```

Points worth knowing before you build on it:

- `room.input()` returns `null` when the server room declares no `defineInput()`, and throws if you call it before the join future resolves.
- `predict.tick()` reads `room.clock.now` when you pass nothing, which is the timebase the server shares. Pass your own only if it comes from that clock, never `DateTime.now()`.
- `step` has to compute exactly what the server computes. When it does, `recon.drift.ema` stays at the floating-point noise floor; when it drifts, that number tells you.
- Guard one-shot effects inside a step on `!ctx.isReplay`, or raise them through `ctx.predict()`, which is replay-safe.
- Call `input.reset()` on `onReconnect`. Sequence numbers restart at zero, so replaying the old ones would corrupt the mirror.

`Predict` also covers dead reckoning (`attachAllReckon`), optimistic events (`defineEvent`), predicted spawns (`spawns`) and composite simulations (`sim`).

## HTTP & Auth

`client.http` resolves paths against the client endpoint. A non-2xx reply throws `ColyseusHttpException`:

```dart
final res = await client.http.get('/test');
print(res.statusCode);
print(res.json['things']);

await client.http.post('/save', body: {'name': 'endel'});
```

`client.auth` covers the [authentication](https://docs.colyseus.io/auth.md) endpoints, and throws `ColyseusAuthException` on a rejected call:

```dart
final data = await client.auth.signInAnonymously();
print(data.user?['anonymousId']);

await client.auth.signInWithEmailAndPassword('user@example.com', 'secret');
await client.auth.registerWithEmailAndPassword('user@example.com', 'secret');
await client.auth.sendPasswordResetEmail('user@example.com');

// The token is shared with client.http, so later requests are authenticated.
client.auth.onChange.listen((d) {
  if (d.token == null) showLoginScreen();
});

client.auth.signOut();
```

> **Note:**
>
> The token persists in the platform's secure storage under one process-wide key, so it survives a restart. A test suite that signs in should sign out again, or set `client.auth.storageKey`, otherwise later clients send a token the next server rejects.

## Known Limitations

- **Request and response is not bound.** `room.request()` has no Dart equivalent yet. Use `send` with a matching `onMessage` listener instead.
- **Prediction does not link on Windows.** The predict layer is dead-stripped out of the Windows DLL. Every other platform links it.
- **Automatic reconnection works once per room.** A second drop leaves the room reconnecting indefinitely. The defect is in the shared core, so every Colyseus native binding has it.

## Next Steps

- [Netcode: Prediction & Lag Comp](https://docs.colyseus.io/netcode.md) - The prediction stack, and the server settings it needs
- [State Synchronization](https://docs.colyseus.io/state.md) - Understanding Schema definitions
- [Room API](https://docs.colyseus.io/room.md) - Server-side room implementation

---
Source: https://docs.colyseus.io/getting-started/flutter


# GameMaker

> **Warning:**
>
> The GameMaker extension is in **beta**, and may not be stable. Please [report any issues you find](https://github.com/colyseus/native-sdk/issues/16).

The GameMaker SDK is built on top of the shared [Colyseus Native SDK](https://github.com/colyseus/native-sdk), which provides cross-platform support for Colyseus across different engines. The work on Native SDK is still in progress, so expect some breaking changes as we go.

## Platforms

- Windows (x86_64)
- macOS (arm64, x86_64)
- Linux (x86_64)
- iOS (arm64)
- Android (arm64, arm32, x86_64)
- HTML5 (WASM). Chrome and other Chromium-based browsers need version 115 or newer.

## Installation

1. Download the latest `.yymps` from [GitHub Releases](https://github.com/colyseus/native-sdk/releases?q=gamemaker+sdk&expanded=true)
2. In GameMaker, go to **Tools → Import Local Package**
3. Select the `.yymps` file, select all resources, and click **Import**

The import adds the `Colyseus_SDK` extension and two scripts, `Colyseus` and `ColyseusPredict`, to your project. Keep both: the first calls into the second, so a project with only one of them does not compile.

## Project Setup

The SDK uses an **event queue** pattern to integrate with GameMaker's frame loop. You need an **Object** with **Create**, **Step**, and **Clean Up** events to manage the connection lifecycle.

You must call `colyseus_process()` once per frame in the **Step** event to poll and dispatch all queued events.

Create the client and join the room in the **Create** event, and free them in **Clean Up**.

## Quick Example

> **Note:**
>
> The state schema and messages in this example come from the room built in [Create a Server](https://docs.colyseus.io/getting-started/server.md). Start that server before you run it.

This example shows how to connect to a room, listen for state changes, send messages, and leave the room.

```js filename="Create_0.gml"
/// Create Event: connect and register the room handlers

client = colyseus_client_create("http://localhost:2567");
net_room = colyseus_client_join_or_create(client, "my_room", "{}");
net_setup_handlers(net_room);   // see below
```

```js filename="Step_0.gml"
/// Step Event: dispatch queued events every frame, then send input

colyseus_process();

if (colyseus_room_is_connected(net_room)) {
    var _dx = keyboard_check(vk_right) - keyboard_check(vk_left);
    var _dy = keyboard_check(vk_down) - keyboard_check(vk_up);
    if (_dx != 0 || _dy != 0) {
        x += _dx * 4;
        y += _dy * 4;
        colyseus_send(net_room, "move", { x: x, y: y });
    }
}
```

```js filename="scr_net.gml"
/// Room event handlers. Called from the object's Create event, so the
/// function literals below are bound to that instance and can store
/// instance variables (player_objs, callbacks).

function net_setup_handlers(net_room) {

    colyseus_on_join(net_room, function(_room) {
        show_debug_message("Joined room: " + colyseus_room_get_id(_room));
        show_debug_message("Session ID: " + colyseus_room_get_session_id(_room));

        // Store as instance variables (no "var") so nested callbacks can access them
        player_objs = {};
        callbacks = colyseus_callbacks_create(_room);

        // Listen for players added to the "players" map
        colyseus_on_add(callbacks, "players", function(instance, key) {
            show_debug_message("Player joined: " + key);

            var _px = colyseus_schema_get(instance, "x");
            var _py = colyseus_schema_get(instance, "y");
            var _player_obj = instance_create_depth(_px, _py, 0, obj_player);

            player_objs[$ key] = _player_obj;

            // GML anonymous functions can access instance variables (like "callbacks"),
            // but NOT outer local variables (declared with "var").
            // Use method() to pass local variables into nested callbacks:
            colyseus_listen(callbacks, instance, "x", method({ obj: _player_obj }, function(v, p) {
                obj.x = v;
            }));
            colyseus_listen(callbacks, instance, "y", method({ obj: _player_obj }, function(v, p) {
                obj.y = v;
            }));
        });

        // Listen for players removed from the map
        colyseus_on_remove(callbacks, "players", method({ objs: player_objs }, function(instance, key) {
            show_debug_message("Player left: " + key);
            if (variable_struct_exists(objs, key)) {
                instance_destroy(objs[$ key]);
                delete objs[$ key];
            }
        }));
    });

    colyseus_on_error(net_room, function(code, msg) {
        show_debug_message("Room error [" + string(code) + "]: " + msg);
    });

    colyseus_on_leave(net_room, function(code, reason) {
        show_debug_message("Left room [" + string(code) + "]: " + reason);
    });

    colyseus_on_message(net_room, function(_room, _type, _data) {
        // _data is auto-decoded: struct for maps, string/number/bool for primitives
        show_debug_message("Message [" + _type + "]: " + json_stringify(_data));
    });

}
```

```js filename="CleanUp_0.gml"
/// Clean Up Event: free resources

if (net_room != 0) {
    colyseus_room_leave(net_room);
    colyseus_room_free(net_room);  // also frees associated callbacks
}
if (client != 0) {
    colyseus_client_free(client);
}
```

## SDK API

### Client

| Function | Description |
| --- | --- |
| `colyseus_client_create(endpoint)` | Create a client. Returns a client handle. |
| `colyseus_client_free(client)` | Free client resources. |
| `colyseus_client_join_or_create(client, room_name, options_json)` | Join or create a room. Returns a room handle. |
| `colyseus_client_join(client, room_name, options_json)` | Join an existing room. |
| `colyseus_client_create_room(client, room_name, options_json)` | Create a new room. |
| `colyseus_client_join_by_id(client, room_id, options_json)` | Join a room by its ID. |
| `colyseus_client_reconnect(client, reconnection_token)` | Re-take a seat with a token saved from `colyseus_room_get_reconnection_token()`, for example after the process was killed. The server must `allowReconnection()`. |
| `colyseus_client_consume_seat_reservation(client, reservation)` | Join with a seat your backend reserved (see [Consuming a Seat Reservation](https://docs.colyseus.io/sdk.md#consuming-a-seat-reservation)). Takes a struct, such as an HTTP reply or a room message, or a JSON string. Returns a room handle; an invalid reservation fails through `colyseus_on_error()`. Requires SDK 0.18.5. |

### Room

| Function | Description |
| --- | --- |
| `colyseus_room_is_connected(room)` | Returns `1` if connected, `0` otherwise. |
| `colyseus_room_get_id(room)` | Get the room's unique ID. |
| `colyseus_room_get_session_id(room)` | Get your session ID in the room. |
| `colyseus_room_get_name(room)` | Get the room type name. |
| `colyseus_room_leave(room)` | Leave the room gracefully. |
| `colyseus_room_free(room)` | Free room resources (also frees callbacks). |
| `colyseus_room_get_reconnection_token(room)` | The `"roomId:token"` string for `colyseus_client_reconnect()`; empty until joined. |
| `colyseus_room_is_reconnecting(room)` | Returns `1` while an automatic reconnection is in progress. |
| `colyseus_room_set_reconnection_options(room, enabled, max_retries, min_delay_ms, max_delay_ms, min_uptime_ms, delay_ms, max_enqueued_messages)` | Tune automatic reconnection; pass `-1` to keep a value. |

### Room Events (GML helpers)

Register callbacks for room lifecycle events. These are dispatched by `colyseus_process()`.

| Function | Callback signature |
| --- | --- |
| `colyseus_on_join(room, handler)` | `handler(room)` |
| `colyseus_on_state_change(room, handler)` | `handler(room)` |
| `colyseus_on_message(room, handler)` | `handler(room, type, data)` (`data` is auto-decoded) |
| `colyseus_on_error(room, handler)` | `handler(code, message)` |
| `colyseus_on_leave(room, handler)` | `handler(code, reason)` |
| `colyseus_on_drop(room, handler)` | `handler(code, reason)`, once when the connection drops with a recoverable code and automatic reconnection starts |
| `colyseus_on_reconnect(room, handler)` | `handler()`, when the reconnection succeeds; messages sent while dropped have been flushed by then |

### Sending Messages

| Function | Description |
| --- | --- |
| `colyseus_send(room, type, data)` | Send a message. `type` is a string or a number. `data` is a struct (sent as a map of strings, numbers and booleans), or a bare string, number or boolean. |
| `colyseus_room_send(room, type, data)` | Send raw encoded bytes with a string type. |
| `colyseus_room_send_bytes(room, type, data, length)` | Send raw bytes. |
| `colyseus_room_send_int(room, type, data)` | Send raw encoded bytes with a numeric type. |

For advanced message construction:

| Function | Description |
| --- | --- |
| `colyseus_message_create_map()` | Create a message builder. Returns a message handle. |
| `colyseus_message_put_str(msg, key, value)` | Add a string field. |
| `colyseus_message_put_number(msg, key, value)` | Add a number field. |
| `colyseus_message_put_bool(msg, key, value)` | Add a boolean field (`1`/`0`). |
| `colyseus_room_send_message(room, type, msg)` | Send and free the constructed message. |
| `colyseus_message_free(msg)` | Free a message (only needed if not sent). |

### State & Schema

Schema instances arrive as GML structs: `colyseus_room_get_state(room)` returns the root state with every field (and nested ref) as a member, and the structs a callback receives are the same objects. The structs are refreshed after every patch, so dot access is current as of the last `colyseus_process()`. Any function below also accepts a struct where it says `instance`.

| Function | Description |
| --- | --- |
| `colyseus_room_get_state(room)` | The root state as a struct (`undefined` until the first state arrives). |
| `colyseus_schema_get(instance, field)` | Read one field: a string, a number (booleans read as `1`/`0`), a struct for refs, `undefined` if the field does not exist. |
| `colyseus_schema_get_field_type(instance, field)` | The field type as a number (`COLYSEUS_TYPE_*`), `-1` if the field does not exist. |
| `colyseus_map_get(instance, field, key)` | An entry of a MapSchema by key: a struct for schema entries, the value for primitive-valued maps, `undefined` when absent. |

### State Change Callbacks (GML helpers)

Create a callbacks manager to listen for state mutations. Omit the `instance` argument to listen on the root state.

| Function | Callback signature |
| --- | --- |
| `colyseus_callbacks_create(room)` | Create a callbacks manager. Returns a callbacks handle. |
| `colyseus_listen(callbacks, [instance], property, handler)` | `handler(value, previous_value)` |
| `colyseus_on_add(callbacks, [instance], property, handler)` | `handler(instance, key)` |
| `colyseus_on_remove(callbacks, [instance], property, handler)` | `handler(instance, key)` |
| `colyseus_on_change(callbacks, [instance], property, handler)` | `handler(key, value)` for any change inside a collection field |
| `colyseus_on_change(callbacks, instance, handler)` | `handler()` after any field of that instance changes |
| `colyseus_callbacks_remove_handle(callbacks, handle)` | Stop listening for a specific callback (each registration returns its handle). |
| `colyseus_callbacks_free(callbacks)` | Free callbacks (auto-freed when room is freed). |

### Event Processing

| Function | Description |
| --- | --- |
| `colyseus_process()` | **Call once per frame.** Polls the event queue and dispatches registered handlers. |

### Running the test server locally

To run the test server locally, you will need to run the following commands in your terminal:

```sh filename="Terminal"
git clone https://github.com/colyseus/sdks-test-server
cd sdks-test-server
npm install
npm start
```

> **Note:**
>
> You can see the source code for the test server [here](https://github.com/colyseus/sdks-test-server).

You should be able to see the server running at `http://localhost:2567`, and the example project will be able to connect to it.

## Debugging

### Breakpoints

If you set a breakpoint while the WebSocket connection is open, the connection closes automatically after 3 seconds due to inactivity. To prevent the WebSocket connection from dropping, use `pingInterval: 0` during development:

```ts filename="app.config.ts"
import { defineServer } from "colyseus";
import { WebSocketTransport } from "@colyseus/ws-transport";

const server = defineServer({
    // ...
    transport: new WebSocketTransport({
        pingInterval: 0,
    }),
    // ...
});
```

Make sure to have a `pingInterval` higher than `0` on production. The default `pingInterval` value is `3000`.

## Next Steps

- [Client SDK API Reference](https://docs.colyseus.io/sdk.md) - Full API documentation for all methods, events, and room operations
- [State Synchronization](https://docs.colyseus.io/state.md) - Understanding Schema definitions
- [Room API](https://docs.colyseus.io/room.md) - Server-side room implementation

---
Source: https://docs.colyseus.io/getting-started/gamemaker


# Godot Engine

> **Warning:**
>
> The GDExtension is in **beta**, and may not be stable. Please [report any issues you find](https://github.com/colyseus/native-sdk/issues/8).

> **Note:**
>
> This extension does not support **Godot Mono**. For Godot Mono (C#), install the `Colyseus` NuGet package by adding it to the `.csproj` file in your project root:
>
> ```xml
> <ItemGroup>
>     <PackageReference Include="Colyseus" Version="0.17.*" />
> </ItemGroup>
> ```
>
>     Godot automatically downloads and sets up NuGet packages the next time it builds the project. See the [Client SDK](https://docs.colyseus.io/sdk.md) documentation for the C# API reference.

We are experimenting with our shared [Colyseus Native SDK](https://github.com/colyseus/native-sdk) for cross-platform support for Colyseus across different engines. Godot is the first engine to support this. The work on Native SDK is still in progress, so expect some breaking changes as we go.

## Platforms

- Desktop (Windows, macOS, Linux)
- iOS
- Android
- Web (HTML5)

## Installation

- Download the latest Godot SDK from [GitHub Releases](https://github.com/colyseus/native-sdk/releases?q=godot+sdk&expanded=true)
- Extract the addons folder into your Godot project root
- **macOS only:** Remove the quarantine attribute by running in the project root:
  ```sh
  xattr -cr addons/colyseus
  ```
- Enable the plugin in **Project Settings** → **Plugins**

## Web Builds

When exporting your project via **Project** → **Export** → **Web (Runnable)**, make sure to enable **Extensions Support**.

![Settings](https://docs.colyseus.io/getting-started/godot-web.png)

## SDK API

Navigate to the [ Client SDK](https://docs.colyseus.io/sdk.md) for API Reference, and select the **Godot** tab.

## Quick Example / Reference

> **Note:**
>
> The state schema and messages in this example come from the room built in [Create a Server](https://docs.colyseus.io/getting-started/server.md). Start that server before you run it.

This example shows how to connect to a room, listen for state changes, send messages and leave the room.

```gdscript filename="Network.gd"
extends Node

var client: Colyseus.Client
var room: Colyseus.Room
var callbacks: Colyseus.Callbacks

func _ready():
	# Create client with endpoint
	client = Colyseus.Client.new("ws://localhost:2567")

	print("Connecting to: ", client.get_endpoint())

	# Join or create a room (options are passed as Dictionary)
	room = client.join_or_create("my_room")

	# Connect signals
	if room:
		room.joined.connect(_on_room_joined)
		room.state_changed.connect(_on_state_changed)
		room.message_received.connect(_on_message_received)
		room.error.connect(_on_room_error)
		room.left.connect(_on_room_left)

func _on_room_joined():
	print("Joined room: ", room.get_id())
	print("  Session ID: ", room.get_session_id())
	print("  Room name: ", room.get_name())

	# Get callbacks container for the room
	callbacks = Colyseus.Callbacks.of(room)

	# Listen to collection additions/removals/changes
	callbacks.on_add("players", _on_player_add)
	callbacks.on_remove("players", _on_player_remove)

	# Send a message
	room.send_message("move", {"x": 10, "y": 20})

func _on_player_add(player, key: String):
	print("+ Player joined: ", key)
	# Listen to nested schema properties
	callbacks.listen(player, "x", _on_player_x_change)
	# Listen to any property change on this player
	callbacks.on_change(player, _on_player_changed)

func _on_player_remove(player, key: String):
	print("- Player left: ", key)

func _on_players_change(key, value):
	print("Players collection changed: ", key)

func _on_player_changed():
	print("  Player instance changed")

func _on_player_x_change(current_x, previous_x):
	print("  x changed: ", previous_x, " -> ", current_x)

func _on_state_changed():
	print("Room state changed")
	var state = room.get_state()
	if state:
		print("  State: ", state)

func _on_message_received(type: Variant, data: Variant):
	print("Message received - type: ", type, " data: ", data)

func _on_room_error(code: int, message: String):
	printerr("Room error [", code, "]: ", message)

func _on_room_left(code: int, reason: String):
	print("Left room [", code, "]: ", reason)

func _exit_tree():
	if room and room.connected:
		room.leave()
```

### Polling

The SDK automatically polls for network events every frame via an internal node added to the scene tree. No manual polling is needed in most cases.

For **headless or test** scenarios where there is no scene tree, call `Colyseus.poll()` manually in your loop:

```gdscript
Colyseus.poll()
```

### State Schema Codegen

The State Schema Codegen is optional but recommended: it gives you type safety and autocomplete in your IDE.

```sh filename="Terminal"
npx schema-codegen src/rooms/schema/* --gdscript --bundle --output ../colyseus/schema/
```

> **Note:**
>
> See the full [State Schema Codegen documentation](https://docs.colyseus.io/state/callbacks.md#frontend-schema-generation) for more options and details.

---
Source: https://docs.colyseus.io/getting-started/godot


# Haxe

You're encouraged to use this SDK along with any Haxe Game Engine, such as: [OpenFL](https://www.openfl.org/), [Kha](http://kha.tech/), [HaxeFlixel](http://haxeflixel.com/), [Heaps](https://heaps.io/), [HaxePunk](http://haxepunk.com/), etc.

## Install package

Install `colyseus` from haxelib:

```sh filename="Terminal"
haxelib install colyseus
```

## SDK Example Project

The [colyseus-hx](https://github.com/colyseus/colyseus-hx) repository contains an [example project](https://github.com/colyseus/colyseus-hx/blob/master/example/openfl) that can be compiled to `html5`, `neko`, `cpp`, `ios`, etc.

### Compiling the example project to `html5`

```sh filename="Terminal"
git clone https://github.com/colyseus/colyseus-hx.git
cd colyseus-hx/example/openfl

# Install haxelib dependencies
haxelib install openfl
haxelib install lime
haxelib install tink_http
haxelib install tink_await
haxelib install swf
haxelib install colyseus-websocket

# Compile the project
haxelib run lime test project.xml html5
```

### Running the test server locally

To run the test server locally, you will need to run the following commands in your terminal:

```sh filename="Terminal"
git clone https://github.com/colyseus/sdks-test-server
cd sdks-test-server
npm install
npm start
```

> **Note:**
>
> You can see the source code for the test server [here](https://github.com/colyseus/sdks-test-server).

You should be able to see the server running at `http://localhost:2567`, and the example project will be able to connect to it.

## Quick Example

> **Note:**
>
> The state schema and messages in this example come from the room built in [Create a Server](https://docs.colyseus.io/getting-started/server.md). Start that server before you run it.

This example shows how to connect to a room, listen for state changes, and send messages.

```haxe
import io.colyseus.Client;
import io.colyseus.Room;
import io.colyseus.serializer.schema.Callbacks;

class NetworkManager {
    var client:Client;
    var room:Room<Dynamic>;

    public function new() {
        client = new Client("ws://localhost:2567");

        client.joinOrCreate("my_room", [], Dynamic, function(err, room) {
            if (err != null) {
                trace("JOIN ERROR: " + err);
                return;
            }

            this.room = room;
            trace("Joined room: " + room.id);

            // Get state callbacks handler
            var callbacks = Callbacks.get(room);

            // Listen for players being added
            callbacks.onAdd("players", function(player, sessionId) {
                trace("Player joined: " + sessionId);

                callbacks.listen(player, "x", function(currentX, previousX) {
                    trace("Player " + sessionId + " x: " + currentX);
                });
            });

            // Listen for players being removed
            callbacks.onRemove("players", function(player, sessionId) {
                trace("Player left: " + sessionId);
            });

            // Send a message to the server
            room.send("move", {x: 10, y: 20});

            // Listen for messages from the server
            room.onMessage("chat", function(message) {
                trace("Chat: " + message);
            });

            room.onLeave = function(code) {
                trace("Left room: " + code);
            };
        });
    }
}
```

## SDK API

Navigate to the [ Client SDK](https://docs.colyseus.io/sdk.md) for API Reference, and select the **Haxe** tab.

### State Schema Codegen

For compiled languages like Haxe, you need to generate client-side schema classes that match your server's state structure. Run the following command from your server directory:

```sh filename="Terminal"
npx schema-codegen src/rooms/schema/* --haxe --output ../src/schema/
```

> **Note:**
>
> See the full [State Schema Codegen documentation](https://docs.colyseus.io/state/callbacks.md#frontend-schema-generation) for more options and details.

### Reactive Schema Tools

The SDK ships with Haxe macros that turn generated schema classes into reactive [`tink.state`](https://github.com/haxetink/tink_state) observables, no manual listeners required.

**Dependencies**: add to your `.hxml`:

```
-lib tink_state
-lib tink_macro
-lib tink_json   # optional, for serialised string fields
```

**`ObservableSchemaMacro`** generates a typed `State<T>` field for every property of a schema class:

```haxe
@:build(io.colyseus.tools.ObservableSchemaMacro.build(MyRoomState))
class MyRoomObservable {
    private static var link:CallbackLink;
    public function listen(room:Room<MyRoomState>)
        link = SchemaListenMacro.listenRef(Callbacks.get(room), room.state);
    public function dispose() link.cancel();
}
```

**`SchemaListenMacro`** wires schema `listen` / `onAdd` / `onRemove` callbacks to the observable fields generated above. It handles primitives, nested schemas, `ArraySchema`, and `MapSchema` recursively.

**Using observables** after calling `observables.listen(room)`:

```haxe
// React to any change across all players
Observable.autorun(() -> for (player in observables.players) {
    trace('x=${player.x.value} y=${player.y.value}');
    trace('items: ${player.items.toArray()}');
});

// Bind to a single field
observables.currentTurn.observe().bind(x -> trace('Turn: $x'));
```

> **Note:**
>
> Enable `-D debug_macro` to write the generated code to `GameSchemaDebug.hx` / `ListenDebug.hx` for inspection. See the full example in [`colyseus-hx/example/tools`](https://github.com/colyseus/colyseus-hx/tree/master/example/tools).

## `ios` target caveats

You may need to manually apply this patch in order to compile for iOS: [HaxeFoundation/hxcpp@5f63d23](https://github.com/HaxeFoundation/hxcpp/commit/5f63d23768988ba2a4d4488843afab70d279a593)

> More info:
> http://community.openfl.org/t/solved-system-not-available-on-ios-with-xcode-9-0/9683?source_topic_id=10046

## Next Steps

- [Client SDK API Reference](https://docs.colyseus.io/sdk.md) - Full API documentation (select the **Haxe** tab)
- [State Synchronization](https://docs.colyseus.io/state.md) - Understanding Schema definitions
- [Room API](https://docs.colyseus.io/room.md) - Server-side room implementation

---
Source: https://docs.colyseus.io/getting-started/haxe


# MonoGame SDK

## Install package

Add the `Colyseus.MonoGame` NuGet package to your project:

```sh filename="Terminal"
dotnet add package Colyseus.MonoGame
```

---

## Quick Example

> **Note:**
>
> The state schema and messages in this example come from the room built in [Create a Server](https://docs.colyseus.io/getting-started/server.md). Start that server before you run it.

This example shows how to connect to a room, listen for state changes via Callbacks, and send messages.

```csharp filename="Game1.cs"
using Microsoft.Xna.Framework;
using Colyseus;
using Colyseus.Schema;

public class Game1 : Game
{
    Client client;
    Room<MyRoomState> room;

    protected override async void LoadContent()
    {
        client = new Client("ws://localhost:2567");

        room = await client.JoinOrCreate<MyRoomState>("my_room");
        System.Diagnostics.Debug.WriteLine("Joined room: " + room.Id);

        // Get state callbacks handler
        var callbacks = Callbacks.Get(room);

        // Listen for players being added
        callbacks.OnAdd(state => state.players, (sessionId, player) => {
            System.Diagnostics.Debug.WriteLine($"Player joined: {sessionId}");

            callbacks.Listen(player, p => p.x, (currentX, previousX) => {
                System.Diagnostics.Debug.WriteLine($"Player {sessionId} x: {currentX}");
            });
        });

        // Listen for players being removed
        callbacks.OnRemove(state => state.players, (sessionId, player) => {
            System.Diagnostics.Debug.WriteLine($"Player left: {sessionId}");
        });

        // Send a message to the server
        room.Send("move", new { x = 10f, y = 20f });

        // Listen for messages from the server
        room.OnMessage<string>("chat", (message) => {
            System.Diagnostics.Debug.WriteLine("Chat: " + message);
        });
    }

    protected override void OnExiting(object sender, EventArgs args)
    {
        if (room != null) room.Leave();
        base.OnExiting(sender, args);
    }
}
```

## Optional: ColyseusGameComponent

The SDK automatically dispatches WebSocket messages internally via an async Task loop, so no extra setup is needed. However, you can optionally register the `ColyseusGameComponent` to synchronize message dispatching with MonoGame's `Update()` cycle:

```csharp filename="Game1.cs"
using Colyseus.MonoGame;

protected override void Initialize()
{
    Components.Add(new ColyseusGameComponent(this));
    base.Initialize();
}
```

## SDK API

Navigate to the [ Client SDK](https://docs.colyseus.io/sdk.md) for API Reference, and select the **C# (Unity)** tab.

### State Schema Codegen

For compiled languages like C#, you need to generate client-side schema classes that match your server's state structure. Run the following command from your server directory:

```sh filename="Terminal"
npx schema-codegen src/rooms/schema/* --csharp --output ../MyGame/States/
```

> **Note:**
>
> See the full [State Schema Codegen documentation](https://docs.colyseus.io/state/callbacks.md#frontend-schema-generation) for more options and details.

### DynamicSchema (Skip Code Generation)

If you want to skip the code generation step entirely, you can use `DynamicSchema` instead of generated schema classes. `DynamicSchema` builds its type metadata at runtime from the server handshake, so no generated files are needed.

```csharp filename="Game1.cs"
using Microsoft.Xna.Framework;
using Colyseus;
using Colyseus.Schema;

public class Game1 : Game
{
    Client client;
    Room<DynamicSchema> room;

    protected override async void LoadContent()
    {
        client = new Client("ws://localhost:2567");

        room = await client.JoinOrCreate<DynamicSchema>("my_room");
        System.Diagnostics.Debug.WriteLine("Joined room: " + room.Id);

        // Access state fields dynamically
        var players = room.State.Get<MapSchema<DynamicSchema>>("players");
        var self = players[room.SessionId];
        var hp = self.Get<int>("hp");

        // Callbacks use string-based property names instead of expressions
        var callbacks = Callbacks.Get(room);

        callbacks.Listen<string>("currentTurn", (currentValue, previousValue) => {
            System.Diagnostics.Debug.WriteLine($"Turn changed: {previousValue} -> {currentValue}");
        });

        callbacks.OnAdd<DynamicSchema>("players", (sessionId, player) => {
            System.Diagnostics.Debug.WriteLine($"Player joined: {sessionId}");

            // Access nested collections
            var items = player.Get<ArraySchema<DynamicSchema>>("items");
        });

        callbacks.OnRemove<DynamicSchema>("players", (sessionId, player) => {
            System.Diagnostics.Debug.WriteLine($"Player left: {sessionId}");
        });
    }

    protected override void OnExiting(object sender, EventArgs args)
    {
        if (room != null) room.Leave();
        base.OnExiting(sender, args);
    }
}
```

> **Warning:**
>
> `DynamicSchema` trades compile-time type safety for convenience. You won't get IDE autocomplete on state fields, and type errors will only surface at runtime. For production projects, [Schema Codegen](#state-schema-codegen) is recommended.

### Message Types Codegen

The same `schema-codegen` command also generates C# classes for any TypeScript interface containing `"Message"` in its name. These classes let you use strongly-typed message objects on the frontend.

For example, given the following server-side code:

```ts filename="src/rooms/MyRoom.ts"
interface MoveMessage {
  x: number;
  y: number;
}

// ...

messages = {
  move: (client: Client, message: MoveMessage) => {
    // handle move
  }
}
```

Running the codegen command will automatically generate a matching C# class:

```csharp filename="Generated C# output"
public class MoveMessage {
    public float x;
    public float y;
}
```

You can then use these classes when sending and receiving messages on the client:

```csharp filename="Sending a message to the server"
room.Send("move", new MoveMessage() { x = 1.0f, y = 2.0f });
```

The same applies to messages sent from the server to the client. For example, given a server-side interface:

```ts filename="src/rooms/MyRoom.ts"
interface EventMessage {
  type: string;
  data: string;
}

// ...

onJoin(client: Client) {
  client.send("event", { type: "welcome", data: "Hello!" } as EventMessage);
}
```

You can listen for it on the client with the generated type:

```csharp filename="Receiving a message from the server"
room.OnMessage<EventMessage>("event", (message) => {
    System.Diagnostics.Debug.WriteLine(message.type);
    System.Diagnostics.Debug.WriteLine(message.data);
});
```

## Debugging

### Breakpoints

If you set a breakpoint in your application while the WebSocket connection is open, it closes after 3 seconds of inactivity. To prevent the WebSocket connection from dropping, use `pingInterval: 0` during development:

```ts filename="app.config.ts"
import { defineServer } from "colyseus";
import { WebSocketTransport } from "@colyseus/ws-transport";

const server = defineServer({
    // ...
    transport: new WebSocketTransport({
        pingInterval: 0, // <--- HERE
    }),
    // ...
});
```

Make sure to have a `pingInterval` higher than `0` on production. The default `pingInterval` value is `3000`.

---
Source: https://docs.colyseus.io/getting-started/monogame


# Native SDK (C)

> **Warning:**
>
> The Native SDK is in **beta**, and may not be stable. Please [report any issues you find](https://github.com/colyseus/native-sdk/issues).

The [Colyseus Native SDK](https://github.com/colyseus/native-sdk) provides a pure C API for integrating Colyseus into any engine or framework. This SDK is the shared foundation behind the Godot, GameMaker, Defold, and [Flutter](https://docs.colyseus.io/getting-started/flutter.md) SDKs. You can also use it directly for custom engines or platforms such as Raylib, SDL, or embedded systems.

See the [Raylib example project](https://github.com/colyseus/native-sdk/tree/main/platforms/raylib) for a complete working sample.

## Platforms

- Desktop (Windows, macOS, Linux)
- iOS
- Android
- Web (Emscripten / WASM)

## Installation

The Native SDK is built with Zig and exposes a C-compatible API via static or shared libraries.

1. Download the latest release from [GitHub Releases](https://github.com/colyseus/native-sdk/releases?q=%22Colyseus+Native+SDK+-+Static+Library%22&expanded=true)
2. Add the `include/` directory to your compiler's include path
3. Link against the `colyseus` library

### Building from source

Requires [Zig 0.15.2](https://ziglang.org/download/).

```sh
git clone https://github.com/colyseus/native-sdk.git
cd native-sdk
zig build
```

The build output will be in `zig-out/lib/` (library) and `zig-out/include/` (headers).

### Headers

```c
#include <colyseus/client.h>       // Client creation and matchmaking
#include <colyseus/schema.h>       // Schema serializer
#include <colyseus/schema/callbacks.h>  // State change callbacks
#include <colyseus/schema/collections.h> // ArraySchema / MapSchema
#include <colyseus/messages.h>     // Message builder and reader
```

## State Schema Codegen

Generate C structs from your server-side schema definitions:

```sh filename="Terminal"
npx schema-codegen src/rooms/schema/* --c --output client/schema/
```

This produces a header file with typed structs, field metadata, and vtables for each schema class. For example, a `Player` schema generates:

```c filename="schema/player.h"
typedef struct {
    colyseus_schema_t __base;   // Must be the first field
    double x;
    double y;
    bool isBot;
    bool disconnected;
} player_t;

static const colyseus_field_t player_fields[] = {
    {0, "x",            COLYSEUS_FIELD_NUMBER,  "number",  offsetof(player_t, x),            NULL, NULL},
    {1, "y",            COLYSEUS_FIELD_NUMBER,  "number",  offsetof(player_t, y),            NULL, NULL},
    {2, "isBot",        COLYSEUS_FIELD_BOOLEAN, "boolean", offsetof(player_t, isBot),        NULL, NULL},
    {3, "disconnected", COLYSEUS_FIELD_BOOLEAN, "boolean", offsetof(player_t, disconnected), NULL, NULL},
};

static const colyseus_schema_vtable_t player_vtable = {
    "Player",
    sizeof(player_t),
    (colyseus_schema_t* (*)(void))player_create,
    player_destroy,
    player_fields,
    4
};
```

The root state vtable is passed to `colyseus_room_set_state_type()` to enable automatic deserialization.

> **Note:**
>
> See the full [State Schema Codegen documentation](https://docs.colyseus.io/state/callbacks.md#frontend-schema-generation) for more options and details.

## Auto Schemas (Without Codegen)

**Show how to use schemas without running the codegen step**

If you do **not** call `colyseus_room_set_state_type()`, the SDK automatically builds schema definitions at runtime from the server's reflection data sent during the handshake. This mode is useful for:

- Prototyping without a build step
- Supporting multiple server versions with different schemas
- Scripting languages or runtimes where codegen is impractical

In this mode, state objects are returned as `colyseus_dynamic_schema_t*` instead of typed structs, and fields are accessed by name through a hash table:

```c
#include <colyseus/schema/dynamic_schema.h>

// Do NOT call colyseus_room_set_state_type() - the SDK will auto-detect.

static void on_join(void* userdata) {
    // State is a dynamic schema when no vtable is provided
    colyseus_dynamic_schema_t* state =
        (colyseus_dynamic_schema_t*)colyseus_room_get_state(room);

    // Access fields by name
    colyseus_dynamic_value_t* turn =
        colyseus_dynamic_schema_get_by_name(state, "currentTurn");

    if (turn && turn->type == COLYSEUS_FIELD_STRING) {
        printf("Current turn: %s\n", turn->data.str);
    }

    // Access nested map
    colyseus_dynamic_value_t* players =
        colyseus_dynamic_schema_get_by_name(state, "players");

    if (players && players->type == COLYSEUS_FIELD_MAP) {
        colyseus_map_schema_foreach(players->data.map, on_player_entry, NULL);
    }
}
```

### Reading dynamic values

Each `colyseus_dynamic_value_t` is a tagged union. Check `value->type` and read the matching field from `value->data`:

```c
switch (value->type) {
    case COLYSEUS_FIELD_STRING:  printf("%s\n", value->data.str); break;
    case COLYSEUS_FIELD_NUMBER:  printf("%f\n", value->data.num); break;
    case COLYSEUS_FIELD_BOOLEAN: printf("%d\n", value->data.boolean); break;
    case COLYSEUS_FIELD_INT32:   printf("%d\n", value->data.i32); break;
    case COLYSEUS_FIELD_REF:     // Nested schema
        handle_dynamic((colyseus_dynamic_schema_t*)value->data.ref); break;
    case COLYSEUS_FIELD_ARRAY:   // colyseus_array_schema_t*
    case COLYSEUS_FIELD_MAP:     // colyseus_map_schema_t*
    default: break;
}
```

### Iterating fields

To walk every field on a dynamic schema (useful for debugging or generic UIs):

```c
static void print_field(int index, const char* name,
                        colyseus_dynamic_value_t* value, void* userdata) {
    printf("[%d] %s (type=%d)\n", index, name, value->type);
}

colyseus_dynamic_schema_foreach(state, print_field, NULL);
```

### Map and array entries

Items inside dynamic `MapSchema`/`ArraySchema` collections are themselves `colyseus_dynamic_schema_t*` (for object types) or raw primitive values:

```c
static void on_player_entry(const char* key, void* value, void* userdata) {
    colyseus_dynamic_schema_t* player = (colyseus_dynamic_schema_t*)value;

    colyseus_dynamic_value_t* x = colyseus_dynamic_schema_get_by_name(player, "x");
    colyseus_dynamic_value_t* y = colyseus_dynamic_schema_get_by_name(player, "y");

    printf("Player %s at (%.1f, %.1f)\n", key, x->data.num, y->data.num);
}
```

### Callbacks with auto schemas

The standard callbacks API works with dynamic schemas. Pass the dynamic schema instance the same way you would a generated struct:

```c
colyseus_callbacks_t* callbacks = colyseus_callbacks_create(room->serializer->decoder);

// Listen on the dynamic state by property name
colyseus_callbacks_on_add(callbacks, state, "players",
    on_player_add, NULL, true);
```

> **Warning:**
>
> Auto schemas trade compile-time type safety and direct struct-offset access for runtime flexibility. For performance-critical paths, prefer codegen.

## Quick Example

> **Note:**
>
> The state schema and messages in this example come from the room built in [Create a Server](https://docs.colyseus.io/getting-started/server.md). Start that server before you run it.

This example shows how to connect to a server, join a room, listen for state changes, send messages, and handle cleanup.

```c filename="main.c"
#include <stdio.h>
#include <string.h>
#include <colyseus/client.h>
#include <colyseus/schema.h>
#include <colyseus/schema/callbacks.h>
#include <colyseus/schema/collections.h>
#include <colyseus/messages.h>
#include "my_room_state.h"  // Generated schema header

static colyseus_client_t* client = NULL;
static colyseus_room_t* room = NULL;
static colyseus_callbacks_t* callbacks = NULL;

// --- Room event handlers ---

static void on_join(void* userdata) {
    printf("Joined room! Session: %s\n", colyseus_room_get_session_id(room));

    // Access the decoded state
    my_room_state_t* state = (my_room_state_t*)colyseus_room_get_state(room);

    // Create callbacks manager for state change listening
    callbacks = colyseus_callbacks_create(room->serializer->decoder);

    // Listen for players being added to the map
    colyseus_callbacks_on_add(callbacks, state, "players",
        on_player_add, NULL, true);

    // Listen for players being removed
    colyseus_callbacks_on_remove(callbacks, state, "players",
        on_player_remove, NULL);
}

static void on_state_change(void* userdata) {
    // Called every time the room state is updated
}

static void on_error(int code, const char* message, void* userdata) {
    printf("Room error (%d): %s\n", code, message);
}

static void on_leave(int code, const char* reason, void* userdata) {
    printf("Left room (%d): %s\n", code, reason ? reason : "unknown");
}

// --- State change callbacks ---

static void on_player_add(void* value, void* key, void* userdata) {
    player_t* player = (player_t*)value;
    const char* session_id = (const char*)key;
    printf("Player joined: %s (x=%.1f, y=%.1f)\n",
        session_id, player->x, player->y);

    // Listen for changes on individual player properties
    colyseus_callbacks_listen(callbacks, player, "x",
        on_player_x_change, NULL, false);
}

static void on_player_remove(void* value, void* key, void* userdata) {
    const char* session_id = (const char*)key;
    printf("Player left: %s\n", session_id);
}

static void on_player_x_change(void* current, void* previous, void* userdata) {
    double x = *(double*)current;
    printf("Player x changed to: %.1f\n", x);
}

// --- Matchmaking callback ---

static void on_room_success(colyseus_room_t* joined_room, void* userdata) {
    room = joined_room;

    // Set state schema type (must be done before event handlers)
    colyseus_room_set_state_type(room, &my_room_state_vtable);

    // Register room event handlers
    colyseus_room_on_join(room, on_join, NULL);
    colyseus_room_on_state_change(room, on_state_change, NULL);
    colyseus_room_on_error(room, on_error, NULL);
    colyseus_room_on_leave(room, on_leave, NULL);
}

static void on_matchmaking_error(int code, const char* message, void* userdata) {
    printf("Failed to join: %s\n", message);
}

// --- Main ---

int main(void) {
    // Create settings
    colyseus_settings_t* settings = colyseus_settings_create();
    colyseus_settings_set_address(settings, "localhost");
    colyseus_settings_set_port(settings, "2567");

    // Create client
    client = colyseus_client_create(settings);

    // Join or create a room
    colyseus_client_join_or_create(
        client, "my_room", "{}",
        on_room_success,
        on_matchmaking_error,
        NULL
    );

    // Main loop (integrate with your engine's loop)
    while (running) {
        // Your engine's frame update here...
    }

    // Cleanup
    if (callbacks) colyseus_callbacks_free(callbacks);
    if (room) {
        colyseus_room_leave(room, true);
        colyseus_room_free(room);
    }
    if (client) colyseus_client_free(client);
    colyseus_settings_free(settings);

    return 0;
}
```

## Sending Messages

Build messages using the message builder API. The `colyseus_message_map_put()` macro uses C11 `_Generic` to auto-detect value types.

```c
// Create a map message
colyseus_message_t* msg = colyseus_message_map_create();
colyseus_message_map_put(msg, "x", 100.0);
colyseus_message_map_put(msg, "y", 200.0);
colyseus_room_send(room, "move", msg);
colyseus_message_free(msg);
```

You can also use explicit typed setters:

```c
colyseus_message_map_put_str(msg, "name", "Alice");
colyseus_message_map_put_int(msg, "score", 42);
colyseus_message_map_put_float(msg, "speed", 3.5);
colyseus_message_map_put_bool(msg, "ready", true);
```

### Array messages

```c
colyseus_message_t* arr = colyseus_message_array_create();
colyseus_message_array_push(arr, 10);
colyseus_message_array_push(arr, 20);
colyseus_room_send(room, "path", arr);
colyseus_message_free(arr);
```

### Nested messages

```c
colyseus_message_t* inner = colyseus_message_map_create();
colyseus_message_map_put(inner, "name", "sword");

colyseus_message_t* outer = colyseus_message_map_create();
colyseus_message_map_put_msg(outer, "item", inner);
colyseus_room_send(room, "equip", outer);
colyseus_message_free(outer);
```

## Receiving Messages

Register message handlers on the room, then read values from the `colyseus_message_reader_t`:

```c
static void on_chat_message(colyseus_message_reader_t* reader, void* userdata) {
    const char* text = NULL;
    size_t len = 0;

    if (colyseus_message_reader_map_get_str(reader, "text", &text, &len)) {
        printf("Chat: %.*s\n", (int)len, text);
    }

    int64_t timestamp;
    if (colyseus_message_reader_map_get_int(reader, "timestamp", &timestamp)) {
        printf("At: %lld\n", timestamp);
    }
}

// Register the handler
colyseus_room_on_message(room, "chat", on_chat_message, NULL);
```

## State Callbacks

After joining a room and receiving state, create a callbacks manager to listen for changes:

```c
// Create callbacks manager from the room's decoder
colyseus_callbacks_t* callbacks = colyseus_callbacks_create(room->serializer->decoder);

my_room_state_t* state = (my_room_state_t*)colyseus_room_get_state(room);

// Listen for property changes on the root state
// The last argument (true) triggers the callback immediately with the current value
colyseus_callbacks_listen(callbacks, state, "currentTurn",
    on_turn_change, NULL, true);

// Listen for items added to a map
colyseus_callbacks_on_add(callbacks, state, "players",
    on_player_add, NULL, true);

// Listen for items removed from a map
colyseus_callbacks_on_remove(callbacks, state, "players",
    on_player_remove, NULL);

// Listen for any change on a specific schema instance
colyseus_callbacks_on_change_instance(callbacks, some_player,
    on_player_changed, NULL);
```

### Removing callbacks

Each registration returns a `colyseus_callback_handle_t` that can be used to unsubscribe:

```c
colyseus_callback_handle_t handle = colyseus_callbacks_on_add(
    callbacks, state, "players", on_player_add, NULL, true);

// Later, remove the callback
colyseus_callbacks_remove(callbacks, handle);
```

## Iterating Collections

Access map and array data directly from the state:

```c
my_room_state_t* state = (my_room_state_t*)colyseus_room_get_state(room);

// Iterate a MapSchema
void print_player(const char* key, void* value, void* userdata) {
    player_t* p = (player_t*)value;
    printf("Player %s at (%.1f, %.1f)\n", key, p->x, p->y);
}
colyseus_map_schema_foreach(state->players, print_player, NULL);

// Get a specific entry by key
player_t* p = (player_t*)colyseus_map_schema_get(state->players, session_id);

// Check if a key exists
if (colyseus_map_schema_contains(state->players, session_id)) { ... }
```

## Settings

```c
colyseus_settings_t* settings = colyseus_settings_create();

colyseus_settings_set_address(settings, "example.com");
colyseus_settings_set_port(settings, "443");
colyseus_settings_set_secure(settings, true);    // Use WSS

// Custom headers
colyseus_settings_add_header(settings, "Authorization", "Bearer token123");

colyseus_client_t* client = colyseus_client_create(settings);
```

## HTTP & Auth

The client exposes HTTP and Auth APIs for REST calls and authentication:

```c
// HTTP requests
colyseus_http_t* http = colyseus_client_get_http(client);
colyseus_http_set_auth_token(http, "my-token");
colyseus_http_get(http, "/profile", on_http_success, on_http_error, NULL);
colyseus_http_post(http, "/action", "{\"key\":\"value\"}", on_http_success, on_http_error, NULL);

// Authentication
colyseus_auth_t* auth = colyseus_client_get_auth(client);
colyseus_auth_signin_anonymous(auth, "{}", on_auth_success, on_auth_error, NULL);
colyseus_auth_signin_email_password(auth, "user@example.com", "password",
    on_auth_success, on_auth_error, NULL);
```

## Memory Management

The SDK follows a consistent `create`/`free` pattern. Every resource you create must be freed:

```c
// Always free in reverse order of creation
colyseus_callbacks_free(callbacks);
colyseus_room_leave(room, true);
colyseus_room_free(room);
colyseus_client_free(client);
colyseus_settings_free(settings);
```

## Reconnection

Use the reconnection token to resume a session after a disconnect:

```c
// Save the reconnection token before disconnect
const char* token = colyseus_room_get_reconnection_token(room);

// Later, reconnect
colyseus_client_reconnect(client, token, on_room_success, on_error, NULL);
```

## Seat Reservations

When your backend reserves the seat itself (see [Consuming a Seat Reservation](https://docs.colyseus.io/sdk.md#consuming-a-seat-reservation)), join with that reservation instead of a room name. Pass the JSON the server returned:

```c
static void on_reservation(const colyseus_http_response_t* response, void* userdata) {
    colyseus_client_consume_seat_reservation_json(client, response->body,
        on_room_success, on_matchmaking_error, NULL);
}

colyseus_http_post(http, "/find_match", "{}", on_reservation, on_http_error, NULL);
```

`colyseus_client_consume_seat_reservation()` takes a `colyseus_seat_reservation_t` instead, for a reservation you assembled yourself. Both functions copy the reservation. They report a missing `name`, `roomId`, `processId` or `sessionId` through the error callback.

---
Source: https://docs.colyseus.io/getting-started/native-sdk


# React (JavaScript/TypeScript SDK)

You can use the `@colyseus/sdk` directly in your React applications. We also provide a separate package, `@colyseus/react`, with custom hooks for room connections and state subscriptions, designed for React's rendering model.

> **Note:**
>
> See an example project using `@colyseus/react` and React Three Fiber: [r3f-lobby-car-prototype](https://github.com/endel/r3f-lobby-car-prototype)

## Installation

```bash
npm install @colyseus/react
```

### Hooks

#### `useRoom(callback, deps?)`

Manages the lifecycle of a Colyseus room connection. Handles connecting, disconnecting on unmount, and reconnecting when dependencies change. Works correctly with React StrictMode.

```tsx
import { Client } from "@colyseus/sdk";
import { useRoom } from "@colyseus/react";

const client = new Client("ws://localhost:2567");

function Game() {
  const { room, error, isConnecting } = useRoom(
    () => client.joinOrCreate("game_room"),
  );

  if (isConnecting) return <p>Connecting...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return <GameView room={room} />;
}
```

The first argument is a callback that returns a `Promise<Room>`. Any Colyseus matchmaking method works (`joinOrCreate`, `join`, `create`, `joinById`, `consumeSeatReservation`).

**Reconnecting on dependency changes:**

```tsx
const { room } = useRoom(
  () => client.joinOrCreate("game_room", { level }),
  [level],
);
```

When `level` changes the previous room is left and a new connection is established.

**Conditional connection:**

Pass a falsy value to skip connecting until a condition is met:

```tsx
const { room } = useRoom(
  isReady ? () => client.joinOrCreate("game_room") : null,
  [isReady],
);
```

#### `useRoomState(room, selector?)`

Subscribes to Colyseus room state changes and returns immutable plain-object snapshots. Unchanged portions of the state tree keep referential equality between renders, so React components only re-render when the data they use actually changes.

```tsx
import { useRoom, useRoomState } from "@colyseus/react";

function Game() {
  const { room } = useRoom(() => client.joinOrCreate("game_room"));
  const state = useRoomState(room);

  if (!state) return <p>Waiting for state...</p>;

  return <p>Players: {state.players.size}</p>;
}
```

**Using a selector** to subscribe to a subset of the state:

```tsx
const players = useRoomState(room, (state) => state.players);
```

Only components that read `players` will re-render when the players map changes.

#### `useLobbyRoom(callback, deps?)`

> **Note:**
>
> This hook is designed to connect to a Colyseus [Lobby Room](https://docs.colyseus.io/matchmaker/lobby.md) and manage the list of available rooms. If you're connecting to a regular game room, use `useRoom()` instead.

Connects to a [Lobby Room](https://docs.colyseus.io/matchmaker/lobby.md) and provides a live-updating list of available rooms. The list is automatically maintained as rooms are created, updated, and removed.

```tsx
import { Client } from "@colyseus/sdk";
import { useLobbyRoom } from "@colyseus/react";

const client = new Client("ws://localhost:2567");

function Lobby() {
  const { rooms, error, isConnecting } = useLobbyRoom(
    () => client.joinOrCreate("lobby"),
  );

  if (isConnecting) return <p>Connecting...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <ul>
      {rooms.map((room) => (
        <li key={room.roomId}>
          {room.name}: {room.clients}/{room.maxClients} players
        </li>
      ))}
    </ul>
  );
}
```

**Return value:**

| Field | Type | Description |
|---|---|---|
| `rooms` | `RoomAvailable<Metadata>[]` | Live list of available rooms |
| `room` | `Room \| undefined` | The underlying lobby room connection |
| `error` | `Error \| undefined` | Connection error, if any |
| `isConnecting` | `boolean` | `true` while connecting to the lobby |

#### `useQueueRoom(connect, consume, deps?)`

> **Note:**
>
> This hook is designed to manage the full lifecycle of a [Queue Room](https://docs.colyseus.io/matchmaker/queue.md). If you're connecting to a regular game room, use `useRoom()` instead.

Manages the full lifecycle of a [Queue Room](https://docs.colyseus.io/matchmaker/queue.md): connecting to the queue room, tracking group size, and receiving a seat reservation. The hook then confirms and consumes the seat to join the match room. Cleans up both rooms on unmount.

```tsx
import { Client } from "@colyseus/sdk";
import { useQueueRoom } from "@colyseus/react";

const client = new Client("ws://localhost:2567");

function Matchmaking() {
  const { room, clients, isWaiting, error } = useQueueRoom(
    () => client.joinOrCreate("queue", { rank: 1200 }),
    (reservation) => client.consumeSeatReservation(reservation),
  );

  if (error) return <p>Error: {error.message}</p>;
  if (room) return <GameScreen room={room} />;
  if (isWaiting) return <p>Waiting for match... {clients} players in group</p>;
  return <p>Connecting...</p>;
}
```

The first argument connects to the queue room. The second argument is called with the `SeatReservation` once a match is found. Use `client.consumeSeatReservation()` to join the match room.

**Return value:**

| Field | Type | Description |
|---|---|---|
| `room` | `Room \| undefined` | The match room, once the seat has been consumed |
| `queue` | `Room \| undefined` | The queue room while waiting (undefined after match is joined) |
| `clients` | `number` | Number of clients in the current matchmaking group |
| `seat` | `SeatReservation \| undefined` | The seat reservation, once received |
| `error` | `Error \| undefined` | Connection or matchmaking error |
| `isWaiting` | `boolean` | `true` while connected to the queue and waiting for a match |

### Netcode Hooks (Colyseus 0.18+)

React bindings for the `@colyseus/sdk` Predict tools: client prediction, reconciliation and remote smoothing. See [Client Prediction & Reconciliation](https://docs.colyseus.io/netcode/client-prediction.md) for the underlying concepts.

> **Warning:**
>
> **The one rule:** structure renders through snapshots, motion renders through predict reads. `useRoomState` re-renders at patch rate with **raw synced values**, so rendering positions from it gives you jittery patch-rate motion. Predicted/smoothed values change every frame and must stay out of the React render cycle. Read them with `predict.value(instance, field)` inside your frame loop (R3F `useFrame`, or the `usePredictLoop` callback) and write into refs.

Every hook below exists in two forms: standalone, taking the `room` as its first argument (as documented here), and bound (returned by [`createRoomContext()`](#createroomcontext), no room argument needed). Pass Predict options once via the context:

```tsx
const {
  RoomProvider, useRoom, useRoomState,
  usePredict, useInput, usePredictLoop, useReconciler,
  useAttachAll, useEventChannel, useEntityInstance, useSessionEntity,
} = createRoomContext({ predict: { mode: "lerp", delay: 100 } });
```

#### `usePredict(room, options?)`

Returns the room's shared `Predict` instance. `Predict.get()` constructs a fresh instance per call, so the hook memoizes one per room, reference-counts consumers, and disposes the instance when the last consumer unmounts. Works correctly with React StrictMode.

```tsx
const predict = usePredict(room);

useFrame(() => {
  meshRef.current.position.x = predict.value(entity, "x");
});
```

#### `useInput(room, options?)`

Returns the room's `InputHandle` (`room.input()`: idempotent, stable per room). Stage fields on `input.data`, then `input.send()` once per fixed step inside the `usePredictLoop` callback.

#### `usePredictLoop(room, onSteps, options?)`

Owns the per-frame driver: calls `predict.tick(now)` once per frame and hands you the number of fixed steps due. Stage + send exactly that many inputs inside the callback ("send before you read"):

```tsx
const input = useInput(room);
const jump = useInputBuffer();

usePredictLoop(room, (steps) => {
  for (let i = 0; i < steps; i++) {
    input.data.moveX = readAxis();     // held state: sample live
    input.data.jump = jump.consume();  // tap: true on at most one step
    input.send();
  }
});
```

By default it runs its own `requestAnimationFrame` loop. With `{ external: true }` it returns a `drive(now?)` function to call from a frame loop you already have:

```tsx
// In React Three Fiber, drive at an early priority so ticks precede reads:
const drive = usePredictLoop(room, onSteps, { external: true });
useFrame(() => drive(), -1);
```

#### `useReconciler(room, select, options)`

Active prediction for the entity you control. This hook is `predict.reconciler()` with the lifecycle handled. The hook waits for the entity to spawn (`select: (state, room) => instance`) and recreates the controller if the server replaces the instance. On unmount, it disposes the controller. `options.input` defaults to the room's input handle.

```tsx
const me = useReconciler(
  room,
  (state, room) => state.players.get(room.sessionId),
  { step: (ctx, p, cmd) => applyInput(p, cmd, ctx.dt), smoothMs: 65, snap: 5 },
);
```

#### `useAttachAll(room, key, config, deps?)`

Passive smoothing for a root-state collection: `predict.attachAll()` as an effect, detached on unmount. Attach angular fields in a separate call:

```tsx
useAttachAll(room, "players", { mode: "lerp", fields: ["x", "y", "z"] });
useAttachAll(room, "players", { mode: "lerp", fields: ["heading"], angle: true });
```

#### `useEventChannel(room, options)`

Optimistic event channel. This hook is `predict.defineEvent()` with teardown on unmount, **plus reactivity**: whenever the channel settles (predict / confirm / reject / unpredicted), the calling component re-renders. Flag-shaped derives then work in plain render code:

```tsx
const pickups = useEventChannel(room, {
  confirmOn: { collection: "items", field: "alive", equals: false },
});

const hidden = !item.alive || pickups?.has(id);   // reactive
```

The returned object is the real SDK channel. Hand it to `ctx.predict` inside a reconciler step, or call `channel.predict(payload)` from UI code.

#### `useEntityInstance(room, select)` / `useSessionEntity(room, collectionKey)`

Select a **decoded schema instance** (what the Predict APIs key off), re-rendering only when its identity changes, never on field updates. `useSessionEntity` is the common case: your own entity by `sessionId`:

```tsx
const me = useSessionEntity(room, "players");
const flag = useEntityInstance(room, (state) => state.ctf.flag);
```

#### `useInputBuffer()`

The ["buffer, then consume"](https://docs.colyseus.io/netcode/recipes.md#taps-between-steps-buffer-then-consume) input recipe as a hook. Input is sampled once per fixed step, not per render frame. A tap on a 0-step frame must not be lost, and a tap spanning a multi-step frame must not fire twice. Call `press()` in the React event handler, `consume()` inside the send loop so the tap lands on exactly one fixed step:

```tsx
const jump = useInputBuffer();

<button onPointerDown={jump.press}>Jump</button>

// inside the usePredictLoop callback:
input.data.jump = jump.consume();
```

#### `getSchemaInstance(snapshot)`

Not a hook: bridges `useRoomState` snapshots back to their decoded instance, for `predict.value()` reads on entities you render from snapshot lists:

```tsx
const source = getSchemaInstance(playerSnapshot);

useFrame(() => {
  meshRef.current.position.x = predict.value(source, "x");
});
```

For a complete working example (R3F + prediction + remote lerp), see [r3f-lobby-car-prototype](https://github.com/endel/r3f-lobby-car-prototype).

### Contexts

#### `createRoomContext()`

Creates a set of hooks and a `RoomProvider` component that share a single room connection across React reconciler boundaries (e.g. DOM + React Three Fiber). The room is stored in a closure-scoped external store rather than React Context, so the hooks work in any reconciler tree that imports them.

```tsx
import { Client } from "@colyseus/sdk";
import { createRoomContext } from "@colyseus/react";

const client = new Client("ws://localhost:2567");

const { RoomProvider, useRoom, useRoomState } = createRoomContext();
```

**Wrap your app with `RoomProvider`:**

```tsx
function App() {
  return (
    <RoomProvider connect={() => client.joinOrCreate("game_room")}>
      <UI />
      <Canvas>
        <GameScene />
      </Canvas>
    </RoomProvider>
  );
}
```

`RoomProvider` accepts a `connect` callback (same as the standalone `useRoom` hook) and an optional `deps` array. Pass a falsy value to `connect` to defer the connection.

**Use the hooks in any component, DOM or R3F:**

```tsx
function UI() {
  const { room, error, isConnecting } = useRoom();
  const players = useRoomState((state) => state.players);

  if (isConnecting) return <p>Connecting...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return <p>Players: {players?.size}</p>;
}
```

The returned `useRoom()` and `useRoomState(selector?)` work identically to the standalone hooks but don't require you to pass the room as an argument.

On Colyseus 0.18+, the context also returns room-bound versions of every [netcode hook](#netcode-hooks-colyseus-018) (`usePredict`, `useInput`, `usePredictLoop`, `useReconciler`, `useAttachAll`, `useEventChannel`, `useEntityInstance`, `useSessionEntity`), with shared Predict options passed once via `createRoomContext({ predict: { mode: "lerp", delay: 100 } })`.

#### `createLobbyContext()`

Creates a `LobbyProvider` and `useLobby` hook for sharing lobby room data globally across your app. Useful when you need room metadata available persistently alongside an active game room, not just on a lobby screen. Like `createRoomContext`, it uses a closure-scoped external store so the hook works across reconciler boundaries.

```tsx
import { Client } from "@colyseus/sdk";
import { createLobbyContext, createRoomContext } from "@colyseus/react";

const client = new Client("ws://localhost:2567");

const { LobbyProvider, useLobby } = createLobbyContext<MyMetadata>();
const { RoomProvider, useRoom, useRoomState } = createRoomContext();
```

**Wrap your app with `LobbyProvider` (can nest with `RoomProvider`):**

```tsx
function App() {
  return (
    <LobbyProvider connect={() => client.joinOrCreate("lobby")}>
      <RoomProvider connect={() => client.joinOrCreate("game_room")}>
        <UI />
        <Canvas>
          <GameScene />
        </Canvas>
      </RoomProvider>
    </LobbyProvider>
  );
}
```

`LobbyProvider` accepts a `connect` callback (same as `useLobbyRoom`) and an optional `deps` array. The lobby connection persists independently of the game room.

**Access lobby data from any component, even deep inside the game:**

```tsx
function RoomBrowser() {
  const { rooms, error, isConnecting } = useLobby();

  if (isConnecting) return <p>Loading rooms...</p>;
  if (error) return <p>Error: {error.message}</p>;

  return (
    <ul>
      {rooms.map((room) => (
        <li key={room.roomId}>
          {room.metadata.displayName}: {room.clients}/{room.maxClients}
        </li>
      ))}
    </ul>
  );
}
```

The returned `useLobby()` hook provides the same fields as `useLobbyRoom` (`rooms`, `room`, `error`, `isConnecting`).

---

## Using `@colyseus/sdk` directly

If you prefer manual control over the room lifecycle without the `@colyseus/react` package, you can use `@colyseus/sdk` directly with `useEffect`:

```typescript filename="RoomComponent.tsx"
import { useEffect, useState, useRef } from "react";
import { Client, Room } from "@colyseus/sdk";

const client = new Client("http://localhost:2567");

function RoomComponent () {
    const roomRef = useRef<Room>();
    const [ sessionIds, setSessionIds ] = useState<string[]>([]);

    useEffect(() => {
        const req = client.joinOrCreate("my_room", {});

        req.then((room) => {
            roomRef.current = room;
            room.onStateChange((state) => setSessionIds(Array.from(state.players.keys())));
        });

        return () => { req.then((room) => room.leave()); };
    }, []);

    return (
        <div>
            {sessionIds.map((sessionId) => (
                <div key={sessionId}>{sessionId}</div>
            ))}
        </div>
    );
}
```

> **Note:**
>
> The `@colyseus/react` hooks handle StrictMode, cleanup, and reconnection automatically. Use direct SDK access only when you need full control over the connection lifecycle.

## Next Steps

- [Client SDK API Reference](https://docs.colyseus.io/sdk.md) - Full API documentation for all methods, events, and room operations
- [Client Prediction & Reconciliation](https://docs.colyseus.io/netcode/client-prediction.md) - The netcode concepts behind the Predict hooks
- [State Synchronization](https://docs.colyseus.io/state.md) - Understanding Schema definitions
- [Room API](https://docs.colyseus.io/room.md) - Server-side room implementation

---
Source: https://docs.colyseus.io/getting-started/react


# Create a Server

A Colyseus game has a server and one or more clients. The server runs your game rooms and owns their state. Clients connect to it. This page creates the server, and the [client SDK pages](https://docs.colyseus.io/getting-started.md#connect-a-client) connect to it.

## Prerequisites

- [ Node.js](https://nodejs.org/) LTS version (or [Bun](https://bun.sh/))
- [ Git](https://git-scm.com/downloads)
- A code editor ([VS Code](https://code.visualstudio.com/) recommended)

## Setting up your server

### Create your Colyseus server

**npm**

``` bash filename="Terminal: npm"
# Create a new Colyseus project
npm create colyseus-app@latest ./my-server

# Enter the project directory
cd my-server

# Run the server
npm start
```

**pnpm**

``` bash filename="Terminal: pnpm"
# Create a new Colyseus project
pnpm create colyseus-app@latest ./my-server

# Enter the project directory
cd my-server

# Run the server
pnpm start
```

**yarn**

``` bash filename="Terminal: yarn"
# Create a new Colyseus project
yarn create colyseus-app ./my-server

# Enter the project directory
cd my-server

# Run the server
yarn start
```

**Bun**

``` bash filename="Terminal: Bun"
# Create a new Colyseus project
bun create colyseus-app@latest ./my-server

# Enter the project directory
cd my-server

# Install Bun transport & Run the server
bun add @colyseus/bun-websockets
bun run src/index.ts
```

The generator asks which language to use and what you're building. **Minimal server** is enough to follow along. See [Scaffolding options](#scaffolding-options) for every preset and flag.

The server listens on `http://localhost:2567`. Open that address in a browser to reach the [Playground](https://docs.colyseus.io/tools/playground.md), where you can join a room and send messages without writing a client.

### Add players to your room

The generated room has no game logic yet. Replace both files below. The Quick Example on each client SDK page joins this room: it reads the `players` map, sends `move`, and listens for `chat`.

```ts filename="src/rooms/schema/MyRoomState.ts"
import { schema, t, type SchemaType } from "@colyseus/schema";

export const Player = schema({
  x: t.number().default(0),
  y: t.number().default(0),
});
export type Player = SchemaType<typeof Player>;

export const MyRoomState = schema({
  players: t.map(Player),
});
export type MyRoomState = SchemaType<typeof MyRoomState>;
```

```ts filename="src/rooms/MyRoom.ts"
import { Room, Client, CloseCode } from "colyseus";
import { MyRoomState, Player } from "./schema/MyRoomState.js";

export class MyRoom extends Room<{ state: MyRoomState }> {
  maxClients = 4;
  state = new MyRoomState();

  messages = {
    move: (client: Client, message: { x: number, y: number }) => {
      const player = this.state.players.get(client.sessionId);
      if (!player) { return; }

      player.x = message.x;
      player.y = message.y;
    },
  };

  onJoin(client: Client, options: any) {
    this.state.players.set(client.sessionId, new Player());
    this.broadcast("chat", `${client.sessionId} joined.`);
  }

  onLeave(client: Client, code: CloseCode) {
    this.state.players.delete(client.sessionId);
    this.broadcast("chat", `${client.sessionId} left.`);
  }
}
```

Each client gets a `Player` entry when it joins, and the server moves it when that client sends `move`. Every change to `players` reaches all clients in the room. `npm start` restarts the server when a file changes. If you chose JavaScript, use the same code without the type annotations.

### Connect a client

Pick the SDK for your engine or framework under [Connect a client](https://docs.colyseus.io/getting-started.md#connect-a-client), and run its Quick Example against this server.

## Build your game logic

The room is where your game runs. Continue with:

- [Room API](https://docs.colyseus.io/room.md)
- [State Synchronization](https://docs.colyseus.io/state.md)
- [Netcode: Prediction & Lag Comp](https://docs.colyseus.io/netcode.md)

## Scaffolding options

`create-colyseus-app` asks a few questions and creates the project from your answers. Each option adds working, wired-in code, and the room comes with a headless test.

### Presets

The first question is what you're building. Pick a preset, or **Custom** to choose each feature individually.

| Preset | `--preset` | What you get |
| --- | --- | --- |
| **Minimal server** | `minimal` | A single room, nothing else. |
| **Realtime action** | `realtime-action` | Vite project (client, server and shared code) with an authoritative fixed tick, server-validated input and client-side prediction, plus lobby and reconnection. TypeScript only. |
| **Turn-based** | `turn-based` | Server-owned turn order with a per-turn deadline, plus reconnection. |
| **Custom** | `custom` | Asks every question: layout, netcode, matchmaking, authentication and database. |

### Using command-line options

Every question has a flag. Options you pass are not asked, and they override the preset. `--yes` fills the rest with defaults, so a single command works in a terminal, a script, or CI.

``` bash filename="Terminal"
npm create colyseus-app@latest my-server -- --preset realtime-action --yes

npm create colyseus-app@latest my-server -- --ts --layout vite --netcode fixed \
    --matchmaking lobby,reconnection --auth module --database colyseus --yes
```

> **Note:**
>
> `npm create` needs the `--` separator to forward options to the generator. `pnpm`, `yarn`, `bun create` and `npx create-colyseus-app@latest` don't.

Pass `.` as the directory to scaffold into the current folder. Omit the directory to be asked for a project name.

| Option | Choices (first is the default) |
| --- | --- |
| `--language` | `typescript` · `esm` · `cjs` · `haxe`. Also as shorthand flags: `--ts`, `--esm`, `--cjs`, `--haxe` |
| `--preset` | `minimal` · `realtime-action` · `turn-based` · `custom` |
| `--layout` | `server` · `vite` (client + server + shared code in one Vite project) · `monorepo` (`apps/backend` + `apps/frontend`) |
| `--netcode` | `none` · `fixed` (fixed tick + client prediction) · `tick` (simple server tick) · `turn-based` · `relay` (client-authoritative) |
| `--matchmaking` | none by default. Comma-separated: `lobby` · `filterby` · `reconnection` · `idle-kick` |
| `--auth` | `none` · `onauth` (validate a token in `onAuth()`, no dependencies) · `module` (`@colyseus/auth`: anonymous + email/password) · `oauth` (`@colyseus/auth` + OAuth provider) |
| `--oauth-provider` | `discord` · `google` · `github` · `twitch` |
| `--database` | `none` · `colyseus` (`@colyseus/database`: SQLite in development, Postgres in production) |

The `realtime-action` preset, the `vite` and `monorepo` layouts, `fixed` netcode, `oauth` and the database require TypeScript. Haxe projects take none of these options: the generator copies the Haxe template as is.

Other flags: `--name <pkg-name>`, `--git` (initialize a repository with a first commit), `--no-install`, `--overwrite`. Run `npx create-colyseus-app@latest --help` for the full reference.

---
Source: https://docs.colyseus.io/getting-started/server


# Swift

> **Warning:**
>
> The Swift SDK is in **beta**, and may not be stable. Please [report any issues you find](https://github.com/colyseus/native-sdk/issues).

The Swift SDK is a Swift package over the shared [Colyseus Native SDK](https://github.com/colyseus/native-sdk), the same core behind the Flutter, Godot and GameMaker SDKs. The work on the Native SDK is still in progress, so expect some breaking changes as we go.

The package is published at [colyseus/colyseus-swift](https://github.com/colyseus/colyseus-swift), a read-only mirror generated on every release. Swift Package Manager resolves a package from a repository root and only understands plain semver tags, so the mirror gives it both. Report issues and send pull requests to [colyseus/native-sdk](https://github.com/colyseus/native-sdk), where the source lives under `platforms/swift`.

## Platforms

- macOS (13+)
- iOS (15+), including the simulator
- tvOS (15+), including the simulator

The package targets Swift 6 language mode and needs Xcode 16 or newer. Linux, visionOS and watchOS are not supported.

The core is Zig as much as it is C, so SwiftPM cannot compile it from source. It arrives as a prebuilt `Colyseus.xcframework` that the package downloads for you. There is no toolchain to install.

## Installation

In Xcode, choose **File → Add Package Dependencies…** and enter the repository URL:

```
https://github.com/colyseus/colyseus-swift
```

Or declare it in your `Package.swift`:

```swift filename="Package.swift"
dependencies: [
    .package(url: "https://github.com/colyseus/colyseus-swift", from: "0.18.1"),
],
targets: [
    .executableTarget(
        name: "MyGame",
        dependencies: [.product(name: "Colyseus", package: "colyseus-swift")]
    ),
]
```

Then import the single module:

```swift
import Colyseus
```

### Sandboxed macOS apps

A sandboxed macOS app needs the outbound-network entitlement, `com.apple.security.network.client`, or every connection fails silently. Add it under **Signing & Capabilities → App Sandbox → Outgoing Connections (Client)**, or directly in the entitlements file:

```xml filename="MyGame.entitlements"
<key>com.apple.security.network.client</key>
<true/>
```

iOS and tvOS apps need no entitlement for outgoing connections.

## Project Setup

The transport runs on its own thread. Inbound traffic is queued there and released inside `Colyseus.pump()`, so decoding, listeners and prediction all run on the thread that pumped. Handlers are delivered on `Colyseus.callbackQueue`, which is the main queue by default.

By default the SDK pumps on its own timer at 60 Hz, and you can join a room without any further setup. A SwiftUI or UIKit app can copy values from a listener into its own observable model and leave it at that.

Games that render every frame should drive the SDK instead. Set `Colyseus.autoPump` to `false` once, then call `Colyseus.pump()` at the top of your frame callback. Decoding, prediction and rendering then all observe the same state within a frame:

```swift filename="GameScene.swift"
import Colyseus
import SpriteKit

final class GameScene: SKScene {
    override func didMove(to view: SKView) {
        Colyseus.autoPump = false // the app owns the frame from here on
    }

    override func update(_ currentTime: TimeInterval) {
        Colyseus.pump() // decode inbound traffic, then deliver listeners

        // read room state and draw
    }
}
```

> **Warning:**
>
> Two pumps racing each other put decoding back on a second thread. Turn `autoPump` off before you start calling `pump()` yourself.

## Quick Example

> **Note:**
>
> The state schema and messages in this example come from the room built in [Create a Server](https://docs.colyseus.io/getting-started/server.md). Start that server before you run it.

This example shows how to connect to a room, listen for state changes, send messages and leave the room.

```swift filename="Network.swift"
import Colyseus

final class Network {
    var client: Colyseus.Client?
    var room: Colyseus.Room<MyRoomState>?

    func connect() async throws {
        let client = try Colyseus.Client(endpoint: "ws://localhost:2567")

        // Options are optional, and are JSON-encoded before they are sent.
        let room = try await client.joinOrCreate(
            "my_room", options: ["name": "Player 1"], state: MyRoomState.self
        )
        self.client = client
        self.room = room

        print("Joined \(room.name ?? "") (\(room.id ?? "")) as \(room.sessionId ?? "")")

        room.onStateChange { state in
            print("players: \(state.players.count)")
        }

        room.onMessage("chat") { payload in
            print("chat: \(payload.string ?? "")")
        }

        room.onError { code, message in print("error \(code): \(message)") }
        room.onLeave { code, _ in print("left with code \(code)") }

        room.send("move", ["x": 10, "y": 20])
    }

    func disconnect() {
        room?.leave()
        room = nil
        client = nil
    }
}
```

`MyRoomState` is a generated class, see [Reading State](#reading-state). Every join method is `async throws` and returns a `Colyseus.Room<State>`. `options:` is JSON-encoded and sent to the server; `state:` types the room:

| Method | Description |
| --- | --- |
| `joinOrCreate(roomName, options: ..., state: ...)` | Join an available room, or create one |
| `join(roomName, ...)` | Join an existing room only |
| `create(roomName, ...)` | Always create a new room |
| `joinById(roomId, ...)` | Join a specific room by its id |
| `reconnect(token: reconnectionToken, state: ...)` | Rejoin a room this client was dropped from |
| `consumeSeatReservation(reservation, state: ...)` | Join with a seat your backend reserved, as a `Colyseus.SeatReservation` or a message payload. See [Consuming a Seat Reservation](https://docs.colyseus.io/sdk.md#consuming-a-seat-reservation). Requires 0.18.9 |

A refused join throws `Colyseus.Error.matchmaking(code:message:)` with the server's own code and message. The call returns once the join handshake completes, so `room.sessionId` and `room.state` are already set when you get the room.

Endpoints accept `ws://`, `wss://`, `http://` and `https://`. Pass a `Colyseus.Settings` instead of an endpoint to set custom headers or a certificate bundle.

## Sending Messages

```swift
room.send("move", ["x": 10, "y": 20]) // map, array, string, number, bool or nil
room.send("ready")                     // payload is optional

room.send(1, [10, 20])                 // numeric message type
room.sendBytes("snapshot", data)       // raw Data, skips MessagePack
```

Payloads are `MessagePackValue`. Swift literals convert to it, so a dictionary, array, string, number or `true` works in place.

### Request and response

`room.request()` sends a message and awaits the reply from the server's matching handler. See [Request and response](https://docs.colyseus.io/room.md#responding-to-a-message-requestresponse) for the server-side handler.

```swift
do {
    let profile = try await room.request("get-profile", ["id": 42])
    print(profile["name"]?.string ?? "")
} catch Colyseus.Error.requestRejected(let reason) {
    print("rejected: \(reason)") // the reason the handler passed to ctx.reject()
} catch Colyseus.Error.requestTimedOut {
    print("no reply")
}
```

A handler that throws surfaces as `requestFailed(name:message:code:)`, and a room that closes first as `roomClosed(code:reason:)`. The default timeout is 10 seconds; change it per call with `timeout:`, or process-wide through `Colyseus.defaultRequestTimeout`.

## Receiving Messages

Every registration returns a `Subscription`. Keep it and call `cancel()` to remove the handler, or ignore the return value to keep the handler for the room's lifetime.

```swift
room.onMessage("chat") { payload in
    print(payload["text"]?.string ?? "")
}

// Every message, whatever its type.
room.onMessage { type, payload in
    print("\(type): \(payload)")
}

// Messages the server sent with client.sendBytes().
room.onMessageBytes("snapshot") { data in
    print("\(data.count) bytes")
}
```

`MessagePackValue` exposes typed accessors (`string`, `int`, `double`, `bool`, `array`, `map`) and subscripts by key and by index. Each returns `nil` when the value has another type.

The room exposes these listeners:

| Listener | Handler receives | Fires when |
| --- | --- | --- |
| `onJoin` | nothing | the client is seated and the first state has arrived |
| `onStateChange` | `State` | a state patch has been applied |
| `onMessage(type)` | `MessagePackValue` | the server sends a message of `type` |
| `onMessage` | `MessageType, MessagePackValue` | the server sends any message |
| `onMessageBytes(type)` | `Data` | the server sends raw bytes of `type` |
| `onError` | `Int32, String` | the server reports an error, with code and message |
| `onLeave` | `Int32, String` | the room closes for good, with the close code |
| `onDrop` | `Int32, String` | the connection drops and automatic reconnection starts |
| `onReconnect` | nothing | automatic reconnection succeeds |

## Reading State

Generate one Swift class per schema from your server's types. Codegen is optional, and it buys type safety and autocomplete in Xcode:

```sh filename="Terminal"
npx schema-codegen src/rooms/schema/* --swift --bundle --output ../client/Sources/MyGame/Gen/
```

> **Note:**
>
> See the full [State Schema Codegen documentation](https://docs.colyseus.io/state/callbacks.md#frontend-schema-generation) for more options and details.

Each generated class is a typed facade over the decoded state. Numbers read as `Double`, strings as `String`, and collections as `MapSchema` and `ArraySchema`:

```swift filename="Gen/Schema.swift"
import Colyseus

public final class Player: SchemaRef, @unchecked Sendable {
    public var x: Double { view["x"] }
    public var y: Double { view["y"] }
    public var name: String { view.string("name") ?? "" }
}

public final class MyRoomState: SchemaRef, @unchecked Sendable {
    public var players: MapSchema<Player> { mapOf("players") }
    public var currentTurn: String { view.string("currentTurn") ?? "" }
}
```

Join with the generated root class. The room is then typed end to end: `room.state` is a `MyRoomState?`, and `onStateChange` fires with it after every patch.

```swift
let room = try await client.joinOrCreate("my_room", state: MyRoomState.self)

room.onStateChange { state in
    for (sessionId, player) in state.players.entries {
        print("\(sessionId): \(player.x), \(player.y)")
    }

    if let sessionId = room.sessionId, let me = state.players[sessionId] {
        print(me.name)
    }
}
```

Decoding never depends on generated code. The core builds its own picture of the state from the reflection data sent during the handshake. A generated class is only a typed way to read what was decoded.

> **Warning:**
>
> A `SchemaRef` points at an instance the decoder owns, and the decoder replaces instances on a full resync or a reconnect. Read instances afresh from `room.state` each frame rather than caching one across frames.

### Without codegen

Join with `SchemaRef` itself as the state type and read fields by name through `view`. Collections come back as `MapSchema<SchemaRef>` and `ArraySchema<SchemaRef>`:

```swift
let room = try await client.joinOrCreate("my_room", state: SchemaRef.self)

room.onStateChange { state in
    print(state.view.string("currentTurn") ?? "")

    for (sessionId, player) in state.mapOf("players", SchemaRef.self).entries {
        print("\(sessionId): \(player.view["x"]), \(player.view["y"])")
    }
}
```

| Accessor | Returns |
| --- | --- |
| `view["field"]` | the numeric field as `Double`; booleans read as 0 or 1 |
| `view.string("field")` | a `String`, or nil |
| `view.bool("field")` | a `Bool` |
| `refOf("field", T.self)` | a nested instance, or nil |
| `mapOf("field", T.self)` | a `MapSchema<T>` |
| `arrayOf("field", T.self)` | an `ArraySchema<T>` |
| `view.fieldNames` | every field declared on the type |

`view["field"]` returns `.nan` for a field the schema does not declare. A typo then shows up as an obviously broken value instead of a plausible zero.

## State Callbacks

Schema callbacks live on `room.callbacks`, also reachable as `Colyseus.Callbacks.get(room)`. Registration takes the field to observe, and collection handlers receive the key and the value. Passing a generated getter's value (`state.players`) binds the registration to the field itself. The registration then survives the server replacing the collection:

```swift
let callbacks = room.callbacks
let state = room.state! // joined with state: MyRoomState.self

callbacks.listen(state, "currentTurn", as: String.self) { value, previous in
    print("turn: \(previous ?? "-") -> \(value ?? "-")")
}

callbacks.onAdd(state.players) { sessionId, player in
    print("+ player joined: \(sessionId)")

    callbacks.listen(player, "x", as: Double.self) { x, previous in
        print("\(sessionId) x: \(previous ?? 0) -> \(x ?? 0)")
    }

    callbacks.onChange(player) {
        print("\(sessionId) changed")
    }
}

callbacks.onRemove(state.players) { sessionId, player in
    print("- player left: \(sessionId)")
}
```

Map keys arrive as `String` and array indexes as `Int`. `listen` and `onAdd` replay what already decoded, so a late subscription still sees every player and `listen` fires with the current value (pass `immediate: false` to skip the replay). Every handler fires inside `Colyseus.pump()`, in the same frame as the patch that caused it.

## Prediction

Waiting for the server to confirm your own movement costs a round trip. The predict layer applies each input immediately and reconciles when the server disagrees. See [Client Prediction](https://docs.colyseus.io/netcode/client-prediction.md) for the concepts. Your room class must declare [`defineInput()`](https://docs.colyseus.io/netcode/server-input.md) before any of this works.

```swift filename="Gameplay.swift"
Colyseus.autoPump = false // the app drives the frame

let predict = Colyseus.Predict.get(room)!
let input = room.input()! // nil when the server room declares no defineInput()

// Other players are smoothed, since their inputs aren't yours to predict.
predict.attachAll(
    state.players, fields: ["x", "y"], options: .init(mode: .damped), except: room.sessionId
)

// Yours is predicted and reconciled.
let me = state.players[room.sessionId!]!
let reconciler = predict.reconciler(
    truth: me, input: input, fields: ["x", "y", "vx", "vy"]
) { ctx, state, command in
    stepPlayer(state, command, dt: ctx.dt) // shared with the server
}

override func update(_ currentTime: TimeInterval) {
    Colyseus.pump()                          // decode inbound, deliver events

    for _ in 0 ..< predict.tick(room.clock.now) {
        input.data.set("moveX", to: keyboard.x)
        input.send()                         // applied locally right away
    }

    draw(x: predict.value(me, "x"), y: predict.value(me, "y"))
}
```

Points worth knowing before you build on it:

- The order inside the frame matters: pump, then tick and send, then draw. A pose read before the pump is a frame stale.
- `room.input()` returns `nil` when the server room declares no `defineInput()`. The input schema comes from the handshake, so nothing has to be generated for it.
- `predict.tick()` takes `room.clock.now`, the timebase the server shares. Never pass `Date()` or wall time.
- `step` has to compute exactly what the server computes. When it does, `reconciler.drift.status` stays `.matched`; when it drifts, that value tells you.
- Guard one-shot effects inside a step on `!ctx.isReplay`, or they repeat on every rollback. Use `ctx.memo()` to freeze a value a replay could not re-derive.
- Call `reconciler.reset()` and `input.reset()` in `onReconnect`. Sequence numbers restart at zero, so replaying the old ones would corrupt the mirror.

`Predict` also covers dead reckoning (`attachAllReckon`), and the `Colyseus` namespace includes `EventChannel` for optimistic events and `Spawns` for entities you create before the server does.

## Reconnection

The SDK reconnects on its own when the connection drops. `onDrop` fires when the retry starts and `onReconnect` when it succeeds; `onLeave` fires only once the room is gone for good. Tune the policy through `room.reconnection`, a `ReconnectionOptions` value:

```swift
room.onDrop { code, reason in showReconnecting() }
room.onReconnect { hideReconnecting() }

var policy = room.reconnection
policy.maxRetries = 10
room.reconnection = policy
```

To take back a seat after the process was gone, keep `room.reconnectionToken` and pass it to `client.reconnect(token:state:)`. The server has to hold the seat with `allowReconnection()`, and `room.leave(consented: false)` is what reports a departure as a drop.

## HTTP & Auth

`client.http` resolves paths against the client endpoint. A reply outside 2xx throws `Colyseus.Error.http(status:body:)`:

```swift
let res = try await client.http.get("/test")
print(res.status)
print(res.json?["things"] ?? .null)

struct Things: Decodable { let things: [String] }
let things = try res.decode(Things.self)

try await client.http.post("/save", json: #"{"name": "endel"}"#)
```

`client.auth` covers the [authentication](https://docs.colyseus.io/auth.md) endpoints, and throws `Colyseus.Error.auth` on a rejected call:

```swift
let user = try await client.auth.signInAnonymously()
print(user.data["anonymousId"] ?? .null)

try await client.auth.signIn(email: "user@example.com", password: "secret")
try await client.auth.register(email: "user@example.com", password: "secret")
try await client.auth.sendPasswordReset(email: "user@example.com")

// The token is shared with client.http, so later requests are authenticated.
client.auth.onChange { user in
    if user == nil { showLoginScreen() }
}

client.auth.signOut()
```

> **Note:**
>
> The token persists in the system keychain under one process-wide key, so it survives a restart. A test suite that signs in should sign out again, or set `client.auth.storageKey`, otherwise later clients send a token the next server rejects.

## Testing latency

Every room can delay its own traffic, which is how you check that prediction and reconnection hold up on a bad connection:

```swift
room.setLatency(delayMs: 200, jitterMs: 30) // round trip, split evenly across both directions
room.dropConnection()                       // kill the socket the way a lost network would

let rtt = try await room.ping()             // one explicit round trip, in milliseconds
```

`Colyseus.Client.latency(of:)` and `Colyseus.Client.fastestEndpoint(among:)` measure endpoints before you connect, for picking a region.

## Known Limitations

- **No `SetSchema` or `CollectionSchema`.** Neither exists in the core; use `MapSchema` and `ArraySchema`.
- **Unreliable input is not available.** It needs a datagram transport the core does not have yet.
- **No SwiftUI or Combine integration ships.** Handlers arrive on the main queue; copy what you need into your own observable model.

## Demos

Two clients are built on this package, and are the best place to see it used:

- [Air Hockey](https://github.com/colyseus/air-hockey-demo/tree/main/clients/swift-app): SpriteKit on macOS, with rollback prediction for the paddle
- [Prediction Playground](https://github.com/colyseus/prediction-playground/tree/main/clients/swift-app): all twelve netcode labs, see [Learn](https://docs.colyseus.io/learn.md#prediction-playground)

## Next Steps

- [Netcode: Prediction & Lag Comp](https://docs.colyseus.io/netcode.md) - The prediction stack, and the server settings it needs
- [State Synchronization](https://docs.colyseus.io/state.md) - Understanding Schema definitions
- [Room API](https://docs.colyseus.io/room.md) - Server-side room implementation

---
Source: https://docs.colyseus.io/getting-started/swift


# JavaScript / TypeScript SDK

<_js_ts_header />

---

## Installation

**Package Manager**

```sh npm2yarn
npm install --save @colyseus/sdk
```

The SDK includes TypeScript definitions out of the box.

**CDN**

Include directly from unpkg:

```html
<script src="https://unpkg.com/@colyseus/sdk/dist/colyseus.js"></script>
```

This URL always loads the latest release. In production, pin the version your server uses by adding it after the package name: `@colyseus/sdk@<version>`.

**Download**

Download the release binaries from [GitHub Releases](https://github.com/colyseus/colyseus/releases?q=%22%40colyseus%2Fsdk%22&expanded=true) and include them in your project:

```html
<script src="colyseus.js"></script>
```

## Quick Example

> **Note:**
>
> The state schema and messages in this example come from the room built in [Create a Server](https://docs.colyseus.io/getting-started/server.md). Start that server before you run it.

Connect to a server, join a room, and listen for state changes:

```ts
import { Client, Callbacks } from "@colyseus/sdk";

const client = new Client("http://localhost:2567");

// Join or create a room
const room = await client.joinOrCreate("my_room");

// Get state callbacks handler
const callbacks = Callbacks.get(room);

// Listen for entities being added to a collection
callbacks.onAdd("players", (player, sessionId) => {
    console.log("Player joined:", sessionId);

    // Listen for changes on nested properties
    callbacks.listen(player, "x", (currentX, previousX) => {
        console.log("Player", sessionId, "x:", currentX);
    });
});

// Listen for entities being removed from a collection
callbacks.onRemove("players", (player, sessionId) => {
    console.log("Player left:", sessionId);
});

// Send a message to the server
room.send("move", { x: 10, y: 20 });

// Listen for messages from the server
room.onMessage("chat", (message) => {
    console.log("Chat:", message);
});
```

> **Note:**
>
> Use `https://` (or `wss://`) for secure connections in production.

## Type Safety (TypeScript)

### Full Type Safety: Room State and Messages

Provide the `typeof server` type as a generic to the client. This generic allows the client to infer both the state type and the message types for the room.

```ts
import { Client } from "@colyseus/sdk";
import type { server } from "../../server/src/app.config.ts";

const client = new Client<typeof server>("http://localhost:2567");
```

> **Note:**
>
> `import type` only imports type information at compile time, so no server code is included in your client bundle.

### Providing Room State Types

There are two ways to get type safety for your room's state:

#### Option 1: Importing the Room **State** Type Only

Use `import type` to import the state type and pass it as a generic to `joinOrCreate<T>()`. This generic gives you **type inference** for `room.state` and state callbacks.

This way, you don't get type inference for the message name or the payload type.

```ts {2,5}
import { Client } from "@colyseus/sdk";
import type { MyState } from "../server/rooms/schema/MyState";

const client = new Client("http://localhost:2567");
const room = await client.joinOrCreate<MyState>("my_room");

room.state.players  // ✓ Auto-complete works
room.state.invalid  // ✗ Compile error

room.onMessage("...", (client, payload) => {}); // ?? Missing type here!
```

#### Option 2: Importing the **Room** Type Only

Use `import type` and pass the type as a generic to `joinOrCreate<T>()`. This generic gives you **type inference** for `room.state` and state callbacks.

```ts {2,5}
import { Client } from "@colyseus/sdk";
import type { MyRoom } from "../server/rooms/MyRoom";

const client = new Client("http://localhost:2567");
const room = await client.joinOrCreate<MyRoom>("my_room");

room.state.players  // ✓ Auto-complete works
room.state.invalid  // ✗ Compile error

room.onMessage("...", () => {}); // ✓ Type-safe
```

### Sharing Schema Classes with the Client

If you import the actual schema class (not just its type) and pass it as the **third argument** to `joinOrCreate()`, you get two benefits:

1. **Custom methods available**: Any custom methods you've defined on your schema classes become accessible on the client.
2. **Reduced bandwidth**: The server skips sending the state structure definition when the client joins, since the client already knows the schema shape.

```ts {2,5}
import { Client } from "@colyseus/sdk";
import { MyState } from "../server/rooms/MyState";

const client = new Client("http://localhost:2567");
const room = await client.joinOrCreate("my_room", {}, MyState);

room.state.players  // ✓ Auto-complete works
room.state.players.get("abc")?.customMethod()  // ✓ Custom methods available
```

---

## Room Debug Panel

The debug panel allows you to inspect the room state and messages in real-time during development, simulate high latency conditions, connection drops, and more.

You can enable the Room Debug Panel in development mode by:

```ts {1}
import "@colyseus/sdk/debug";
```

![](https://docs.colyseus.io/getting-started/ts-sdk-debug.png)

---

## Troubleshooting: `tsconfig.json` Configuration

If you define your state with the [`@type()` decorator style](https://docs.colyseus.io/state/schema/decorators.md) and target ES2022 or ESNext, ensure your `tsconfig.json` includes:

```json filename="tsconfig.json"
{
    "compilerOptions": {
        "useDefineForClassFields": false,
        "experimentalDecorators": true,
        "strict": true
    }
}
```

These flags are required only for `@type()` decorators. The recommended [`schema()` builder](https://docs.colyseus.io/state/schema.md) works without them.

## Next Steps

- [Client SDK API Reference](https://docs.colyseus.io/sdk.md) - Full API documentation for all methods, events, and room operations
- [State Synchronization](https://docs.colyseus.io/state.md) - Understanding Schema definitions
- [State Sync Callbacks](https://docs.colyseus.io/state/callbacks.md) - Listen for state changes
- [Phaser Tutorial](https://docs.colyseus.io/learn/tutorial/phaser.md) - Complete game example

---
Source: https://docs.colyseus.io/getting-started/typescript


# Unity SDK

## Install package

**Unity Package Manager (UPM)**

- Go to **Window → Package Management → Package Manager**. Click "+" button, then select "Add package from git URL..."
    - Enter Git URL: `https://github.com/colyseus/colyseus-unity-sdk.git#upm`
    - Click "ADD"

    Click to import the example project in order to test the built-in demonstration.

**From .unitypackage (legacy)**

- Download the latest [Colyseus Unity SDK](https://github.com/colyseus/colyseus-unity3d/releases/latest/download/Colyseus_Plugin.unitypackage)
    - Import the `Colyseus_Plugin.unitypackage` contents into your project.

    The `Colyseus_Plugin.unitypackage` contains an example project under `Assets/Colyseus/Example` you can use as a reference.

---

### Testing from Unity Editor

Starting with Unity 6000.1.0b1, Unity integrates [Multiplayer Play Mode](https://docs-multiplayer.unity3d.com/mppm/current/about/). This mode lets you test your Colyseus-based game with multiple clients inside the Unity Editor, without building the application.

- See how to install [Multiplayer Play Mode](https://docs-multiplayer.unity3d.com/mppm/current/install/)
- Alternatively, you can use [ParrelSync](https://github.com/VeriorPies/ParrelSync) for older versions of Unity.

## SDK Example Project

The example project [included in the SDK package](https://github.com/colyseus/colyseus-unity-sdk/tree/master/Assets/Colyseus/Runtime/Example~) does not contain any visual components or UI. It contains the majority of important method calls you would be using in a real-world application.

![Import Example](https://docs.colyseus.io/getting-started/unity-sdk-import-example.png)

- Joining into a custom room with Messages and State Synchronization
- Joining into a [ LobbyRoom](https://docs.colyseus.io/matchmaker/lobby.md) and listening to its messages
- Joining into a [ QueueRoom](https://docs.colyseus.io/matchmaker/queue.md) and listening to its messages
- [Consuming a seat reservation](https://docs.colyseus.io/sdk.md#other-join-methods) from QueueRoom and joining into the match room

### Running the test server locally

To run the test server locally, you will need to run the following commands in your terminal:

```sh filename="Terminal"
git clone https://github.com/colyseus/sdks-test-server
cd sdks-test-server
npm install
npm start
```

> **Note:**
>
> You can see the source code for the test server [here](https://github.com/colyseus/sdks-test-server).

You should be able to see the server running at `http://localhost:2567`, and the example project will be able to connect to it.

## Quick Example

> **Note:**
>
> The state schema and messages in this example come from the room built in [Create a Server](https://docs.colyseus.io/getting-started/server.md). Start that server before you run it.

This example shows how to connect to a room, listen for state changes via Callbacks, and send messages.

```csharp filename="NetworkManager.cs"
using UnityEngine;
using Colyseus;
using Colyseus.Schema;

public class NetworkManager : MonoBehaviour
{
    Client client;
    Room<MyRoomState> room;

    async void Start()
    {
        client = new Client("ws://localhost:2567");

        room = await client.JoinOrCreate<MyRoomState>("my_room");
        Debug.Log("Joined room: " + room.Id);

        // Get state callbacks handler
        var callbacks = Callbacks.Get(room);

        // Listen for players being added
        callbacks.OnAdd(state => state.players, (sessionId, player) => {
            Debug.Log($"Player joined: {sessionId}");

            callbacks.Listen(player, p => p.x, (currentX, previousX) => {
                Debug.Log($"Player {sessionId} x: {currentX}");
            });
        });

        // Listen for players being removed
        callbacks.OnRemove(state => state.players, (sessionId, player) => {
            Debug.Log($"Player left: {sessionId}");
        });

        // Send a message to the server
        room.Send("move", new { x = 10f, y = 20f });

        // Listen for messages from the server
        room.OnMessage<string>("chat", (message) => {
            Debug.Log("Chat: " + message);
        });
    }

    async void OnDestroy()
    {
        if (room != null) await room.Leave();
    }
}
```

### Waiting for the first state

A resolved join does **not** mean the state has been synchronized yet. `room.State` is instantiated when you join, but its collections (`players`, nested refs, …) are only populated by the first full state sync. That sync arrives a moment later. Code that reads `room.State` right after joining finds empty collections (or `null` ones, with older generated classes) and `null` refs. Don't keep a reference to a collection read before that sync. The decoder replaces it with the server's copy, and the old instance stays empty.

`WaitForFirstState()` covers the gap. This method is the C# analogue of the JavaScript SDK's `room.onStateChange.once(...)`:

```csharp
room = await client.JoinOrCreate<MyRoomState>("my_room");

// wait for the first full state sync before reading room.State
await room.WaitForFirstState();

Debug.Log($"{room.State.players.Count} players already in the room");
```

It resolves immediately when the state has already synchronized, so it is always safe to await, including after reconnections.

> **Warning:**
>
> Never poll for state with `Task.Delay` on **WebGL** builds. WebGL has no thread-pool timers, so `Task.Delay` never resumes and the wait hangs forever. `WaitForFirstState()` is timer-free: it completes on the message pump and works on every platform, including WebGL. When your async code does need a delay or timeout, use [UniTask](https://github.com/Cysharp/UniTask). `UniTask.Delay` runs on Unity's player loop instead of thread-pool timers, so it works on WebGL.

> **Note:**
>
> Registering `Callbacks` (as in the Quick Example above) is safe *before* the first sync. Callbacks are driven by the decoder and fire as the initial state decodes. A callback on a collection the server hasn't sent yet waits for it, whether the field starts empty or `null`. `WaitForFirstState()` is for code that reads `room.State` directly.

### Iterating collections

`MapSchema<T>` implements `IReadOnlyDictionary<string, T>` and `ArraySchema<T>` implements `IReadOnlyList<T>`, so `foreach` and LINQ work on them directly. A map iterates in insertion order, the order the server added the entries, and `foreach` allocates nothing.

```csharp
foreach (var (sessionId, player) in room.State.players) {
    Debug.Log($"{sessionId}: {player.x}, {player.y}");
}

foreach (var player in room.State.players.Values) { Draw(player); }

var alive = room.State.players.Values.Count(p => p.hp > 0);
var first = room.State.turnOrder[0];
```

`Keys` and `Values` are live typed views, and `ContainsKey` checks for an entry without reading it. Adding or removing an entry while enumerating throws an `InvalidOperationException`. The old `map.items` member still reads and writes the map but is marked obsolete. An `int` key on it is a position, as before.

## SDK API

Navigate to the [ Client SDK](https://docs.colyseus.io/sdk.md) for API Reference, and select the **C# (Unity)** tab.

### State Schema Codegen

For compiled languages like C#, you need to generate client-side schema classes that match your server's state structure. Run the following command from your server directory:

```sh filename="Terminal"
npx schema-codegen src/rooms/schema/* --csharp --output ../Assets/Scripts/States/
```

The generated classes compile as they are, inside any namespace. `number`, `float32` and `float64` fields are `double`, as the server holds them in memory, so client-side prediction doesn't round between ticks. The wire can still narrow a fractional `number` to float32 precision. Cast where Unity wants a `float`: `new Vector3((float)p.x, 0, (float)p.z)`. Collections start as empty instances, and `.default()` values carry over. Fields declared with `.noSync()` are left out, since they take no field index on the wire. `t.angle()` and `t.quantized()` bounds held in a `const` resolve, including through re-exports.

> **Note:**
>
> See the full [State Schema Codegen documentation](https://docs.colyseus.io/state/callbacks.md#frontend-schema-generation) for more options and details.

### DynamicSchema (Skip Code Generation)

If you want to skip the code generation step entirely, you can use `DynamicSchema` instead of generated schema classes. `DynamicSchema` builds its type metadata at runtime from the server handshake, so no generated files are needed.

```csharp filename="NetworkManager.cs"
using UnityEngine;
using Colyseus;
using Colyseus.Schema;

public class NetworkManager : MonoBehaviour
{
    Client client;
    Room<DynamicSchema> room;

    async void Start()
    {
        client = new Client("ws://localhost:2567");

        room = await client.JoinOrCreate<DynamicSchema>("my_room");
        Debug.Log("Joined room: " + room.Id);

        // collections are null until the first full state sync
        await room.WaitForFirstState();

        // Access state fields dynamically
        var players = room.State.Get<MapSchema<DynamicSchema>>("players");
        var self = players[room.SessionId];
        var hp = self.Get<int>("hp");

        // Callbacks use string-based property names instead of expressions
        var callbacks = Callbacks.Get(room);

        callbacks.Listen<string>("currentTurn", (currentValue, previousValue) => {
            Debug.Log($"Turn changed: {previousValue} -> {currentValue}");
        });

        callbacks.OnAdd<DynamicSchema>("players", (sessionId, player) => {
            Debug.Log($"Player joined: {sessionId}");

            // Access nested collections
            var items = player.Get<ArraySchema<DynamicSchema>>("items");
        });

        callbacks.OnRemove<DynamicSchema>("players", (sessionId, player) => {
            Debug.Log($"Player left: {sessionId}");
        });
    }

    async void OnDestroy()
    {
        if (room != null) await room.Leave();
    }
}
```

> **Warning:**
>
> `DynamicSchema` trades compile-time type safety for convenience. You won't get IDE autocomplete on state fields, and type errors will only surface at runtime. For production projects, [Schema Codegen](#state-schema-codegen) is recommended.

### Message Types Codegen

The same `schema-codegen` command also generates C# classes for any TypeScript interface containing `"Message"` in its name. These classes let you use strongly-typed message objects on the frontend.

For example, given the following server-side code:

```ts filename="src/rooms/MyRoom.ts"
interface MoveMessage {
  x: number;
  y: number;
}

// ...

messages = {
  move: (client: Client, message: MoveMessage) => {
    // handle move
  }
}
```

Running the codegen command will automatically generate a matching C# class:

```csharp filename="Generated C# output"
public class MoveMessage {
    public double x;
    public double y;
}
```

You can then use these classes when sending and receiving messages on the Unity client:

```csharp filename="Sending a message to the server"
room.Send("move", new MoveMessage() { x = 1.0, y = 2.0 });
```

The same applies to messages sent from the server to the client. For example, given a server-side interface:

```ts filename="src/rooms/MyRoom.ts"
interface EventMessage {
  type: string;
  data: string;
}

// ...

onJoin(client: Client) {
  client.send("event", { type: "welcome", data: "Hello!" } as EventMessage);
}
```

You can listen for it on the Unity client with the generated type:

```csharp filename="Receiving a message from the server"
room.OnMessage<EventMessage>("event", (message) => {
    Debug.Log(message.type);
    Debug.Log(message.data);
});
```

## Debugging

### Editor Debug Panel (experimental)

The editor debug panel lets you inspect the room state and messages in real-time during development. You can also simulate high latency, connection drops, and more.

You can enable the Editor Debug Panel at **Window → Colyseus → Room Inspector**

![Editor Debug Panel](https://docs.colyseus.io/getting-started/unity-sdk-debug.png)

### Breakpoints

If you set a breakpoint while the WebSocket connection is open, the connection is closed automatically after 3 seconds of inactivity. To prevent the WebSocket connection from dropping, use `pingInterval: 0` during development:

```ts filename="app.config.ts"
import { defineServer } from "colyseus";
import { WebSocketTransport } from "@colyseus/ws-transport";

const server = defineServer({
    // ...
    transport: new WebSocketTransport({
        pingInterval: 0, // <--- HERE
    }),
    // ...
});
```

Make sure to have a `pingInterval` higher than `0` on production. The default `pingInterval` value is `3000`.

---
Source: https://docs.colyseus.io/getting-started/unity


# WeChat (JavaScript/TypeScript SDK)

WeChat is a popular messaging and social media platform in China, and it provides a rich set of APIs for building mini-programs and games. Colyseus can be integrated with WeChat to create real-time multiplayer experiences.

As the WeChat JavaScript runtime is not fully compatible with the browser, you will need to use the following polyfills to ensure compatibility.

> **Warning:**
>
> Feedback? Join the discussion on GitHub: https://github.com/colyseus/colyseus.js/pull/158

> **Note:**
>
> The [JavaScript / TypeScript SDK](https://docs.colyseus.io/getting-started/typescript.md) is compatible with WeChat after applying the necessary polyfills and monkey-patches.

### `URL` Polyfill

WeChat does not provide the [`URL` standard](https://url.spec.whatwg.org/), so you need to install a polyfill to use it.

**Install polyfill via NPM**

If you are using a build system, you can install the `url-polyfill` package:

```sh npm2yarn
npm install --save url-polyfill
```

        And import it in your entry file:

```javascript
require('url-polyfill');
```

**Copy & paste manually**

If you are not using a build system, you can manually copy and paste the polyfill code from the [url-polyfill repository](https://github.com/lifaon74/url-polyfill/blob/master/url-polyfill.js).

### WebSocket monkey-patch

Users have reported that the WeChat JavaScript runtime does not support sending `Uint8Array` or `Array` data types directly through WebSocket. To work around this, you can monkey-patch the `WebSocket.send` method to convert these data types to a format that WeChat can handle.

```typescript
const WebSocket_send = WebSocket.prototype.send;
WebSocket.prototype.send = function(data) {
    if (data instanceof Uint8Array) {
        WebSocket_send.call(this, data.slice().buffer);
    } else if (Array.isArray(data)){
        WebSocket_send.call(this, (new Uint8Array(data)).buffer);
    } else {
        WebSocket_send.call(this, data);
    }
}
```

## Next Steps

- [JavaScript / TypeScript SDK](https://docs.colyseus.io/getting-started/typescript.md) - Full SDK setup guide
- [Client SDK API Reference](https://docs.colyseus.io/sdk.md) - Full API documentation for all methods, events, and room operations
- [State Synchronization](https://docs.colyseus.io/state.md) - Understanding Schema definitions

---
Source: https://docs.colyseus.io/getting-started/wechat


# Learn Multiplayer Game Development with Colyseus

Tutorials that build a multiplayer game step by step, plus ready-to-run examples for your engine. Further down, open-source demos where one authoritative server drives clients across more than a dozen engines.

- [Getting Started](https://docs.colyseus.io/getting-started.md)
- [Tutorials](https://docs.colyseus.io/learn/tutorial.md)
- [Examples](https://docs.colyseus.io/learn/examples.md)

## Premium Demos

{premiumDemos.length} complete prototypes you can play right now in your browser. Each runs the
whole stack at once: authoritative server, client prediction, smoothed remotes
and lag compensation.

We're actively expanding the set, and adding engine ports to it: Air Hockey
already ships Godot and Unity clients alongside its Three.js build.

## Open-Source Demos

Every one of these is MIT-licensed and free to clone. Each runs from a single authoritative server with multiple client implementations, one per game engine. Read the source to see exactly how each SDK connects, synchronizes state, and handles real-time gameplay with Colyseus.

Unity, Godot, Defold, GameMaker and Haxe have a client in all three. Whichever
you work in, there are three different projects to read in it.

### Prediction Playground

A tour rather than a game: twelve small labs, each isolating one
[netcode](https://docs.colyseus.io/netcode.md) technique. Reconciliation, the interpolation modes, dead
reckoning, lag compensation, optimistic events, predicted spawns. Every lab has
a live latency slider and shows the exact SDK-facing code it runs.

![The opening split screen: the same entity in the same room at 200 ms of injected latency, raw server echo above, client prediction below](https://docs.colyseus.io/demos/prediction/hero.webp)

All twelve labs run on one shared server, so each client below is the same lab
logic ported to a different SDK.

- **Web (TypeScript)** (Web): [Play](https://prediction-colyseus.vercel.app/), [Source](https://github.com/colyseus/prediction-playground/tree/main/src/client)
- **Unity** (Windows, macOS, Linux, WebGL, iOS, Android): [Source](https://github.com/colyseus/prediction-playground/tree/main/clients/unity-app)
- **Godot (GDScript)** (Windows, macOS, Linux, HTML5): [Source](https://github.com/colyseus/prediction-playground/tree/main/clients/godot-gd-app)
- **Godot (C#)** (Windows, macOS, Linux): [Source](https://github.com/colyseus/prediction-playground/tree/main/clients/godot-app)
- **Defold** (Windows, macOS, Linux, HTML5, iOS, Android): [Source](https://github.com/colyseus/prediction-playground/tree/main/clients/defold-app)
- **GameMaker** (Windows, macOS, Linux, HTML5): [Source](https://github.com/colyseus/prediction-playground/tree/main/clients/gamemaker-app)
- **Haxe + Heaps** (Native (HL/C)): [Source](https://github.com/colyseus/prediction-playground/tree/main/clients/haxe-app)
- **C + raylib** (Windows, macOS, Linux, Web (Emscripten)): [Source](https://github.com/colyseus/prediction-playground/tree/main/clients/native-app)
- **Flutter** (macOS): [Source](https://github.com/colyseus/prediction-playground/tree/main/clients/flutter-app)
- **Swift** (macOS (SpriteKit)): [Source](https://github.com/colyseus/prediction-playground/tree/main/clients/swift-app)

![Lab 06: lag compensation](https://docs.colyseus.io/demos/prediction/lab-06-lagcomp.webp)
***06 · Lag Compensation**: the server rewinds to what you saw, so aiming at a moving target lands.*

![Lab 10: composite world](https://docs.colyseus.io/demos/prediction/lab-10-hockey.webp)
***10 · Composite World**: paddle and puck both predicted; the dashed ghost is the server trailing by one round trip.*

### Realtime Tanks Multiplayer

A real-time arena shooter: drive, aim and fire against everyone else in the
room, with health pickups and a live leaderboard. Nine clients, one server:
every row below joins the *same* match.

![Realtime Tanks running in the browser on PlayCanvas](https://docs.colyseus.io/demos/tanks/web-playcanvas.webp)

- **PlayCanvas** (Web): [Play](https://colyseus.io/realtime-tanks-demo/web-playcanvas/), [Source](https://github.com/colyseus/realtime-tanks-demo/tree/master/web-playcanvas)
- **GameMaker** (Windows, macOS, Linux, HTML5): [Play](https://colyseus.io/realtime-tanks-demo/gamemaker/), [Source](https://github.com/colyseus/realtime-tanks-demo/tree/master/gamemaker)
- **Godot** (Windows, macOS, Linux, HTML5, iOS, Android): [Play](https://colyseus.io/realtime-tanks-demo/godot/), [Source](https://github.com/colyseus/realtime-tanks-demo/tree/master/godot)
- **Defold** (Windows, macOS, Linux, HTML5, iOS, Android): [Play](https://colyseus.io/realtime-tanks-demo/defold/), [Source](https://github.com/colyseus/realtime-tanks-demo/tree/master/defold)
- **Haxe + Heaps** (Web, Native (HL/C)): [Play](https://colyseus.io/realtime-tanks-demo/haxe/), [Source](https://github.com/colyseus/realtime-tanks-demo/tree/master/haxe)
- **Unity** (Windows, macOS, Linux, WebGL, iOS, Android): [Play](https://colyseus.io/realtime-tanks-demo/unity/), [Source](https://github.com/colyseus/realtime-tanks-demo/tree/master/unity)
- **Three.js** (Web): [Play](https://colyseus.io/realtime-tanks-demo/web-threejs/), [Source](https://github.com/colyseus/realtime-tanks-demo/tree/master/web-threejs)
- **Construct 3** (Web): [Play](https://colyseus.io/realtime-tanks-demo/construct3/), [Source](https://github.com/colyseus/realtime-tanks-demo/tree/master/construct3)
- **MonoGame** (Windows, macOS, Linux): [Source](https://github.com/colyseus/realtime-tanks-demo/tree/master/monogame)

### Turn-based "UNO" Card Game

A four-player game of UNO: turn order, draw and discard piles, and bots to
fill the empty seats. Six clients, one server: every row below sits at the
*same* table.

![Turn-based UNO running in the browser on React + React Three Fiber](https://docs.colyseus.io/demos/uno/web-react.webp)

- **React + R3F** (Web): [Source](https://github.com/colyseus/turnbased-cards-demo/tree/main/web-react)
- **GameMaker** (Windows, macOS, Linux, HTML5): [Source](https://github.com/colyseus/turnbased-cards-demo/tree/main/gamemaker)
- **Godot** (Windows, macOS, Linux, HTML5, iOS, Android): [Source](https://github.com/colyseus/turnbased-cards-demo/tree/main/godot)
- **Defold** (Windows, macOS, Linux, HTML5, iOS, Android): [Source](https://github.com/colyseus/turnbased-cards-demo/tree/main/defold)
- **Haxe + Heaps** (Web, Native (HL/C)): [Source](https://github.com/colyseus/turnbased-cards-demo/tree/main/haxe)
- **Unity** (Windows, macOS, Linux, WebGL, iOS, Android): [Source](https://github.com/colyseus/turnbased-cards-demo/tree/main/unity)

## Framework Overview Talk

Watch Endel Dreyer's talk at JS GameDev Summit 2022, organized by [GitNation](https://gitnation.org/). The talk covers how Colyseus handles authoritative game state, client synchronization, and room-based matchmaking.

[Video](https://www.youtube.com/embed/KnN6nRtfL44?start=260)

## Going Further

Built your first room? The [Netcode section](https://docs.colyseus.io/netcode.md) covers the prediction stack: authoritative input, client-side prediction, and lag compensation. These techniques are the built-in version of what the [tutorials](https://docs.colyseus.io/learn/tutorial.md) build by hand.

---
Source: https://docs.colyseus.io/learn


# Examples

Explore ready-to-use example projects to help you get started with Colyseus. Browse the sidebar to find examples organized by game engine or framework. The majority of these examples are MIT licensed, so feel free to use them as a starting point for your own projects.

## Backend-only Examples

- [Basic Usage Examples](https://github.com/colyseus/colyseus-examples)

- [Authentication w/ Firebase](https://github.com/colyseus/demo-firebase-authentication)

- [`"Push To Talk" Example`](https://github.com/colyseus/demo-push-to-talk)

- [Messaging w/ Protocol Buffers](https://github.com/endel/colyseus-0.15-protocol-buffers)

---

See [Community → Games](https://docs.colyseus.io/community.md#games) for more games developed by the community.

---
Source: https://docs.colyseus.io/learn/examples


# Babylon.js Examples

> **Warning:**
>
> Submit your own examples! Click "Edit this page" on the sidebar and create a pull-request..

| Preview | Name + Description |
| --- | --- |
| ![MMO Engine](https://docs.colyseus.io/examples/babylonjs/alathon-mmo-engine-oss.webp) | **MMO Engine** - A very WIP "engine" for an MMO [GitHub →](https://github.com/alathon/mmo-engine-oss) |
| ![T5C - The 5th Continent](https://docs.colyseus.io/community/games/orion3dgames-t5c.webp) | **T5C - The 5th Continent** - A multiplayer RPG game [GitHub →](https://github.com/orion3dgames/t5c) |
| ![Bomberman Mayhem](https://docs.colyseus.io/community/games/orion3dgames-bomberman-mayhem.webp) | **Bomberman Mayhem** - A multiplayer Bomberman-style game [GitHub →](https://github.com/orion3dgames/bomberman-mayhem) |
| ![Hide and Seek](https://docs.colyseus.io/examples/babylonjs/hide-and-seek/title-screenshot.png) | **Hide and Seek** - Demonstration project using Babylon.js Editor and Colyseus [GitHub →](https://github.com/colyseus/babylonjs-hide-and-seek) |
| ![Barebones](https://docs.colyseus.io/tutorial/babylonjs/preview.png) | **Barebones** - Barebones example using Babylon.js and Colyseus - [Frontend project →](https://github.com/colyseus/tutorial-babylonjs-client/) - [Backend project →](https://github.com/colyseus/tutorial-babylonjs-server/) - [ Tutorial](https://docs.colyseus.io/learn/tutorial/babylonjs/intro.md) |

---
Source: https://docs.colyseus.io/learn/examples/babylonjs


# Decentraland Examples

> **Warning:**
>
> Submit your own examples! Click "Edit this page" on the sidebar and create a pull-request..

| Preview | Name + Description |
| --- | --- |
| ![SDK6 + SDK7 Scene](https://docs.colyseus.io/examples/decentraland/colyseus-decentraland.png) | **SDK6 + SDK7 Scene** - Colyseus + Decentraland demonstration [GitHub →](https://github.com/colyseus/decentraland) |
| ![In-world Browser](https://docs.colyseus.io/examples/decentraland/pabloes-decentraland-browser.png) | **In-world Browser** - A clickable browsers prototype to navigate the web inside Decentraland [GitHub →](https://github.com/pabloes/decentraland-browser) |

---
Source: https://docs.colyseus.io/learn/examples/decentraland


# Defold Engine Examples

> **Warning:**
>
> Submit your own examples! Click "Edit this page" on the sidebar and create a pull-request..

| Preview | Name + Description |
| --- | --- |
| ![Multiplayer Platformer](https://docs.colyseus.io/examples/defold/platformer.webp) | **Multiplayer Platformer** - Colyseus 0.18: 3D platformer with client-side physics and predicted coin pickups, on a server authoritative over rounds and falling platforms. - [Play →](https://colyseus.io/defold-platformer-game/) - [GitHub →](https://github.com/colyseus/defold-platformer-game) |
| ![Tic-Tac-Toe](https://docs.colyseus.io/examples/pixijs/tic-tac-toe.webp) | **Tic-Tac-Toe** - Colyseus 0.16: Turn-based Multiplayer Example [GitHub →](https://github.com/colyseus/demo-tic-tac-toe/tree/master/defold) |
| ![Realtime Multiplayer Example preview](https://cdn.jsdelivr.net/gh/paweljarosz/defold-realtime-colyseus@master/media/example.gif) | **Realtime Multiplayer Example** - Defold Realtime Multiplayer example using Colyseus [GitHub →](https://github.com/paweljarosz/defold-realtime-colyseus) |
| ![Card Game Template](https://docs.colyseus.io/examples/defold/sominator.jpg) | **Card Game Template** - 2D multiplayer card game templates in Unity, Phaser, Defold, and Godot, using Colyseus for the server backend. [GitHub →](https://github.com/sominator/colyseus-2d-multiplayer-card-game-templates) |

---
Source: https://docs.colyseus.io/learn/examples/defold


# Discord Activity Examples

> **Warning:**
>
> Submit your own examples! Click "Edit this page" on the sidebar and create a pull-request..

| Preview | Name + Description |
| --- | --- |
| ![Multiplayer Discord Activity](https://docs.colyseus.io/examples/discord/template.gif) | **Multiplayer Discord Activity** - Template: Multiplayer Discord Activity with Colyseus + PixiJS (Discord Embedded App SDK) [GitHub →](https://github.com/colyseus/discord-activity) |
| ![Phaser + Colyseus Template](https://docs.colyseus.io/examples/discord/phaser-discord.webp) | **Phaser + Colyseus Template** - A quickstart Phaser template for creating multiplayer Discord Activities [GitHub →](https://github.com/phaserjs/discord-multiplayer-template) |

## More Discord Activities (Open source)

- Phaser Discord Multiplayer Games Template - [phaserjs/discord-multiplayer-template](https://github.com/phaserjs/discord-multiplayer-template)
- Air Party - [tejaboy/airparty_discord](https://github.com/tejaboy/airparty_discord) ([YouTube Tutorial](https://www.youtube.com/watch?v=k6A2VUbIQio))
- Unity WebGL Multiplayer Tutorial - [DotSketched/Discord-Activity-WebGL-Tutorial](https://github.com/DotSketched/Discord-Activity-WebGL-Tutorial) ([YouTube Tutorial](https://www.youtube.com/watch?v=ff2AXPc_msc))
- Chess-like tactical fps turn based combat game prototype - [RaiaN/tactochess](https://github.com/RaiaN/tactochess)
- TypeScript + Colyseus + React - [Wave-Play/robo.js](https://github.com/Wave-Play/robo.js/tree/main/templates/activity-ts-colyseus-react)
- Discord Typing Race - [linkai101/keyboard-derby](https://github.com/linkai101/keyboard-derby/)

> Made a cool Discord Activity? Make a pull-request and contribute to the list!

---
Source: https://docs.colyseus.io/learn/examples/discord


# KAPLAY Examples

> **Warning:**
>
> Submit your own examples! Click "Edit this page" on the sidebar and create a pull-request..

| Preview | Name + Description |
| --- | --- |
| ![KAPLAY + Colyseus](https://docs.colyseus.io/examples/kaplay/colyseus-kaplay.png) | **KAPLAY + Colyseus** - KAPLAY + Colyseus Sample App [GitHub →](https://github.com/colyseus/kaplay) |
| ![Air Hockey Multiplayer](https://docs.colyseus.io/examples/kaplay/air-hockey.webp) | **Air Hockey Multiplayer** - Example game made by @imaginarny [GitHub →](https://github.com/imaginarny/kaplay-colyseus) |

---
Source: https://docs.colyseus.io/learn/examples/kaplay


# Phaser

> **Warning:**
>
> Submit your own examples! Click "Edit this page" on the sidebar and create a pull-request..

| Preview | Name + Description |
| --- | --- |
| ![TypeScript Online Game Template](https://cdn.jsdelivr.net/gh/ASteinheiser/ts-online-game-template@main/images/system-design.png) | **TypeScript Online Game Template** - A template for creating real-time, online games using TypeScript! Quickly create mmo-style games using React + Phaser for rendering, Colyseus for websockets and Electron for native builds! [GitHub →](https://github.com/asteinheiser/ts-online-game-template) |
| ![Pokemon Auto Chess](https://docs.colyseus.io/community/games/keldaanCommunity-pokemonAutoChess.webp) | **Pokemon Auto Chess** - An auto-battler game made by fans for fans. Open source, non profit. All rights to the Pokemon Company [GitHub →](https://github.com/keldaanCommunity/pokemonAutoChess) |
| ![Reldens](https://docs.colyseus.io/community/games/damian-pastorini-reldens.webp) | **Reldens** - Open source HTML5 MMORPG platform [GitHub →](https://github.com/damian-pastorini/reldens) |

---
Source: https://docs.colyseus.io/learn/examples/phaser


# PixiJS Examples

> **Warning:**
>
> Submit your own examples! Click "Edit this page" on the sidebar and create a pull-request..

| Preview | Name + Description |
| --- | --- |
| ![TOSIOS](https://docs.colyseus.io/community/games/halftheopposite-tosios.jpg) | **TOSIOS** - The Open-Source IO Shooter - A multiplayer top-down shooter [GitHub →](https://github.com/halftheopposite/TOSIOS/) |
| ![Agar.io-style Demonstration Project using PixiJS and Colyseus](https://docs.colyseus.io/examples/pixijs/agario.webp) | **Boilerplate** - Agar.io-style Demonstration Project using PixiJS and Colyseus [GitHub →](https://github.com/endel/colyseus-pixijs-boilerplate) |
| ![Tic-Tac-Toe](https://docs.colyseus.io/examples/pixijs/tic-tac-toe.webp) | **Tic-Tac-Toe** - Turn-based Multiplayer Example [GitHub →](https://github.com/endel/colyseus-tic-tac-toe) |

---
Source: https://docs.colyseus.io/learn/examples/pixijs


# Three.js Examples

> **Warning:**
>
> Submit your own examples! Click "Edit this page" on the sidebar and create a pull-request..

| Preview | Name + Description |
| --- | --- |
| ![Mazmorra](https://repository-images.githubusercontent.com/163449522/e8b6a300-cb5a-11ea-860f-56e5e9974f11) | **Mazmorra** - A multiplayer dungeon crawler game [GitHub →](https://github.com/endel/mazmorra) |

---
Source: https://docs.colyseus.io/learn/examples/threejs


# Tutorials

**JavaScript**

- [Phaser](https://docs.colyseus.io/learn/tutorial/phaser.md)
- [PlayCanvas](https://docs.colyseus.io/learn/tutorial/playcanvas.md)
- [Babylon.js](https://docs.colyseus.io/learn/tutorial/babylonjs/intro.md)
- [KAPLAY](https://kaplayjs.com/docs/guides/how-to-make-a-multiplayer-game-with-colyseus-and-kaplay/)
- [Cocos Creator](https://docs.colyseus.io/learn/tutorial/cocos/mmo.md)

**Unity**

- [MMO](https://docs.colyseus.io/learn/tutorial/unity/mmo.md)
- [Shooting Gallery](https://docs.colyseus.io/learn/tutorial/unity/shooting-gallery.md)
- [Starboss](https://docs.colyseus.io/learn/tutorial/unity/starboss.md)
- [Turn-based Tanks](https://docs.colyseus.io/learn/tutorial/unity/turn-based-tanks.md)

---
Source: https://docs.colyseus.io/learn/tutorial


# Hide and Seek Tech Demo

> **Warning:**
>
> This demo uses an older version of Colyseus.

## Requirements
- Node.js v14.0 or higher
- Colyseus 0.14.20
- Colyseus Client SDK 0.14.13
- Babylon.js Editor 4.4.0 or higher

## Introduction
The purpose of this technical demo is to show how to use Colyseus with the Babylon.js Editor. The following documentation covers installing and using the Colyseus SDK, as well as locally running a Colyseus server. The demo is designed to work with Colyseus version 0.14.20 and [Babylon.js Editor version 4.4.0](http://editor.babylonjs.com/).
This demo, "Hide and Seek", is a simple game where players are randomly assigned the role of Hider (ghost) or the lone Seeker (pumpkin head). In order for the Hiders to win they need to evade the Seeker until time runs out.

**[Download Demo](https://github.com/colyseus/babylonjs-hide-and-seek/archive/master.zip)** ([View source code](https://github.com/colyseus/babylonjs-hide-and-seek/))

![Hide and Seek Demo](https://docs.colyseus.io/examples/babylonjs/hide-and-seek/title-screenshot.png)

## Getting Started

### Colyseus SDK/Framework
You need to install and launch the server from the **provided Server directory** for this demo to function properly.
To run the demonstration server locally, run the following commands in your terminal:

```
cd Server
npm install
npm start
```

> **Note:**
>
> - Install the server before you attempt to run or open the project in the editor, or compilation errors will result. The errors happen because client code references class types from the server code, for development convenience.
> - When opening the demo in the Babylon.js Editor some `.js` files will be generated in the **Server** folder alongside their original `.ts` source files. When launching the server locally (via `npm start`) those `.js` files are removed to prevent runtime issues.

#### Colyseus Client SDK
You do not need to install the Colyseus client SDK manually for this demo. The Babylon.js Editor installs it automatically, because it is listed as a dependency in the `package.json` of the project workspace. If needed, manual instructions on how to install the Colyseus client SDK in the Babylon.js Editor can be found [here](https://docs.colyseus.io/getting-started/typescript.md).

#### Colyseus Server Settings
All server settings are defined in `.env` files located in the Babylon.js Editor workspace here:

![Server Settings](https://docs.colyseus.io/examples/babylonjs/hide-and-seek/server-settings.png)

If you are running a local server, the `local` settings should be sufficient. However if you wish to host a server you’ll need to change the **Colyseus Server Address** and **Colyseus Server Port** values accordingly. For example the remote settings used to connect to the live demo on Arena are included.
By default the editor will load server settings from the `local.env` file.

## Playing the Demo
![Editor](https://docs.colyseus.io/examples/babylonjs/hide-and-seek/editor.png)

There is only one scene and the editor should load it automatically when opening the workspace. You can click the `Run` button at the top left of the editor (highlighted in green) and that will open a player window. To create or join an existing room you can simply click the `Quick Play` button. An overlay displaying `Joining...` should appear and if successful it will disappear revealing the lobby UI.
By default a minimum of three players is required to start a match, but you can adjust that, as noted in the section below. If necessary you can open multiple client instances to satisfy the player requirement.

> **Note:**
>
> - For better performance, try running the client in your browser rather than the editor's integrated browser (right click the "Run" button)
>
> ![Run](https://docs.colyseus.io/examples/babylonjs/hide-and-seek/run.png)
>
> - If you cannot reach the lobby UI confirm your local server is working properly and check the editor logs for errors.

![Gameplay](https://docs.colyseus.io/examples/babylonjs/hide-and-seek/gameplay.png)

### Controls
Player movement: W, A, S, & D keys.

### Demo Gameplay Mechanics
- All players start near the center of the arena in front of the mausoleum
- A round of play lasts 60 seconds. Time left in the round is viewable in the top left corner of the screen

#### Seeker:
- The Seeker wins if they find all the Hiders within the countdown
- The Seeker cannot directly see the Hiders until they are captured
- There are various traps spread out over the arena that betray a Hider’s position to the Seeker
    - Mud puddles will cause you to leave a trail of muddy footprints for a short period of time
    - Spirits may be disturbed from their abodes
    - Bats may be startled from their resting places

#### Hider:
- Hiders have 3 seconds to scatter before the Seeker is able to seek
- Hiders win if one or more stay hidden at the end of the round
- A Hider is captured when they enter the Seeker's FOV, or when they get within about a unit of the Seeker in any direction
    - Current FOV is 60 degrees out for 7 units
- When captured a Hider cannot move
    - Denoted by a green glow with chains at the foot of the Hider
- A Hider that has been captured can be rescued by another Hider only one time before being permanently caught
    - To rescue a captured Hider a fellow Hider just needs to stand right next to them for one second

## Adjusting the Demo
As you play around with this demo, you may want to make some adjustments to better familiarize yourself with what is happening. Below, you’ll learn how to make these minor adjustments. Most adjustable values are defined in `gameConfig.ts` in the **Server** folder at `Server/src/gameConfig.ts`

![Server Settings](https://docs.colyseus.io/examples/babylonjs/hide-and-seek/config.png)

### Player Requirements
`minPlayers` represents the minimum number of players required to start a round of play. `maxPlayers` represents the max number of players allowed to join a room. There is a max of 8 players permitted per room for the demo. You can reduce the max player count, but increasing it past 8 will cause issues.

### Player Movement
There are two values that affect player movement speed. The base player speed is defined by `playerMovementSpeed` and that applies to both the Hiders and the Seeker. The Seeker gets a speed boost defined by `seekerMovementBoost` and is set to `1.2` by default. Using that value the speed boost means the Seeker gets to move 1.2 as fast (or 20% faster) than the Hiders.

### Seeker's Vision
The Seeker's ability to capture Hiders is based on it's vision defined by it's field of view(FOV) and viewing distance. Both values are defined in the config as `seekerFOV` and `seekerCheckDistance` respectively.

### Rescuing Captured Hiders
There are two values involved with rescuing Hiders. `rescueDistance` controls the max distance another Hider can be in order to rescue their friend. `rescueTime` is the time, in milliseconds, it takes to rescue a Hider.

### Various Countdowns
There are various countdowns that can be adjusted; all are denoted with a `Countdown` suffix and affect the time between game states. All values are assumed to be in milliseconds:

![Countdowns](https://docs.colyseus.io/examples/babylonjs/hide-and-seek/countdowns.png)

- `preRoundCountdown`: time spent in lobby before the room locks and a game begins; begins when the minimum number of players have joined.
- `initializedCountdown`: a brief pause after the server initializes the room for a round of play. This pause gives clients time to receive updated schemas and handle spawning before the prologue state.
- `prologueCountdown`: the prologue countdown is the total time before the Seeker is allow to pursue Hiders. The prologue countdown is partnered with the scatter countdown. The time Hiders have to read their role is `prologueCountdown - scatterCountdown`
- `scatterCountdown`: the time that Hiders have to scatter before the Seeker is allowed to pursue.
- `huntCountdown`: the length of a round of play; the time the Seeker has to hunt for the Hiders.
- `gameOverCountdown`: the time spent on the post game lobby UI.

---
Source: https://docs.colyseus.io/learn/tutorial/babylonjs/hide-and-seek


# Babylon.js: Real Time Multiplayer Tutorial

![](https://docs.colyseus.io/tutorial/babylonjs/gameplay.png)

## On this tutorial you will learn how to:

- Set-up your first authoritative server with Colyseus
- Synchronize shared state data between server and client
- Exchange messages between client and server
- Matchmake clients into rooms

### Full source code

- [ Babylon.js Project (Frontend)](https://github.com/colyseus/tutorial-babylonjs-client/)
- [ Colyseus Node.js/TypeScrippt Project (Backend)](https://github.com/colyseus/tutorial-babylonjs-server/)

## Before you start

### Prior Knowledge Expected

- Basic Babylon.js knowledge ([See Getting Started with Babylon.js](https://doc.babylonjs.com/start))
- Basic knowledge of Node.js ([See Introduction to Node.js](https://nodejs.dev/learn/))

## Creating the server

We will be making a basic server, hosted locally on your computer for keeping player states. Changes will be synchronized with clients accordingly.

To create a fresh new Colyseus server, run the following from your command-line:

```sh filename="Terminal"
npm create colyseus-app@latest ./babylonjs-multiplayer-server
```

Let's make sure you can run the server locally now, by running `npm start`:

```sh filename="Terminal"
cd babylonjs-multiplayer-server
npm start
```

If successful, the output should look like this in your command-line:

```txt
✅ development.env loaded.
✅ Express initialized
⚔️ Listening on http://localhost:2567
```

## Including the Colyseus JavaScript SDK

For simplicity's sake, the examples on this guide are using the [Babylon.js Playground](https://doc.babylonjs.com/toolsAndResources/tools/playground). Although the full source-code available for download uses [NPM + Webpack](https://doc.babylonjs.com/divingDeeper/developWithBjs/npmSupport).

In the Playground, we inject the Colyseus JavaScript SDK manually through a `<script>` tag created via code. This technique is described in [_"Using External Assets In The Playground"_ → _"Javascript files"_](https://doc.babylonjs.com/toolsAndResources/tools/playground/externalPGAssets#javascript-files).

> **Warning:**
>
> This approach is not recommended in a real-world scenario!

```typescript
// Load Colyseus SDK (asynchronously)
var scriptUrl = "https://unpkg.com/@colyseus/sdk/dist/colyseus.js";
var externalScript = document.createElement("script");
externalScript.src = scriptUrl;
document.head.appendChild(externalScript);
```

In a real-world scenario, please follow the [official Colyseus documentation](https://docs.colyseus.io/getting-started/typescript.md) on how to include the Colyseus JavaScript SDK.

> [Playground Link](https://playground.babylonjs.com/#ZRZS5F#1)
> ![](https://docs.colyseus.io/tutorial/babylonjs/playground-load-sdk.png)

## Establishing a Client-Server Connection

Now we can instantiate Colyseus `Client` instance and join a game from any script.

```typescript
var createScene = function() {
  // (...)

  //
  // Create the Colyseus Client.
  //
  var colyseusSDK = new Colyseus.Client("http://localhost:2567");

  //
  // Connect with Colyseus server
  //
  colyseusSDK.joinOrCreate("my_room").then(function(room) {
    console.log("Connected to roomId: " + room.roomId);

  }).catch(function(error) {
    console.log("Couldn't connect.");
  });

  // (...)
}
```

> **Note:**
>
> Note that we're using the local `http://localhost:2567` endpoint here. You need to [deploy your server](https://docs.colyseus.io/deployment.md) to the public internet in order to play with others online.

> **Warning:**
>
> If you happen to see `net::ERR_BLOCKED_BY_CLIENT` error in the console, make sure to disable ad-block or shields due to untrusted origin.

When you run your BabylonJS project now, your client establishes a connection with the server. The server then creates the room `my_room` on demand.

Notice that `my_room` is the default room identifier set by the barebones Colyseus server. You can and should change this identifier in the `arena.config.ts` file.

You will be seeing the following message in your server logs, which means a client successfully joined the room!

```txt
19U8WkmoK joined!
```

> [Playground Link](https://playground.babylonjs.com/#3K64VU#2)
> ![](https://docs.colyseus.io/tutorial/babylonjs/playground-room-connection.png)

## Room State and Schema

In Colyseus, we define shared data through its `Schema` structures.

> `Schema` is a special data type from Colyseus that is capable of encoding its changes/mutations _incrementally_. The encoding and decoding process happens internally by the framework and its SDK.

The state synchronization loop looks like this:

1. State changes (mutations) are synchronized automatically from Server → Clients
2. Clients, by attaching callbacks to their local _read-only_ `Schema` structures, can observe for state mutations and react to it.
3. Clients can send arbitrary messages to the server - which decides what to do with it - and may mutate the state (Go back to step **1.**)

---

Let's go back to editing the Server code, and define our Room State in the Server.

We need to handle multiple `Player` instances, and each `Player` will have `x`, `y` and `z` coordinates:

**Schema Builder**

```ts filename="MyRoomState.ts"
import { schema, t } from "@colyseus/schema";

export const Player = schema({
    x: t.number(),
    y: t.number(),
    z: t.number(),
}, "Player");

export const MyRoomState = schema({
    players: t.map(Player),
}, "MyRoomState");
```

**Decorators**

```ts filename="MyRoomState.ts"
import { MapSchema, Schema, type } from "@colyseus/schema";

export class Player extends Schema {
    @type("number") x: number;
    @type("number") y: number;
    @type("number") z: number;
}

export class MyRoomState extends Schema {
    @type({ map: Player }) players = new MapSchema<Player>();
}
```

> **Note:**
>
> See [State Synchronization → Schema Definition](https://docs.colyseus.io/state/schema.md).

Now, still in the backend, let's modify our `onJoin()` method to create a `Player` instance whenever a new connection is established with the room.

```ts filename="MyRoom.ts"
// ...
    onJoin(client: Client, options: any) {
        console.log(client.sessionId, "joined!");

        // create Player instance
        const player = new Player();

        // place Player at a random position
        const FLOOR_SIZE = 500;
        player.x = -(FLOOR_SIZE/2) + (Math.random() * FLOOR_SIZE);
        player.y = -1;
        player.z = -(FLOOR_SIZE/2) + (Math.random() * FLOOR_SIZE);

        // place player in the map of players by its sessionId
        // (client.sessionId is unique per connection!)
        this.state.players.set(client.sessionId, player);
    }
// ...
}
```

Also, when the client disconnects, let's remove the player from the map of players:

```ts filename="MyRoom.ts"
// ...
    onLeave(client: Client, consented: boolean) {
        console.log(client.sessionId, "left!");

        this.state.players.delete(client.sessionId);
    }
// ...
```

The state mutations we've done in the backend **can be observed** in the frontend. We'll do that in the next section.

## Setting up the Scene for Synchronization

For this demo, we need to create two objects in our Scene:

- A Plane, mesh object to represent the floor
- A Sphere, mesh object to represent the players, which we will initiate for each new player joining the room.

### Creating the Plane

Let's create a Plane with size `500`.

```typescript
// Create the ground
var ground = BABYLON.MeshBuilder.CreatePlane("ground", {size: 500}, scene);
ground.position.y = -15;
ground.rotation.x = Math.PI / 2;
```

## Listening for State Changes

Once connected to the room, the frontend can start listening for state changes and build a visual representation of the server's data.

## Adding new players

As per [Room State and Schema](#room-state-and-schema) section, whenever the server accepts a new connection - the `onJoin()` method is creating a new Player instance within the state.

We're going to listen to this event on the frontend now:

```typescript
// (...)

// connect with the room
colyseusSDK.joinOrCreate("my_room").then(function(room) {
  var callbacks = Colyseus.Callbacks.get(room);

  // listen for new players
  callbacks.onAdd("players", (player, sessionId) => {
    //
    // A player has joined!
    //
    console.log("A player has joined! Their unique session id is", sessionId);
  });
});

// (...)
```

When playing the scene, you should see a message in the browser's console whenever a new client joins the room.

For the visual representation, we need to clone the "Player" object. Keep a local reference to each clone, keyed by `sessionId`, so we can operate on them later:

```typescript
// (...)

// we will assign each player visual representation here
// by their `sessionId`
var playerEntities = {};

colyseusSDK.joinOrCreate("my_room").then(function(room) {
  var callbacks = Colyseus.Callbacks.get(room);

  // listen for new players
  callbacks.onAdd("players", function (player, sessionId) {
    // create player Sphere
    var sphere = BABYLON.MeshBuilder.CreateSphere(`player-${sessionId}`, {
        segments: 8,
        diameter: 40
    });

    // set player spawning position
    sphere.position.set(player.x, player.y, player.z);

    // store reference for later
    playerEntities[sessionId] = sphere;
  });
});

// (...)
```

> [Playground Link](https://playground.babylonjs.com/#W613VP#2)
> ![](https://docs.colyseus.io/tutorial/babylonjs/playground-onadd.png)

### The "Current Player"

We can give the current player, color `#ff9900` and other players `grey`, by checking the `sessionId` against the connected `room.sessionId`:

```typescript
// (...)

callbacks.onAdd("players", (player, sessionId) => {
  var isCurrentPlayer = (sessionId === room.sessionId);

  // (...)

  // set material to differentiate CURRENT player and OTHER players
  sphere.material = new BABYLON.StandardMaterial(`player-material-${sessionId}`);

  if (isCurrentPlayer) {
    // highlight current player
    sphere.material.emissiveColor = BABYLON.Color3.FromHexString("#ff9900");

  } else {
    // other players are gray colored
    sphere.material.emissiveColor = BABYLON.Color3.Gray();
  }

  // (...)
});

// (...)
```

### Removing disconnected players

When a player is removed from the state (upon `onLeave()` in the backend), we need to remove their visual representation as well.

```javascript
// ...
callbacks.onRemove("players", function (player, sessionId) {
    playerEntities[sessionId].dispose();
    delete playerEntities[sessionId];
});
// ...
```

> [Playground Link](https://playground.babylonjs.com/#CB3LF6#1)
> ![](https://docs.colyseus.io/tutorial/babylonjs/playground-onadd-onremove.png)

## Moving the players

### Sending the new position to the server

We are going to use the `Scene.onPointerDown` event to determine the exact `Vector3` position the player should move towards. We then send that position as a message to the server.

```typescript
scene.onPointerDown = function (event, pointer) {
  if (event.button == 0) {
    const targetPosition = pointer.pickedPoint.clone();

    // Position adjustments for the current play ground.
    // Prevent spheres from moving all around the screen other than on the ground mesh.
    targetPosition.y = -1;
    if(targetPosition.x > 245) targetPosition.x = 245;
    else if(targetPosition.x < -245) targetPosition.x = -245;
    if(targetPosition.z > 245) targetPosition.z = 245;
    else if(targetPosition.z < -245) targetPosition.z = -245;

    // Send position update to the server
    room.send("updatePosition", {
      x: targetPosition.x,
      y: targetPosition.y,
      z: targetPosition.z,
    });
  }
};
```

### Receiving the message from the server

Whenever the `"updatePosition"` message is received in the server, we're going to mutate the player that sent the message through its `sessionId`.

```ts filename="MyRoom.ts"
// ...
  state = new MyRoomState();

  messages = {
    "updatePosition": (client, data) => {
      const player = this.state.players.get(client.sessionId);
      player.x = data.x;
      player.y = data.y;
      player.z = data.z;
    }
  }
// ...
```

### Updating Player's visual representation

Having the mutation on the server, we can detect it on the frontend via `callbacks.onChange()`, or `callbacks.listen()`.

- `callbacks.onChange(instance)` is triggered **per schema instance**
- `callbacks.listen(instance, prop)` is triggered **per property** change

We are going to use `.onChange()` since we need all the new coordinates at once, no matter if just one has changed individually.

```typescript
// (...)

callbacks.onAdd("players", function (player, sessionId) {
    // (...)
    callbacks.onChange(player, function () {
        playerEntities[sessionId].position.set(player.x, player.y, player.z);
    });

    // Alternative, listening to individual properties:
    // callbacks.listen(player, "x", (newX, prevX) => console.log(newX, prevX));
    // callbacks.listen(player, "y", (newY, prevY) => console.log(newY, prevY));
    // callbacks.listen(player, "z", (newZ, prevZ) => console.log(newZ, prevZ));
});

// (...)
```

> **Note:**
>
> See [Client SDK → State Sync Callbacks](https://docs.colyseus.io/state/callbacks.md)

> [Playground Link](https://playground.babylonjs.com/#JMA5FE#2)
> ![](https://docs.colyseus.io/tutorial/babylonjs/playground.png)

## Interpolating the player's position

To enable position interpolation, we're going to use the [Render Loop](https://doc.babylonjs.com/features/featuresDeepDive/animation/render_frame_animation) and the [`Scalar.Lerp()`](https://doc.babylonjs.com/typedoc/classes/BABYLON.Scalar#Lerp) method.

Instead of updating the player position directly (as in [previous section](#updating-players-visual-representation)), we are going to cache the next position. During the Render Loop, we constantly interpolate each player position towards it:

```typescript
// (...)
var playerNextPosition = {};

callbacks.onAdd("players", function (player, sessionId) {
    // (...)
    playerNextPosition[sessionId] = sphere.position.clone();

    callbacks.onChange(player, function () {
        playerNextPosition[sessionId].set(player.x, player.y, player.z);
    });
});
// (...)
```

And finally, the Render Loop:

```typescript
scene.registerBeforeRender(() => {
    for (let sessionId in playerEntities) {
        var entity = playerEntities[sessionId];
        var targetPosition = playerNextPosition[sessionId];
        entity.position = BABYLON.Vector3.Lerp(entity.position, targetPosition, 0.05);
    }
});
```

> [Playground Link](https://playground.babylonjs.com/#RAG7FE#27)
> ![](https://docs.colyseus.io/tutorial/babylonjs/playground.png)

## Extra: Monitoring Rooms and Connections

Colyseus comes with an optional monitoring panel that can be helpful during the development of your game.

To view the monitor panel from your local server, go to [http://localhost:2567/colyseus](http://localhost:2567/colyseus).

![monitor](https://docs.colyseus.io/tutorial/babylonjs/monitor.png)

You can see and interact with all spawned rooms and active client connections through this panel.

> **Note:**
>
> See [Tools → Monitoring Panel](https://docs.colyseus.io/tools/monitoring.md)

---
Source: https://docs.colyseus.io/learn/tutorial/babylonjs/intro


# MMO Tech Demo

> **Warning:**
>
> This demo uses an older version of Colyseus.

This technical demo shows one method of making a **basic** MMO, including a chat system, player persistence, multiple flowing Colyseus.Rooms and networked interactable objects. Note that this demo **does not** include sharding or other load balancing methods that a production scale MMO would need. This demo is designed to work with Colyseus version 0.14.0 and [Cocos Creator version 3.2.0](cocos-dashboard://download/2d_3.2.0).

**[Download demo](https://github.com/colyseus/cocos-demo-mmo/archive/master.zip)** ([View source code](https://github.com/colyseus/cocos-demo-mmo/))

![Screenshot](https://docs.colyseus.io/tutorial/cocos/mmo/mmoOverview.png)

## Requirements
- Node.js v14.0 or higher
- Colyseus 0.14.0
- Cocos Creator 3.2.0
- MongoDB 4.4.1 or higher

## Getting Started

If you haven't already downloaded the Cocos dashboard you can do so [here](https://download.cocos.com/CocosDashboard/v1.2.0/CocosDashboard-v1.2.0-win-050511.exe).

For instruction on how to install the Colyseus SDK for the Cocos engine please see this [guide](https://docs.colyseus.io/getting-started/cocos.md)

### Launching a local server

You need to install and launch the server from the **provided Server directory** for this demo to function properly. To run the server locally, run the following commands in your terminal:

```
cd Server
npm install
npm start
```

Additionally, this demo uses MongoDB for player persistence. If you wish to run the server locally, you'll have to set up your own local DB or provide your own connection URL. See the "Adjusting the Demo" section.

[See the MongoDB website for details on how to set up a local instance](https://docs.mongodb.com/community/server/install/)

### Colyseus Server Settings

All server settings can be changed via the ColyseusSettings objects located here:

![ScriptableObject](https://docs.colyseus.io/tutorial/cocos/mmo/serverSettings.png)

Two settings objects have been included already. The LocalSettings object connects to a locally hosted game server and is the default object when you first open the project.
If you are running a local server, the default settings should be sufficient. If you wish to host a server, change the **Colyseus Server Address** and **Colyseus Server Port** values accordingly. The DemoSettings object will connect to the live demo server.

To use the `DemoSettings` object, drag and drop its prefab into the `ColyseusSettingsObject` property of the MMO Manager component. You'll find the component in the inspector of the `MMOLoginScene`.

![Screenshot](https://docs.colyseus.io/tutorial/cocos/mmo/changeSettings.png)

## Playing the Demo

Start the player in the scene "MMOLoginScene" located at `assets\Scenes\MMOLoginScene`. If this is your first time, you'll need to create an account. Input your e-mail, password and then login to begin. If you are successful, the client will load the "TowerScene" scene and place a NetworkedEntity in it. At any point you can press the escape key to view the controls, customize your avatar or exit to the main menu. You will be transferred into a different room by walking into the grey cubes that are located on sides of rooms.

### Controls

The controls for this demo are visible in the Escape menu at any time and are as follows:

| Input                            | Description        |
| -------------------------------- | ------------------ |
| Escape                           | Menu               |
| W,A,S,D                          | Movement           |
| Hold Shift                       | Sprint             |
| Q,E                              | Rotate Avatar      |
| Scroll Up/Down                   | Zoom In/Out        |
| Hold and Drag Right Mouse Button | Camera Pivot       |
| `                                | Toggle Chat Window |

## Demo Overview

This demo was designed to show how a user could potentially design and implement an MMO style game using Colyseus. It highlights the following features:

---

### Dynamic Rooms

MMORooms are created and disposed of as needed. When a player enters a grid space, we join a room where it's `progress` value is set to the grid values, as seen in `app.config.ts`:

```javascript
const server = defineServer({
  rooms: {
    lobby_room: defineRoom(MMORoom).filterBy(["progress"]) // Filter room by "progress" (which grid we're wanting to join EX: -1x2)
  }
})
```

As players move throughout the world, they join/leave rooms based off of their position in the world grid. A message is sent from the client to the server stating that the player is trying to update their progress, which we then catch in `MMORoom.ts`:

```javascript
messages = {
    "transitionArea": (client: Client, transitionData: Vector[]) => {
        if (transitionData == null || transitionData.length < 2) {
            logger.error(`*** Grid Change Error! Missing data for grid change! ***`);
            return;
        }
        this.onGridUpdate(client, transitionData[0] as  Vector2, transitionData[1] as  Vector3);
    }
}
```

After determining the new grid position, the client is given a new SeatReservation to consume, joining the correct Colyseus.Room for that position. A similar flow also occurs when Logging in/Signing up (see **Player Persistence** section).

![MapScreenshot](https://docs.colyseus.io/tutorial/cocos/mmo/grid.png)

This image shows the grid map implemented for this demo. The grid spaces contain exits of the four cardinal directions to each other, allowing you to travel from one to the other. For example in grid space `0x0`, you can take the North(green) exit and you will be placed into grid space `0x1`. All other contiguous grid spaces will have exits to each other. Green = North, Red = South, Blue = East, and Yellow = West.

### Chat System

![ChatScreenshot](https://docs.colyseus.io/tutorial/cocos/mmo/chat.png)

An additional Colyseus.Room is used to handle the Chat system: `ChatRoom.ts`. In both the client and the server, anywhere we join or leave an MMORoom we also join or leave a ChatRoom. These ChatRooms are filtered by `roomId` which is the ID of the MMORoom it is connected to.
When a client sends a message, it's added to the ChatRoomState's ChatQueue, triggering a state change on all connected clients. Every new message that comes in receives a `timeStamp` value, after which it will be removed from the queue.

### Player Persistence

> **Note:**
>
> This demo uses a very basic user authentication system to persist unique player accounts.
> **Do NOT treat it as a real world example** of how to implement user authentication.
> **Do NOT use any email and password combination you actually use anywhere else.**

In this demo, unique player accounts are persisted in a database. The account tracks a player's progress (which room they are currently in and which room they were in last), position, coin balance, and more.
A player account is necessary to play this demo. With successful user authentication, a seat reservation for a room is sent back to the client. The session Id of that seat reservation is saved to the player's account entry in the database as a "pendingSessionId". When the client attempts to consume the seat reservation, the room's "onAuth" hook looks up the player account by its "pendingSessionId". If no player account with a matching "pendingSessionId" exists, the client will not be allowed to join the room. However, with a successful player account look up, the "pendingSessionId" will become an "activeSessionId" and the client will join the room.
A player's progress is used to filter rooms during the matchmaking process. For example, a player with progress value "1,1" (grid area coordinates 1x1) will matchmake into an existing room with the same progress value. If no room with that progress value exists, then one shall be created. This way, rooms for each grid coordinate only exist as players are in them. A player's progress is updated as they leave one grid area to move to another via one of the exit doors.

### Interactable Elements

![Interactables](https://docs.colyseus.io/tutorial/cocos/mmo/interactable.png)
Grid spaces may have `Interactables` scattered around them. These are frontend representations of `InteractableState` schema objects that are placed within the editor when we make a new grid space prefab. When a player performs an interaction with one of these objects, the client will send a `objectInteracted` message to the server. If the server is not yet aware of the provided Interactable ID, it creates a new schema reference. The reference is added to the room's schema map and makes its way back to the client. The server will then check if the Client meets the requirements to perform an interaction. If successful, all clients will receive an `objectUsed` message broadcast, along with the interactable's ID and the user who interacted with it. On the client's side, the appropriate `NetworkedEntity` and `Interactable` objects will be told to perform together.
This demo comes with 4 different types of interactables that you can find in the various grid spaces:

-   Button Podium
    -   Gives the interacting user 1 coin per press
-   Coin Op
    -   A small ride that will disable your controls temporarily and bounce your NetworkedEntity around. Costs 1 coin per use
-   Teleporter
    -   A small platform that will teleport a user to it's "exit platform". Costs 1 coin to use

## Adjusting the Demo

As you play around with this demo, you may want to make some adjustments to better familiarize yourself with what is happening. Below, you'll learn how to make these minor adjustments.

### Using your own DB

To point this demo at your own database, provide a different Mongo connection string in the `arena.env` file, located in the `Server` directory. The file currently expects a locally hosted mongo db:

```javascript
DEMO_DATABASE=mongodb://localhost:27017/demo?retryWrites=true&w=majority
```

### Chat Message Life Time

On the frontend, you can change how long a message shows by changing the public `messageShowTime` variable on `ChatManager.ts`. This value is then sent to the server when joining or creating a room in `MMOManager.ts`:

```javascript
private async joinChatRoom() {
    let chatRoom: Colyseus.Room<ChatRoomState> = await this._client.joinOrCreate<ChatRoomState>('chat_room', {
        roomID: this.Room.id,
        messageLifetime: ChatManager.Instance.messageShowTime,
    });

    ChatManager.Instance.setRoom(chatRoom);
}
```

### Adding Your Own Interactables

If you want to add a new interactable to the client, it must inherit from `Interactable.ts`. Check out any of the other Interactables for ideas of what you can do. If you want to override the `serverType` value on you Interactable, you should ALSO add a case for your new `serverType` on the server in `interactableObjectFactory.ts`:

```javascript
export function getStateForType(type: string): InteractableState {
    let state: InteractableState = new InteractableState();
    //Any new types need an appropriate constructor in here or they will return empty
    switch (type) {
        case "DEFAULT": {
            state.assign({
                coinChange: 0,
                interactableType: type,
                useDuration: 5100.0,
            });
            break;
        }

        case "BUTTON_PODIUM": {
            state.assign({
                coinChange: 1,
                interactableType: type,
                useDuration: 10000.0,
            });
            break;
        }
        case "COIN_OP": {
            state.assign({
                coinChange: -1,
                interactableType: type,
                useDuration: 5100.0,
            });
            break;
        }
        case "TELEPORTER": {
            state.assign({
                coinChange: -2,
                interactableType: type,
                useDuration: 5100.0,
            });
            break;
        }
    }
    return state;
}
```

The variable `coinChange` is the amount a user's coin count should change upon use. If the value is negative (the interactable COSTS coins to use), the server confirms the user has enough coins before responding with success. See the `handleObjectCost` function in `MMORoom.ts`:

```javascript
handleObjectCost(object: InteractableState, user: NetworkedEntityState): boolean {
    let cost: number = object.coinChange;
    let worked: boolean = false;

    //Its a gain, no need to check
    if (cost >= 0) {
      user.coins += cost;
      worked = true;
    }
    //Check if user can afford this
    if (cost < 0) {
      if (Math.abs(cost) <= user.coins) {
        user.coins += cost;
        worked = true;
      }
      else {
        worked = false;
      }
    }

    return worked;
  }
```

If this check is successful, object interaction will move forward normally.
The variable `useDuration` is used to factor in how long an interactable will remain `inUse` after a user interacts with it. When an interactable gets used, it's `availableTimestamp` is set as so:

```javascript
interactableObject.inUse = true;
interactableObject.availableTimestamp =
    this.state.serverTime + interactableObject.useDuration;
```

The server then checks on each timestep:

```javascript
checkObjectReset() {
    this.state.interactableItems.forEach((state: InteractableState) => {
      if (state.inUse && state.availableTimestamp <= this.state.serverTime) {
        state.inUse = false;
        state.availableTimestamp = 0.0;
      }
    });
  }
```

This resets the `inUse` value for any interactables in the MMORoom if the `serverTime` says it's time to do that.

---
Source: https://docs.colyseus.io/learn/tutorial/cocos/mmo


# Phaser: Real Time Multiplayer Tutorial

This guide will show you how you can build a multiplayer experience with Colyseus Multiplayer Framework and Phaser.

- [1. Basic Player Movement](https://docs.colyseus.io/learn/tutorial/phaser/basic-player-movement.md)
- [2. Linear Interpolation](https://docs.colyseus.io/learn/tutorial/phaser/linear-interpolation.md)
- [3. Client Predicted Input](https://docs.colyseus.io/learn/tutorial/phaser/client-predicted-input.md)
- [4. Fixed Tickrate](https://docs.colyseus.io/learn/tutorial/phaser/fixed-tickrate.md)

---

## In this tutorial you will learn how to:

- Connect multiple players into a **room**
- Use keyboard **arrow keys** to move current player
- **Interpolate** player's position on the frontend
- Apply **client-prediction** for local user input
- Use **fixed tickrate** to make sure client and server are using the same values, even if a client has lower frame-rate.

## Materials

- [ Full source-code on GitHub](https://github.com/colyseus/tutorial-phaser)
- [ Live Project on Glitch](https://glitch.com/~colyseus-phaser-tutorial)

---
Source: https://docs.colyseus.io/learn/tutorial/phaser


# Phaser #1: Basic Player Movement

This guide will show you how you can build a multiplayer experience with Colyseus Multiplayer Framework and Phaser.

## In Part 1, we will learn how to:

- Set up a **Colyseus** server and the **Phaser** client
- Connect multiple players into a **room**
- Use keyboard **arrow keys** to move players across the network

### Materials

- [ Part 1: Phaser Scene source-code](https://github.com/colyseus/tutorial-phaser/blob/master/client/src/scenes/Part1Scene.ts)
- [ Part 1: Colyseus Room source-code](https://github.com/colyseus/tutorial-phaser/blob/master/server/src/rooms/Part1Room.ts)

---

- [ Full source-code on GitHub](https://github.com/colyseus/tutorial-phaser)

## Before you start

### Prior Knowledge Expected

- Basic Phaser knowledge ([See Getting Started with Phaser 3](http://phaser.io/tutorials/getting-started-phaser3))
- Basic JavaScript/TypeScript understanding ([See TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html))
- Basic Node.js understanding ([See Introduction to Node.js](https://nodejs.dev/learn/))

## Creating the Server

We will be making a basic server, hosted locally on your computer for keeping player states.

To create a fresh new Colyseus server, run the following from your command-line:

```sh filename="Terminal"
npm init colyseus-app ./server
```

Let's make sure you can run the server locally now, by running `npm start`:

```sh filename="Terminal"
cd server
npm start
```

If successful, the output should look like this in your command-line:

```txt
✅ development.env loaded.
✅ Express initialized
⚔️ Listening on http://localhost:2567
```

## Creating the Client

We are going to set up a new project using NPM, Parcel and TypeScript for the frontend. If you are more comfortable with other tooling, feel free to use the tools of your choice instead.

### Setting up Parcel and TypeScript

Create the frontend project by running the following commands from your terminal:

```sh filename="Terminal"
mkdir client
cd client
npm init -y
```

Install the development dependencies (`parcel` and `typescript`):

```sh filename="Terminal"
npm install --save-dev parcel typescript
```

Install the runtime dependencies (`phaser` and `@colyseus/sdk`):

```sh filename="Terminal"
npm install --save phaser @colyseus/sdk
```

Generate the `tsconfig.json` file by running the following command:

```sh filename="Terminal"
npx tsc --init
```

**IMPORTANT**: By default, the generated `tsconfig.json` file has _strict_ type checking enabled. We suggest disabling strict type checking for this tutorial.

```json filename="tsconfig.json"
// (...)
    /* Type Checking */
    "strict": false,
// (...)
```

Create the `index.html` file, importing our entrypoint file as a module:

```html filename="index.html"
<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Colyseus + Phaser Example</title>
</head>
<body>
    <!---------------------------------------------------->
    <!-- Include entrypoint TypeScript file as a module -->
    <!---------------------------------------------------->
    <script src="index.ts" type="module"></script>
</body>
</html>
```

And, finally, create the entrypoint `index.ts` file TypeScript file, creating a `Phaser.Game` instance, and a `GameScene`:

```ts filename="index.ts"
import Phaser from "phaser";

// custom scene class
export class GameScene extends Phaser.Scene {
    preload() {
      // preload scene
    }

    create() {
      // create scene
    }

    update(time: number, delta: number): void {
      // game loop
    }
}

// game config
const config: Phaser.Types.Core.GameConfig = {
    type: Phaser.AUTO,
    width: 800,
    height: 600,
    backgroundColor: '#b6d53c',
    parent: 'phaser-example',
    physics: { default: "arcade" },
    pixelArt: true,
    scene: [ GameScene ],
};

// instantiate the game
const game = new Phaser.Game(config);
```

To access the frontend project from your web browser, let's start `parcel` in another terminal tab. Parcel builds and serves the frontend files:

```sh filename="Terminal"
npx parcel serve index.html
```

Alternatively, you can edit your `package.json` file and add a `"start"` command with this:

```json filename="package.json"
  // (...)
  "scripts": {
    "start": "parcel serve index.html",
  },
  // (...)
```

Then, instead of running that first long `parcel` command, you can run `npm start` for short now:

```sh filename="Terminal"
npm start
```

If successful, the output should look like this in your command-line:

```txt
> client@1.0.0 start
> parcel serve index.html

Server running at http://localhost:1234
✨ Built in 6ms
```

### Establishing a Client-Server Connection

From the Phaser scene, let's instantiate our Colyseus `Client` instance, and connect into a `Room`.

We need the `create()` method to be defined as `async` to be able to use `await` inside it.

```ts
import { Client, Room } from "@colyseus/sdk";

// custom scene class
export class GameScene extends Phaser.Scene {
    // (...)

    client = new Client("http://localhost:2567");
    room: Room;

    async create() {
      console.log("Joining room...");

      try {
        this.room = await this.client.joinOrCreate("my_room");
        console.log("Joined successfully!");

      } catch (e) {
        console.error(e);
      }
    }

    // (...)
}
```

> **Note:**
>
> Note that we're using the local `http://localhost:2567` endpoint here. You need to [deploy your server](https://docs.colyseus.io/deployment.md) to the public internet in order to play with others online.

When you refresh your browser now, your client is going to establish a connection with the server. The server then creates the room `my_room` on demand for you.

Notice that `my_room` is the default room identifier set by the barebones Colyseus server. You can and should change this identifier in the `arena.config.ts` file.

You will be seeing the following message in your server logs, which means a client successfully joined the room!

```txt
19U8WkmoK joined!
```

## Room State and Schema

In Colyseus, we define shared data through its `Schema` structures.

> `Schema` is a special data type from Colyseus that is capable of encoding its changes/mutations _incrementally_. The encoding and decoding process happens internally by the framework and its SDK.

The state synchronization loop looks like this:

1. State changes (mutations) are synchronized automatically from Server → Clients
2. Clients, by attaching callbacks to their local _read-only_ `Schema` structures, can observe for state mutations and react to it.
3. Clients can send arbitrary messages to the server - which decides what to do with it - and may mutate the state (Go back to step **1.**)

---

Let's go back to editing the Server code, and define our Room State in the Server.

We need to handle multiple `Player` instances, and each `Player` will have `x`, `y` and `z` coordinates:

**Schema Builder**

```ts filename="MyRoomState.ts"
import { schema, t } from "@colyseus/schema";

export const Player = schema({
    x: t.number(),
    y: t.number(),
}, "Player");

export const MyRoomState = schema({
    players: t.map(Player),
}, "MyRoomState");
```

**Decorators**

```ts filename="MyRoomState.ts"
import { MapSchema, Schema, type } from "@colyseus/schema";

export class Player extends Schema {
    @type("number") x: number;
    @type("number") y: number;
}

export class MyRoomState extends Schema {
    @type({ map: Player }) players = new MapSchema<Player>();
}
```

> **Note:**
>
> See [State Synchronization → Schema Definition](https://docs.colyseus.io/state/schema.md).

Now, still in the backend, let's modify our `onJoin()` method to create a `Player` instance whenever a new connection is established with the room.

```ts filename="MyRoom.ts"
// (...)
    onJoin(client: Client, options: any) {
        console.log(client.sessionId, "joined!");

        const mapWidth = 800;
        const mapHeight = 600;

        // create Player instance
        const player = new Player();

        // place Player at a random position
        player.x = (Math.random() * mapWidth);
        player.y = (Math.random() * mapHeight);

        // place player in the map of players by its sessionId
        // (client.sessionId is unique per connection!)
        this.state.players.set(client.sessionId, player);
    }
// (...)
}
```

Also, when the client disconnects, let's remove the player from the map of players:

```ts filename="MyRoom.ts"
// (...)
    onLeave(client: Client, consented: boolean) {
        console.log(client.sessionId, "left!");

        this.state.players.delete(client.sessionId);
    }
// (...)
```

The state mutations we've done on the backend **can be observed** on the frontend. That's what we're going to do in the next sections.

## Preloading Assets in the Demo Scene

For this demo, we only need one sprite to represent the player, which we are going to use whenever a player joins the room.

![Player Sprite](https://cdn.jsdelivr.net/gh/colyseus/tutorial-phaser@master/client/dist/assets/ship_0001.png)

```ts
    // (...)

    preload() {
      // preload scene
      this.load.image('ship_0001', 'https://cdn.jsdelivr.net/gh/colyseus/tutorial-phaser@master/client/dist/assets/ship_0001.png');
    }

    // (...)
```

## Listening for State Changes

After a connection with the room has been established, the frontend can start listening for state changes. The frontend then creates a visual representation of the data in the server.

In order to attach callbacks to the state, we need to import the `Callbacks` class from `@colyseus/sdk`:

```typescript
import { Callbacks } from "@colyseus/sdk";
// (...)
const callbacks = Callbacks.get(this.room);
```

### Adding new players

As per [Room State and Schema](#room-state-and-schema) section, whenever the server accepts a new connection - the `onJoin()` method is creating a new Player instance within the state.

We're going to listen to this event on the frontend now:

```ts
// (...)
callbacks.onAdd("players", (player, sessionId) => {
  //
  // A player has joined!
  //
  console.log("A player has joined! Their unique session id is", sessionId);
});
// (...)
```

When playing the Scene, you should see a message in the console of the browser whenever a new client joins the room.

For the visual representation, we need to add a Phaser GameObject for each joining player. We also keep a local reference to each GameObject, keyed by `sessionId`, so we can operate on them later:

```ts
import { Callbacks } from "@colyseus/sdk";

export class GameScene extends Phaser.Scene {
    // (...)
    room: Room;

    // we will assign each player visual representation here
    // by their `sessionId`
    playerEntities: {[sessionId: string]: any} = {};

    // (...)
    async create() {
        // (...)
        const callbacks = Callbacks.get(this.room);

        // listen for new players
        callbacks.onAdd("players", (player, sessionId) => {
            const entity = this.physics.add.image(player.x, player.y, 'ship_0001');

            // keep a reference of it on `playerEntities`
            this.playerEntities[sessionId] = entity;
        });

        // (...)
    }
}
```

### Removing disconnected players

When a player is removed from the state (upon `onLeave()` in the backend), we need to remove their visual representation as well.

```ts
// (...)
callbacks.onRemove("players", (player, sessionId) => {
    const entity = this.playerEntities[sessionId];
    if (entity) {
        // destroy entity
        entity.destroy();

        // clear local reference
        delete this.playerEntities[sessionId];
    }
});
// (...)
```

## Moving the players

### Sending input messages

For this particular example, we are going to send the player's input at every tick. This approach is a requirement for the client-side prediction technique applied by the end of this tutorial.

At every `update()` tick, we are going to update the local `inputPayload`, and send it as a message to the server.

```ts
export class GameScene extends Phaser.Scene {
    // (...)

    // local input cache
    inputPayload = {
        left: false,
        right: false,
        up: false,
        down: false,
    };

    cursorKeys: Phaser.Types.Input.Keyboard.CursorKeys;

    preload() {
        // (...)
        this.cursorKeys = this.input.keyboard.createCursorKeys();
    }

    update(time: number, delta: number): void {
        // skip loop if not connected with room yet.
        if (!this.room) { return; }

        // send input to the server
        this.inputPayload.left = this.cursorKeys.left.isDown;
        this.inputPayload.right = this.cursorKeys.right.isDown;
        this.inputPayload.up = this.cursorKeys.up.isDown;
        this.inputPayload.down = this.cursorKeys.down.isDown;
        this.room.send(0, this.inputPayload);
    }
    // (...)
```

### Receiving the message from the server

Whenever the message is received in the server, we're going to mutate the player that sent the message through its `sessionId`.

> **⚠️ Note:** We are going to update this method on Part 3. The final implementation with **client-side prediction** needs to process the input at every tick instead of when receiving the message.

```ts filename="MyRoom.ts"
// (...)
  state = new MyRoomState();

  // handle player input
  messages = {
    0: (client, payload) => {
      // get reference to the player who sent the message
      const player = this.state.players.get(client.sessionId);
      const velocity = 2;

      if (payload.left) {
        player.x -= velocity;

      } else if (payload.right) {
        player.x += velocity;
      }

      if (payload.up) {
        player.y -= velocity;

      } else if (payload.down) {
        player.y += velocity;
      }
    }
  }
// (...)
```

### Updating Player's visual representation

Having the mutation on the server, we can detect it on the frontend via `callbacks.onChange()`, or `callbacks.listen()`.

- `callbacks.onChange(instance, ...)` is triggered **per schema instance**
- `callbacks.listen(instance, prop, ...)` is triggered **per property** change

We are going to use `.onChange()` since we need all the new coordinates at once, no matter if just one has changed individually.

```ts
// (...)
// listen for new players
callbacks.onAdd("players", (player, sessionId) => {
    const entity = this.physics.add.image(player.x, player.y, 'ship_0001');

    // keep a reference of it on `playerEntities`
    this.playerEntities[sessionId] = entity;

    // listening for server updates
    callbacks.onChange(player, () => {
        // update local position immediately
        entity.x = player.x;
        entity.y = player.y;
    });

    // Alternative, listening to individual properties:
    // callbacks.listen(player, "x", (newX, prevX) => console.log(newX, prevX));
    // callbacks.listen(player, "y", (newY, prevY) => console.log(newY, prevY));
});
// (...)
```

> **Note:**
>
> See [Client SDK → State Sync Callbacks](https://docs.colyseus.io/state/callbacks.md)

## Extra: Monitoring Rooms and Connections

Colyseus comes with an optional monitoring panel that can be helpful during the development of your game.

To view the monitor panel from your local server, go to http://localhost:2567/colyseus.

![monitor](https://docs.colyseus.io/tutorial/phaser/monitor.png)

You can see and interact with all spawned rooms and active client connections through this panel.

> **Note:**
>
> See [Tools → Monitoring Panel](https://docs.colyseus.io/tools/monitoring.md)

---
Source: https://docs.colyseus.io/learn/tutorial/phaser/basic-player-movement


# Phaser #3: Client Predicted Input

> **Note:**
>
> This tutorial implements prediction **by hand** to teach the concept. For the built-in 0.18 API (`room.input()` + `Predict.reconciler` with rollback and reconciliation), see [Client Prediction](https://docs.colyseus.io/netcode/client-prediction.md).

This guide will show you how you can build a multiplayer experience with Colyseus Multiplayer Framework and Phaser.

## In Part 3, we will:

- Update **CURRENT** player position immediately at the rate of the frontend's update loop
- Use linear interpolation to smooth the visual representation of **OTHER** players

### Materials

- [ Part 3: Phaser Scene source-code](https://github.com/colyseus/tutorial-phaser/blob/master/client/src/scenes/Part3Scene.ts)
- [ Part 3: Colyseus Room source-code](https://github.com/colyseus/tutorial-phaser/blob/master/server/src/rooms/Part3Room.ts)

---

- [ Full source-code on GitHub](https://github.com/colyseus/tutorial-phaser)

## Why do we need client-side prediction?

Networked multiplayer games are always going to have _some_ delay between the server and the client.

Client-side prediction is a technique that reduces the _perceived_ delay of the local player. The client gives immediate feedback while its inputs and/or messages haven't reached the server yet.

This tutorial is going to cover one possible solution for player movement using keyboard input. Depending on the type of game you are making, and the outcome you are aiming for, a different technique could work best. There is no "final and correct" answer in this space.

## Detecting the "current player"

During [Part 1](basic-player-movement) and [Part 2](linear-interpolation) of this tutorial, we have treated local and remote players equally, moving them all using the same logic.

We will need to detect which entity represents the current player, to be able to apply custom logic to it.
To do so, we are going to identify the current player and keep a special reference to its visual representation in our game scene.

Let's declare the related variables:

```typescript
export class GameScene extends Phaser.Scene {
  // (...)

  currentPlayer: Phaser.Types.Physics.Arcade.ImageWithDynamicBody;
  remoteRef: Phaser.GameObjects.Rectangle;
```

Now, let's modify the `players.onAdd()` callback to identify which player is the current one, by checking the `sessionId` key against the connected `room.sessionId`:

```typescript
callbacks.onAdd("players", (player, sessionId) => {
    const entity = this.physics.add.image(player.x, player.y, 'ship_0001');
    this.playerEntities[sessionId] = entity;

    if (sessionId === this.room.sessionId) {
        // this is the current player!
        // (we are going to treat it differently during the update loop)
        this.currentPlayer = entity;

        // remoteRef is being used for debug only
        this.remoteRef = this.add.rectangle(0, 0, entity.width, entity.height);
        this.remoteRef.setStrokeStyle(1, 0xff0000);

        callbacks.onChange(player, () => {
            this.remoteRef.x = player.x;
            this.remoteRef.y = player.y;
        });

    } else {
        // all remote players are here!
        // (same as before, we are going to interpolate remote players)
        callbacks.onChange(player, () => {
            entity.setData('serverX', player.x);
            entity.setData('serverY', player.y);
        });
    }
});
```

The `remoteRef` here is a simple rectangle used to have visual feedback of where the local player is positioned in the server.

## Moving the local player instantly

We need to implement in the frontend the same logic we already have on the backend for player movement.

Instead of waiting for the server's acknowledgement, we apply the position change locally at the same instant we send the input to the server:

```typescript
// (...)
update(time: number, delta: number): void {
    // skip loop if not connected yet.
    if (!this.currentPlayer) { return; }

    const velocity = 2;
    this.inputPayload.left = this.cursorKeys.left.isDown;
    this.inputPayload.right = this.cursorKeys.right.isDown;
    this.inputPayload.up = this.cursorKeys.up.isDown;
    this.inputPayload.down = this.cursorKeys.down.isDown;
    this.room.send(0, this.inputPayload);

    if (this.inputPayload.left) {
        this.currentPlayer.x -= velocity;

    } else if (this.inputPayload.right) {
        this.currentPlayer.x += velocity;
    }

    if (this.inputPayload.up) {
        this.currentPlayer.y -= velocity;

    } else if (this.inputPayload.down) {
        this.currentPlayer.y += velocity;
    }
// (...)
```

> **Note:**
>
> For simplicity sake, we are duplicating the code here. As both server and client are written in TypeScript, you could potentially import a shared implementation and use it on both sides.

### Skipping linear interpolation for the current player

We are going to change the `update()` method to skip applying linear interpolation for the current player:

```typescript
for (let sessionId in this.playerEntities) {
    // do not interpolate the current player
    if (sessionId === this.room.sessionId) {
        continue;
    }

    // interpolate all other player entities
    const entity = this.playerEntities[sessionId];
    const { serverX, serverY } = entity.data.values;

    entity.x = Phaser.Math.Linear(entity.x, serverX, 0.2);
    entity.y = Phaser.Math.Linear(entity.y, serverY, 0.2);
}
```

Let's go back to your browser and see the results now. You should see the visual representation of the current player always matching the debugging red square (`remoteRef`).

## Simulating latency from the local server

Colyseus provides an utility method you can use during development for simulating network latency. You can use it for checking how the user experience would look like when experiencing latency and delay.

From the backend, in the `app.config.ts` file, add the following:

```typescript
server.simulateLatency(200);
```

On the example above, a full round-trip between client messages and the server are going to be of **200ms**.

---
Source: https://docs.colyseus.io/learn/tutorial/phaser/client-predicted-input


# Phaser #4: Fixed Tickrate

> **Note:**
>
> This tutorial enqueues and dequeues inputs at a fixed tick **by hand** to teach the concept. For the built-in 0.18 API (`defineInput()` + `setFixedTimestep()`), see [Server Input & Fixed Timestep](https://docs.colyseus.io/netcode/server-input.md).

This guide will show you how you can build a multiplayer experience with Colyseus Multiplayer Framework and Phaser.

## In Part 4, we will:

- Learn why determinism is important
- **Enqueue** incoming player inputs on the server
- **Dequeue** player inputs at every tick on the server
- Use fixed tick-rate on both the server and the frontend

### Materials

- [ Part 4: Phaser Scene source-code](https://github.com/colyseus/tutorial-phaser/blob/master/client/src/scenes/Part4Scene.ts)
- [ Part 4: Colyseus Room source-code](https://github.com/colyseus/tutorial-phaser/blob/master/server/src/rooms/Part4Room.ts)

---

- [ Full source-code on GitHub](https://github.com/colyseus/tutorial-phaser)

---

## Determinism

In order to avoid differences between the server and client simulations, both the server and the client need to be **deterministic**. Given the same inputs on both client and server, they should produce the same output.

The server and client must process the input and apply the same update loop logic at a fixed tick rate.

## Enqueue/dequeue player input on the backend

### Enqueue player input

A common technique we can apply is to enqueue player inputs, and process them all at the next server tick.

Let's update the server's `Player` definition to hold a queue of inputs, a local-only field that is never synchronized to clients:

**Schema Builder**

The `.noSync()` modifier keeps the field on the instance without registering it for synchronization:

```typescript
export const Player = schema({
  // (...)
  inputQueue: t.ref(Array).noSync().default(() => []),
}, "Player");
```

**Decorators**

A class field without `@type()` is never synchronized:

```typescript
export class Player extends Schema {
  // (...)
  inputQueue: any[] = [];
}
```

Now, when receiving the player input messages, instead of processing them immediately, we are going to enqueue them to be processed later:

```ts filename="MyRoom.ts"
// (...)
messages = {
    0: (client, payload) => {
        // handle player input
        const player = this.state.players.get(client.sessionId);

        // enqueue input to user input buffer.
        player.inputQueue.push(payload);
    }
}
```

### Process/dequeue player input at every tick

We need to have an update loop in the backend with the same implementation we do for the frontend.

For this, we use `this.setTimestep()` to register the update loop:

```ts filename="MyRoom.ts"
// (...)
onCreate() {
    // (...)
    this.setTimestep((deltaTime) => {
        this.update(deltaTime);
    });
}
```

The enqueued inputs from every player need to be processed during the `update` loop:

```ts filename="MyRoom.ts"
update(deltaTime: number) {
    const velocity = 2;

    this.state.players.forEach(player => {
        let input: any;

        // dequeue player inputs
        while (input = player.inputQueue.shift()) {
            if (input.left) {
                player.x -= velocity;

            } else if (input.right) {
                player.x += velocity;
            }

            if (input.up) {
                player.y -= velocity;

            } else if (input.down) {
                player.y += velocity;
            }
        }
    });
}
```

## Fixed tick-rate

“Ticks per second” is more practical and simpler to understand than “milliseconds per frame” when dealing with determinism.

We can force extra ticks during a single render frame so the simulation behaves the same even when the rendering frame-rate drops.

### Fixed tick-rate on Phaser

We are going to copy the entire `update()` implementation we have on the frontend, and move it to a `fixedTick()` method.

```typescript
// (...)
export class GameScene extends Phaser.Scene {
    // (...)

    fixedTick() {
        //
        // paste the previous `update()` implementation here!
        //
    }

    // (...)
}
```

Now, during the `update()` loop, we are going to allow having multiple ticks on a single frame, if needed:

```typescript
// (...)
elapsedTime = 0;
fixedTimeStep = 1000 / 60;

update(time: number, delta: number): void {
    // skip loop if not connected yet.
    if (!this.currentPlayer) { return; }

    this.elapsedTime += delta;
    while (this.elapsedTime >= this.fixedTimeStep) {
        this.elapsedTime -= this.fixedTimeStep;
        this.fixedTick(time, this.fixedTimeStep);
    }
}
```

### Fixed tick-rate on Colyseus

Let's do the same for the backend now:

```ts filename="MyRoom.ts"
// (...)
onCreate() {
    let elapsedTime = 0;
    this.setTimestep((deltaTime) => {
        elapsedTime += deltaTime;

        while (elapsedTime >= this.fixedTimeStep) {
            elapsedTime -= this.fixedTimeStep;
            this.fixedTick(this.fixedTimeStep);
        }
    });
}
// (...)
```

For consistency, we have also renamed the backend `update()` method to `fixedTick()`.

---
Source: https://docs.colyseus.io/learn/tutorial/phaser/fixed-tickrate


# Phaser #2: Linear Interpolation

> **Note:**
>
> This tutorial implements interpolation **by hand** to teach the concept. For the built-in 0.18 API that smooths remote entities for you, see [Client Prediction → Remote entities](https://docs.colyseus.io/netcode/client-prediction.md#remote-entities).

This guide will show you how you can build a multiplayer experience with Colyseus Multiplayer Framework and Phaser.

## In Part 2, we will explore:

- Update the player's positions at every tick
- Use **linear interpolation** to smooth player's movement

### Materials

- [ Part 2: Phaser Scene source-code](https://github.com/colyseus/tutorial-phaser/blob/master/client/src/scenes/Part2Scene.ts)
- [ Part 2: Colyseus Room source-code](https://github.com/colyseus/tutorial-phaser/blob/master/server/src/rooms/Part2Room.ts)

---

- [ Full source-code on GitHub](https://github.com/colyseus/tutorial-phaser)

## Why does Part 1 have choppy movement?

On [Part 1](basic-player-movement) of this tutorial, we used `callbacks.onChange()` to update the player's visual representation the instant state updates arrive from the server:

```typescript
// listening for server updates
callbacks.onChange(player, () => {
    // update local position immediately
    entity.x = player.x;
    entity.y = player.y;
});
```

The result is "choppy": the server sends updates less often than the frontend renders frames.

Colyseus sends state updates to the client at every **50ms** (_20fps_) by default, whereas the frontend re-renders at every **16.6ms** (_60fps_).

One simple yet effective way to smooth out the movement is to progressively move the player towards the latest position received at every render frame.

## Applying Linear Interpolation

### Cache remote position

The linear interpolation is going to be applied at every render frame.

To allow that, first we need to cache the latest player position received from the server:

```typescript
// listening for server updates
callbacks.onChange(player, () => {
    //
    // do not update local position immediately
    // we're going to LERP them during the render loop.
    //
    entity.setData('serverX', player.x);
    entity.setData('serverY', player.y);
});
```

### Interpolate positions at every frame

Now, we are going to iterate over every player entity during our update loop. We use `Phaser.Math.Linear()` to move each entity slowly from its current position towards the last cached position:

```typescript
update(time: number, delta: number): void {
    // (...)

    for (let sessionId in this.playerEntities) {
        // interpolate all player entities
        const entity = this.playerEntities[sessionId];
        const { serverX, serverY } = entity.data.values;

        entity.x = Phaser.Math.Linear(entity.x, serverX, 0.2);
        entity.y = Phaser.Math.Linear(entity.y, serverY, 0.2);
    }
}
```

> **Note:**
>
> The third argument of `Phaser.Math.Linear` is the _percentage_ value. You may want to adjust it for your own needs. It accepts from `0` to `1`. The higher it is, the faster the interpolation is going to happen.

---
Source: https://docs.colyseus.io/learn/tutorial/phaser/linear-interpolation


# PlayCanvas: Real Time Multiplayer Tutorial

[Video](https://playcanv.as/p/1QoAsx7r/)

> *Select create game to open a new game. And click anywhere on the floor to move the object.*

## On this tutorial you will learn:
- Setting up your Colyseus server
- Joining a Colyseus room from PlayCanvas
- Synchronizing the state between server and client
- Exchanging messages between client and server

## Materials

- [ PlayCanvas Project (Frontend)](https://playcanvas.com/project/859259/overview/colyseus-demo)
- [ Colyseus TypeScript Project (Backend)](https://github.com/colyseus/tutorial-playcanvas-server)

## Before you start

### Prior Knowledge Expected

- Basic PlayCanvas knowledge ([See PlayCanvas Developer Resources](https://developer.playcanvas.com/))
- Basic JavaScript/TypeScript understanding ([See TypeScript Handbook](https://www.typescriptlang.org/docs/handbook/intro.html))
- Basic Node.js understanding ([See Introduction to Node.js](https://nodejs.dev/learn/))

## Creating the Server

We will be making a basic server, hosted locally on your computer for keeping player states. Changes will be synchronized with clients accordingly.

To create a fresh new Colyseus server, run the following from your command-line:

```sh filename="Terminal"
npm init colyseus-app ./playcanvas-demo-server
```

Let's make sure you can run the server locally now, by running `npm start`:

```sh filename="Terminal"
cd playcanvas-demo-server
npm start
```

If successful, the output should look like this in your command-line:

```txt
✅ development.env loaded.
✅ Express initialized
⚔️ Listening on http://localhost:2567
```

## Including the Colyseus JavaScript SDK

Now we need to add the Colyseus JavaScript SDK on PlayCanvas.

We can do that through a "external script" on PlayCanvas project settings.

Open **"Menu" → "Settings"**:

![settings](https://docs.colyseus.io/tutorial/playcanvas/settings.png)

From the Settings panel, expand on **"External Scripts"**, and increase the number of **"URLs"**.

![CDN](https://docs.colyseus.io/tutorial/playcanvas/ext_script.png)

In the new **"URL"** field, let's include the Colyseus JavaScript SDK, from a CDN:

```txt
https://unpkg.com/@colyseus/sdk/dist/colyseus.js
```

This external script makes the `Colyseus` [JavaScript / TypeScript SDK](https://docs.colyseus.io/getting-started/typescript.md) available for our PlayCanvas scripts.

## Establishing a Client-Server Connection

Now, from a new PlayCanvas Script, let's instantiate our `Colyseus.Client` instance. ([see "Creating new scripts"](https://developer.playcanvas.com/en/user-manual/scripting/creating-new/))

You can attach this script to a new empty entity called "NetworkManager".

```javascript
var NetworkManager = pc.createScript('networkManager');

NetworkManager.prototype.initialize = function () {
  //
  // instantiate the SDK
  // (no connection is established at this point)
  //
  this.app.colyseus = new Colyseus.Client("http://localhost:2567");

  //
  // request to join or create a room "my_room"
  // (establish connection with the server)
  //
  this.room = await this.app.colyseus.joinOrCreate("my_room");
}
```

> **Note:**
>
> Note that we're using the local `http://localhost:2567` endpoint here. You need to [deploy your server](https://docs.colyseus.io/deployment.md) to the public internet in order to play with others online. You can also use [Glitch](https://glitch.com/edit/#!/tutorial-playcanvas-server) to host your server publicly.

When you **"Launch"** your PlayCanvas project now, your client establishes a connection with the server. The server then creates the room `my_room` on demand.

Notice that `my_room` is the default room identifier set by the barebones Colyseus server. You can and should change this identifier in the `arena.config.ts` file.

You will be seeing the following message in your server logs, which means a client successfully joined the room!

```
19U8WkmoK joined!
```

## Room State and Schema

In Colyseus, we define shared data through its `Schema` structures.

> `Schema` is a special data type from Colyseus that is capable of encoding its changes/mutations _incrementally_. The encoding and decoding process happens internally by the framework and its SDK.

The state synchronization loop looks like this:

1. State changes (mutations) are synchronized automatically from Server → Clients
2. Clients, by attaching callbacks to their local _read-only_ `Schema` structures, can observe for state mutations and react to it.
3. Clients can send arbitrary messages to the server - which decides what to do with it - and may mutate the state (Go back to step **1.**)

---

Let's go back to editing the Server code, and define our Room State in the Server.

We need to handle multiple `Player` instances, and each `Player` will have `x`, `y` and `z` coordinates:

**Schema Builder**

```typescript
// MyRoomState.ts
import { schema, t } from "@colyseus/schema";

export const Player = schema({
    x: t.number(),
    y: t.number(),
    z: t.number(),
}, "Player");

export const MyRoomState = schema({
    players: t.map(Player),
}, "MyRoomState");
```

**Decorators**

```typescript
// MyRoomState.ts
import { MapSchema, Schema, type } from "@colyseus/schema";

export class Player extends Schema {
    @type("number") x: number;
    @type("number") y: number;
    @type("number") z: number;
}

export class MyRoomState extends Schema {
    @type({ map: Player }) players = new MapSchema<Player>();
}
```

> **Note:**
>
> See [State Synchronization → Schema Definition](https://docs.colyseus.io/state/schema.md).

Now, still in the backend, let's modify our `onJoin()` method to create a `Player` instance whenever a new connection is established with the room.

```ts filename="MyRoom.ts"
// ...
    onJoin(client: Client, options: any) {
        console.log(client.sessionId, "joined!");

        // create Player instance
        const player = new Player();

        // place Player at a random position
        const FLOOR_SIZE = 4;
        player.x = -(FLOOR_SIZE/2) + (Math.random() * FLOOR_SIZE);
        player.y = 1.031;
        player.z = -(FLOOR_SIZE/2) + (Math.random() * FLOOR_SIZE);

        // place player in the map of players by its sessionId
        // (client.sessionId is unique per connection!)
        this.state.players.set(client.sessionId, player);
    }
// ...
}
```

Also, when the client disconnects, let's remove the player from the map of players:

```ts filename="MyRoom.ts"
// ...
    onLeave(client: Client, consented: boolean) {
        console.log(client.sessionId, "left!");

        this.state.players.delete(client.sessionId);
    }
// ...
```

The state mutations we've done in the backend **can be observed** in the frontend. We'll do that in the next section.

## Setting up the Scene for Synchronization

For this demo, we need to create two objects in our Scene:

- A Plane to represent the floor
- A Capsule to represent the players, which we will clone for each new player joining the room.

### Creating the Plane

Let's create a Plane with scale `8`.

![Plane](https://docs.colyseus.io/tutorial/playcanvas/plane.jpg)

### Creating the Player

Let's create the Player capsule with scale `1`.

Make sure to uncheck the `"Enabled"` property. We will not have any Player instances enabled until we have active connections with the server.

![Player](https://docs.colyseus.io/tutorial/playcanvas/player.png)

## Listening for State Changes

Once connected to the room, the frontend can start listening for state changes and build a visual representation of the server's data.

### Adding new players

As per [Room State and Schema](#room-state-and-schema) section, whenever the server accepts a new connection - the `onJoin()` method is creating a new Player instance within the state.

We're going to listen to this event on the frontend now:

```typescript
//
// In order to attach callbacks to the state, we need to use the `Callbacks.get()` method
//
const callbacks = Colyseus.Callbacks.get(this.room);

// ...
callbacks.onAdd("players", (player, sessionId) => {
  //
  // A player has joined!
  //
  console.log("A player has joined! Their unique session id is", sessionId);
});
// ...
```

When playing the Scene, you should see a message in the browser's console whenever a new client joins the room.

For the visual representation, we need to clone the "Player" object. Keep a local reference to each clone, keyed by `sessionId`, so we can operate on them later:

```typescript
// ...

// we will assign each player visual representation here
// by their `sessionId`
this.playerEntities = {};

// listen for new players
callbacks.onAdd("players", (player, sessionId) => {
  // find the base Player representation (not enabled)
  const playerEntityToClone = this.app.root.findByName("Player");

  // clone the Player representation, and enabled it!
  const entity = playerEntityToClone.clone();
  entity.enabled = true;

  // set position based on server data
  entity.setPosition(player.x, player.y, player.z);

  // add clone to the Scene
  playerEntityToClone.parent.addChild(entity);

  // assign visual representation by their `sessionId`
  this.playerEntities[sessionId] = entity;
});
// ...
```

### The "Current Player"

You can keep a special reference to the current player object by checking the `sessionId` against the connected `room.sessionId`:

```typescript
// ...
callbacks.onAdd("players", (player, sessionId) => {
  // ...
  if (room.sessionId === sessionId) {
    this.currentPlayerEntity = playerEntities[sessionId];
  }
  // ...
});
```

### Removing disconnected players

When a player is removed from the state (upon `onLeave()` in the backend), we need to remove their visual representation as well.

```javascript
// ...
callbacks.onRemove("players", (player, sessionId) => {
  // destroy entity
  this.playerEntities[sessionId].destroy();

  // clear local reference
  delete this.playerEntities[sessionId];
});
// ...
```

## Moving the players

### Sending the new position to the server

We are going to listen for the "mouse down" event. Using [ray cast](https://developer.playcanvas.com/en/user-manual/physics/ray-casting/), we determine the exact `Vec3` position the player should move towards. We then send that position as a message to the server.

```typescript
// ...
this.app.mouse.on(pc.EVENT_MOUSEDOWN, (event) => {
  // Create the "bounding box" for the floor
  const boundingBox = new pc.BoundingBox(new pc.Vec3(0, 0, 0), new pc.Vec3(4, 0.001, 4));;

  // Initialise the ray and work out the direction of the ray
  // from the a screen position
  const ray = new pc.Ray();
  const targetPosition = new pc.Vec3();

  const cameraEntity = this.app.root.findByName("Camera");
  cameraEntity.camera.screenToWorld(event.x, event.y, cameraEntity.camera.farClip, ray.direction);
  ray.origin.copy(cameraEntity.getPosition());
  ray.direction.sub(ray.origin).normalize();

  // Test the ray against the ground
  const result = boundingBox.intersectsRay(ray, targetPosition);

  if (result) {
    // Adjust position height
    targetPosition.y = 1.031;

    //
    // Send new target player position to server.
    //
    this.room.send("updatePosition", {
        x: targetPosition.x,
        y: targetPosition.y,
        z: targetPosition.z,
    });
  }
});
```

### Receiving the message from the server

Whenever the `"updatePosition"` message is received in the server, we're going to mutate the player that sent the message through its `sessionId`.

```ts filename="MyRoom.ts"
// ...
  state = new MyRoomState();

  messages = {
    "updatePosition": (client, data) => {
      const player = this.state.players.get(client.sessionId);
      player.x = data.x;
      player.y = data.y;
      player.z = data.z;
    }
  }
// ...
```

### Updating Player's visual representation

Having the mutation on the server, we can detect it on the frontend via `callbacks.onChange()`, or `callbacks.listen()`.

- `callbacks.onChange(instance, ...)` is triggered **per schema instance**
- `callbacks.listen(instance, prop, ...)` is triggered **per property** change

We are going to use `.onChange()` since we need all the new coordinates at once, no matter if just one has changed individually.

```typescript
// ...
callbacks.onAdd("players", (player, sessionId) => {
  // ...
  callbacks.onChange(player, () => {
    this.playerEntities[sessionId].setPosition(player.x, player.y, player.z);
  });

  // Alternative, listening to individual properties:
  // callbacks.listen(player, "x", (newX, prevX) => console.log(newX, prevX));
  // callbacks.listen(player, "y", (newY, prevY) => console.log(newY, prevY));
  // callbacks.listen(player, "z", (newZ, prevZ) => console.log(newZ, prevZ));
});
```

> **Note:**
>
> See [Client SDK → State Sync Callbacks](https://docs.colyseus.io/state/callbacks.md)

---

## Extra: Monitoring Rooms and Connections

Colyseus comes with an optional monitoring panel that can be helpful during the development of your game.

To view the monitor panel from your local server, go to http://localhost:2567/colyseus.

![monitor](https://docs.colyseus.io/tutorial/playcanvas/monitor.png)

You can see and interact with all spawned rooms and active client connections through this panel.

> **Note:**
>
> See [Tools → Monitoring Panel](https://docs.colyseus.io/tools/monitoring.md)

---
Source: https://docs.colyseus.io/learn/tutorial/playcanvas


# MMO Tech Demo

> **Warning:**
>
> This demo uses an older version of Colyseus.

This technical demo shows one way to make a **basic** MMO: a chat system, player persistence, multiple flowing Colyseus.Rooms and networked interactable objects. The demo **does not** include sharding or any other load balancing you would need for a production-scale MMO. This demo is designed to work with Colyseus version 0.14.7 and [Unity version 2020.3.1f1](https://unity3d.com/unity/qa/lts-releases).

**[Download demo](https://github.com/colyseus/unity-demo-mmo/archive/master.zip)** ([View source code](https://github.com/colyseus/unity-demo-mmo/))

![Screenshot](https://docs.colyseus.io/tutorial/unity/mmo/screenshot.PNG)

## Getting Started

### Launching a local server

You need to install and launch the server from the **provided Server directory** for this demo to function properly. Simply follow the instructions found underneath ["Running the demo server" in the Unity section of these docs](https://docs.colyseus.io/getting-started/unity.md#running-the-test-server-locally).

Additionally, this demo uses MongoDB for player persistence. To run it locally, set up a local DB or provide your own (see the "Adjusting the Demo" section).

[See the MongoDB website for details on how to set up a local instance](https://docs.mongodb.com/community/server/install/)

### ColyseusSettings ScriptableObject

All server settings can be changed via the ColyseusSetting ScriptableObject located here:

![ScriptableObject](https://docs.colyseus.io/tutorial/unity/scriptable-object.png)

If you are running a local server, the default settings should be sufficient. To host a server, change the **Colyseus Server Address** and **Colyseus Server Port** values accordingly.

## Playing the Demo

Start the player in the scene "MMOLoginScene" located at `ColyseusTechDemo-MMO\Assets\Scenes\MMOLoginScene`. If this is your first time, you'll need to create an account. Input your e-mail, password and then login to begin. If you are successful, the client will load the "TowerScene" scene and place a NetworkedEntity in it. At any point you can press the escape key to view the controls, customize your avatar or exit to the main menu. You will be transferred into a different room by walking into the grey cubes that are located on sides of rooms.

### Controls
The controls for this demo are visible in the Escape menu at any time and are as follows:

| Input                            | Description        |
|----------------------------------|--------------------|
| W,A,S,M                          | Movement           |
| Hold Shift                       | Sprint             |
| Q,E                              | Rotate Avatar      |
| Scroll Up/Down                   | Zoom In/Out        |
| Hold and Drag Right Mouse Button | Camera Pivot       |
| `                                | Toggle Chat Window |

## Demo Overview
This demo was designed to show how a user could potentially design and implement an MMO style game using Colyseus. It highlights the following features:
### Dynamic Rooms
MMORooms are created and disposed of as needed. When a player enters a grid space, we join a room where it's `progress` value is set to the grid values, as seen in `app.config.ts`:
```javascript
const server = defineServer({
  rooms: {
    lobby_room: defineRoom(MMORoom).filterBy(["progress"]) // Filter room by "progress" (which grid we're wanting to join EX: -1x2)
  }
})
```
As players move throughout the world, they join/leave rooms based off of their position in the world grid. A message is sent from the client to the server stating that the player is trying to update their progress, which we then catch in `MMORoom.ts`:
```javascript
messages = {
    "transitionArea": (client: Client, transitionData: Vector[]) => {
        if (transitionData == null || transitionData.length < 2) {
            logger.error(`*** Grid Change Error! Missing data for grid change! ***`);
            return;
        }
        this.onGridUpdate(client, transitionData[0] as  Vector2, transitionData[1] as  Vector3);
    }
}
```
After determining the new grid position, the client is given a new SeatReservation to consume, joining the correct Colyseus.Room for that position. A similar flow also occurs when Logging in/Signing up (see **Player Persistence** section).

![MapScreenshop](https://docs.colyseus.io/tutorial/unity/mmo/map.PNG)

The image above shows the grid map for this demo. The non-green grid spaces contain exits that will wrap around to each other, allowing you to travel from one to the other. For example in grid space `-3x3`, you can take the North West exit and you will be placed into grid space `3x-3`. All other contiguous grid spaces will have exits to each other. The grid spaces that are only touching corners will have exits in those corners to traverse the grid diagonally.

### Chat System
![ChatScreenshot](https://docs.colyseus.io/tutorial/unity/mmo/chatScreenshot.PNG)
An additional Colyseus.Room is used to handle the Chat system: `ChatRoom.ts`. In both the client and the server, anywhere we join or leave an MMORoom we also join or leave a ChatRoom. These ChatRooms are filtered by `roomId` which is the ID of the MMORoom it is connected to.
When a client sends a message, it's added to the ChatRoomState's ChatQueue, triggering a state change on all connected clients. Every new message that comes in receives a `timeStamp` value, after which it will be removed from the queue.

### Player Persistence

> **Note:**
>
> This demo uses a very basic user authentication system to persist players
> across unique user accounts. Do NOT treat it as a real-world example of how
> to implement user authentication.
> Do NOT use any email and password combination you actually use anywhere else.

In this demo, unique player accounts are persisted in a database. Each account tracks the player's progress (their current and previous room), position, coin balance, and more.
A player account is necessary to play this demo. With successful user authentication, a seat reservation for a room is sent back to the client.  The session Id of that seat reservation is saved to the player's account entry in the database as a "pendingSessionId". When the client attempts to consume the seat reservation to join the room, the "onAuth" hook looks up a player account by that "pendingSessionId". If no player account with a matching "pendingSessionId" exists, the client will not be allowed to join the room. However, with a successful player account look up, the "pendingSessionId" will become an "activeSessionId" and the client will join the room.
A player's progress is used to filter rooms during the matchmaking process. For example, a player with a progress value of "1,1" (grid coordinates 1x1) will matchmake into an existing room with the same progress value. If no room with that progress value exists, then one shall be created. This way, rooms for each grid coordinate only exist as players are in them. A player's progress is updated as they leave one grid area to move to another via one of the exit doors.
### Interactable Elements
![Interactables](https://docs.colyseus.io/tutorial/unity/mmo/coinOp.PNG)
Grid spaces may have `Interactables` scattered around them. These are frontend representations of `InteractableState` schema objects that are placed within the editor when we make a new grid space prefab. When a player performs an interaction with one of these objects, the client will send a `objectInteracted` message to the server. If the server does not yet know the provided Interactable ID, it creates a new schema reference. That reference is added to the room's schema map and makes its way back to the client. The server will then check if the Client meets the requirements to perform an interaction. If successful, all clients will receive an `objectUsed` message broadcast, along with the interactable's ID and the user who interacted with it. On the client's side, the appropriate `NetworkedEntity` and `Interactable` objects will be told to perform together.
This demo comes with 4 different types of interactables that you can find in the various grid spaces:
- Button Podium
    - Gives the interacting user 1 coin per press
- Coin Op
    - A small ride that will disable your controls temporarily and bounce your NetworkedEntity around. Costs 1 coin per use
- Teleporter
    - A small platform that will teleport a user to its "exit platform". Costs 2 coins to use
- FX Swirl
    - An alternate to the Button Podium that costs nothing and gives nothing, but displays a cool effect when pressed (uses the DEFAULT server type)

## Adjusting the Demo

As you play around with this demo, you may want to make some adjustments to better familiarize yourself with what is happening. Below, you'll learn how to make these minor adjustments.

### Using your own DB
To point this demo at your own database, provide a different Mongo connection string in the `arena.env` file in the `Server` directory. The current string expects a locally hosted mongo db:
``` javascript
DEMO_DATABASE=mongodb://localhost:27017/demo?retryWrites=true&w=majority
```

### Chat Message Life Time
On the frontend, change how long a message shows by changing the public `messageShowTime` variable on `ChatManager.cs`. That value is sent to the server when joining or creating a room in `MMOManager.cs`:
```csharp
private async void JoinChatRoom()
{
    Colyseus.Room<ChatRoomState> chatRoom = await client.JoinOrCreate<ChatRoomState>("chat_room", new Dictionary<string, object>() { { "roomID", Room.Id }, {"messageLifetime", ChatManager.Instance.messageShowTime} });
    ChatManager.Instance.SetRoom(chatRoom);
}
```
### Adding Your Own Interactables
If you want to add a new interactable to the client, it must inherit from `Interactable.cs`. Check out any of the other Interactables for ideas of what you can do. If you want to override the `serverType` value on you Interactable, you should ALSO add a case for your new `serverType` on the server in `interactableObjectFactory.ts`:
```javascript
export  function  getStateForType(type: string) : InteractableState {
	let  state : InteractableState = new  InteractableState();
	//Any new types need an appropriate constructor in here or they will return empty
	switch(type){
		case("DEFAULT"):
		{
			state.assign({
				coinChange :  0,
				interactableType :  type,
				useDuration :  5100.0
			});
			break;
		}

		case("BUTTON_PODIUM"):
		{
			state.assign({
				coinChange :  1,
				interactableType :  type,
				useDuration :  10000.0
			});
			break;
		}
		case("COIN_OP"):
		{
			state.assign({
				coinChange : -1,
				interactableType :  type,
				useDuration :  5100.0
			});
			break;
		}
		case("TELEPORTER"):
		{
			state.assign({
				coinChange : -2,
				interactableType :  type,
				useDuration :  5100.0
			});
			break;
		}
	}
	return  state;
}
```
The variable `coinChange` is the amount a user's coin count should change upon use. If the value is negative (the interactable COSTS coins to use), the server confirms the user has enough coins before responding with success. See the function `handleObjectCost` in `MMORoom.ts`:
``` javascript
handleObjectCost(object: InteractableState, user: NetworkedEntityState): boolean {
    let cost: number = object.coinChange;
    let worked: boolean = false;

    //Its a gain, no need to check
    if (cost >= 0) {
      user.coins += cost;
      worked = true;
    }
    //Check if user can afford this
    if (cost < 0) {
      if (Math.abs(cost) <= user.coins) {
        user.coins += cost;
        worked = true;
      }
      else {
        worked = false;
      }
    }

    return worked;
  }
```
If this check is successful, object interaction will move forward normally.
The variable `useDuration` is used to factor in how long an interactable will remain `inUse` after a user interacts with it. When an interactable gets used, it's `availableTimestamp` is set as so:
``` javascript
interactableObject.inUse = true;
interactableObject.availableTimestamp = this.state.serverTime + interactableObject.useDuration;
```
The server then checks on each timestep:
``` javascript
checkObjectReset() {
    this.state.interactableItems.forEach((state: InteractableState) => {
      if (state.inUse && state.availableTimestamp <= this.state.serverTime) {
        state.inUse = false;
        state.availableTimestamp = 0.0;
      }
    });
  }
```
This resets the `inUse` value for any interactables in the MMORoom if the `serverTime` says it's time to do that.

---
Source: https://docs.colyseus.io/learn/tutorial/unity/mmo


# Shooting Gallery Tech Demo

> **Warning:**
>
> This demo uses an older version of Colyseus.

The purpose of this technical demo is to show how to create rooms, utilize customized game logic and handle a full, multiplayer game cycle. The demo is designed to work with Colyseus version 0.14 and [Unity version 2019.4.20f1](https://unity3d.com/unity/qa/lts-releases).

**[Download demo](https://github.com/colyseus/unity-demo-shooting-gallery/archive/master.zip)** ([View source code](https://github.com/colyseus/unity-demo-shooting-gallery/))

![Screenshot](https://docs.colyseus.io/tutorial/unity/shooting-gallery/screenshot.png)

## Getting Started

### Launching a local server

You need to install and launch the server from the **provided Server directory** for this demo to function properly. Simply follow the instructions found underneath ["Running the demo server" in the Unity section of these docs](https://docs.colyseus.io/getting-started/unity.md#running-the-test-server-locally).

### ColyseusSettings ScriptableObject

All server settings can be changed via the ColyseusSetting ScriptableObject located here:

![ScriptableObject](https://docs.colyseus.io/tutorial/unity/scriptable-object.png)

If you are running a local server, the default settings should be sufficient. If you wish to host a server, you'll need to change the **Colyseus Server Address** and **Colyseus Server Port** values accordingly.

### Playing the Demo

Start the player in the scene "Lobby" located at `Assets\GalleryShooter\Scenes\Lobby`. Input your username and create a room to begin. **If you cannot reach the room creation screen, confirm your local server is working properly and check the Unity Editor for error logs.** If you are successful, the client will load the "GalleryShooter" scene. If you press the Enter key or click the "Start" button, you'll "ready up" and the game will begin. If you wait for more players to join on your local server, all players must "ready up" before the game will begin.

## Adjusting the Demo

As you play around with this demo, you may want to make some adjustments to better familiarize yourself with what is happening. Below, you'll learn how to make these minor adjustments.

### Targets

The values used for the Targets in-game can be found in the server code at `Server\src\rooms\customLogic\targets.ts`. Here, you can adjust the score values, rename targets and add/remove target options. If you add a new target, make sure to also give it a new "id" value. Otherwise the Unity client will not know what target model to display.

These target options on the client can be adjusted in the "TargetController" prefab, located at `Assets\GalleryShooter\Prefabs\Targets\Controls\TargetController.prefab`. If you wish to adjust the models or add new targets, here is where you prepare the client for them.

### Target Movement

The targets, when provided from the server, will be handed off to the corresponding TargetTreadmill based off of their row. "Row" is randomly set on the server in `target.ts` at line 52. If you add or remove rows in the GalleryShooter scene, the server must be made aware of it via `LobbyController.numberOfTargetRows`:

![numberOfTargetRows](https://docs.colyseus.io/tutorial/unity/shooting-gallery/number-of-target-rows.png)

This number is sent to the server when a room initializes. The server uses it when randomly selecting a target's row.

The treadmills individually control the frequency with which they'll send out targets:

![Time between targets](https://docs.colyseus.io/tutorial/unity/shooting-gallery/time-between-targets.png)

The TargetBase objects control their own speed here:

![Move speed](https://docs.colyseus.io/tutorial/unity/shooting-gallery/move-speed.png)

### Adjusting the guns

The important values for the gun can be changed on the Gun prefab here:

![Guns](https://docs.colyseus.io/tutorial/unity/shooting-gallery/guns.png)

### Max Players

The default max number of players is set to `25`. You can adjust that in `Server\src\rooms\ShootingGalleryRoom.ts` at line `94`. Or, if you wish to have no limit, simply remove this line.

### Adjust Player Movement

You can tweak the player's movement values on the prefab located at `Assets\GalleryShooter\Prefabs\GalleryShootPlayer.prefab`. Here you can also adjust the interpolation rates for movement of remote players along with other limits.

---
Source: https://docs.colyseus.io/learn/tutorial/unity/shooting-gallery


# Starboss Tech Demo

> **Warning:**
>
> This demo uses an older version of Colyseus.

This demo began with the [Unity Procedural Boss Demo](https://www.youtube.com/watch?v=LVSmp0zW8pY) [(Source available here)](https://on.unity.com/37K5j1b), which our team converted into a multiplayer experience with two different game modes.

This technical demo shows how to take an existing, single player project and convert it to handle a full, multiplayer game cycle. The demo is designed to work with Colyseus version 0.14.7 and [Unity version 2020.1.5f1](https://unity3d.com/unity/qa/lts-releases).

**[Download demo](https://github.com/colyseus/unity-demo-starboss/archive/main.zip)** ([View source code](https://github.com/colyseus/unity-demo-starboss/))

![Screenshot](https://docs.colyseus.io/tutorial/unity/starboss/screenshot.PNG)

## Getting Started

### Launching a local server

You need to install and launch the server from the **provided Server directory** for this demo to function properly. Simply follow the instructions found underneath ["Running the demo server" in the Unity section of these docs](https://docs.colyseus.io/getting-started/unity.md#running-the-test-server-locally).

### ColyseusSettings ScriptableObject

All server settings can be changed via the ColyseusSetting ScriptableObject located here:

![ScriptableObject](https://docs.colyseus.io/tutorial/unity/scriptable-object.png)

If you are running a local server, the default settings should be sufficient. If you wish to host a server, you'll need to change the **Colyseus Server Address** and **Colyseus Server Port** values accordingly.

### Playing the Demo

Start the player in the scene "StarBossLobby" located at `Assets\StarBoss\Scenes\StarBossLobby`. Input your username and create a room to begin. **If you cannot reach the room creation screen, confirm your local server is working properly and check the Unity Editor for error logs.** If you are successful, the client will load the "Scene_Dev_Environment" scene. When creating a room, you have the option to make a Co-op or a Team Deathmatch room. If you press the Enter key or click the "Start" button within a Co-op room, you'll "ready up" and the game will begin. If you wait for more players to join on your local server, all players must "ready up" before the game will begin. If you made a Team Deathmatch room, you will need at least 1 more player to join on the other team before you can begin.

## Demo Overview

### Creating and Listing Rooms with Different Game Modes
The overridden `CreateRoom` function in `StarBossLobbyController.cs` on the frontend determines whether we're launching a Team Deathmatch or Co-op room:
```csharp
string gameModeLogic = coopToggle.isOn ? "starBossCoop" : "starBossTDM";
roomOptions = new Dictionary<string, object> {{"logic", gameModeLogic }, { "scoreToWin", 3 } };
LoadMainScene(() => { ExampleManager.Instance.CreateNewRoom(selectRoomMenu.RoomCreationName, roomOptions);
```
On the backend in `StarBossRoom.ts` we receive these `roomOptions` and use the `logic` member to determine which type of room we're going to create:
```javascript
// Retrieve the custom logic for the room
const  customLogic = await  this.getCustomLogic(options["logic"]);
if(customLogic == null) logger.debug("NO Custom Logic Set");
try{
	if(customLogic != null) {
		this.setMetadata({isCoop:  options["logic"] == "starBossCoop" });
		customLogic.InitializeLogic(this, options);
	}
}
catch(error){
	logger.error("Error with custom room logic: " + error);
}
```
In this line:
```javascript
this.setMetadata({isCoop:  options["logic"] == "starBossCoop" });
```
We set the value for `isCoop` in the room's metadata, which we can then use on the frontend to display the type of room.

To accomplish this, on the frontend we created a Serializable class `StarBossRoomMetaData.cs` that contains the `isCoop` value. We then use this class within our custom `StarBossRoomAvailable` which inherits from `Colyseus.RoomAvailable`:
```csharp
[System.Serializable]
public class StarBossRoomAvailable : Colyseus.RoomAvailable {
    public StarBossRoomMetaData metadata;
}
```
And then within `ExampleManager.cs` we have updated the `GetAvailableRooms` function to receive data of type `StarBossRoomAvailable`:
```csharp
public async void GetAvailableRooms() {
    StarBossRoomAvailable[] rooms = await client.GetAvailableRooms<StarBossRoomAvailable>(_roomController.roomName);
    onRoomsReceived?.Invoke(rooms);
}
```
We also updated the `OnRoomsReceived` delegate call to use `StarBossRoomAvailable`. Finally, for every entry we receive, we Instantiate an object with a `RoomListItem` component attached and we pass it a reference to the room available. In the `DetermineMode` function in `RoomListItem.cs`:
```csharp
bool isCoop = roomRef.metadata.isCoop;

if (isCoop) {
    roomName.text = roomRef.roomId;
    gameMode.text = "Co-op";
    gameMode.color = coopColor;
    backgroundImage.color = coopColor;
}
else {
    roomName.text = roomRef.roomId;
    gameMode.text = "Team Deathmatch";
    gameMode.color = deathmatchColor;
    backgroundImage.color = deathmatchColor;
}
```
The final result gives us something like this:
![RoomList](https://docs.colyseus.io/tutorial/unity/starboss/room-list.PNG)

## Adjusting the Demo

As you play around with this demo, you may want to make some adjustments to better familiarize yourself with what is happening. Below, you'll learn how to make these minor adjustments.

### Team Deathmatch Score to Win

The maximum score to win in a Team Deathmatch is currently set to 3 on the frontend in the overridden `CreateRoom` function in `StarBossLobbyController.cs`:
```csharp
roomOptions = new Dictionary<string, object> {{"logic", gameModeLogic }, { "scoreToWin", 3 } };
LoadMainScene(() => { ExampleManager.Instance.CreateNewRoom(selectRoomMenu.RoomCreationName, roomOptions);
```

On the backend, we receive these `roomOptions` and use them to initialize the game logic. Only if we're initializing a Team Deathmatch room, do we make use of the `scoreToWin` option as seen in `starBossTDM.js`:
```javascript
roomRef.tdmScoreToWin = options["scoreToWin"] ? Number(options["scoreToWin"]) : 10;
```

---
Source: https://docs.colyseus.io/learn/tutorial/unity/starboss


# Turn Based Tanks Demo

> **Warning:**
>
> This demo uses an older version of Colyseus.

The goal of this demo is to serve as an example of one approach to an asynchronous, turn based game using Colyseus.
This demo is designed to work with Colyseus version 0.14.7 and [Unity version 2019.4.20f1](https://unity3d.com/unity/qa/lts-releases).

**[Download demo](https://github.com/colyseus/unity-demo-tanks/archive/main.zip)** ([View source code](https://github.com/colyseus/unity-demo-tanks/))

![Lobby](https://docs.colyseus.io/tutorial/unity/turn-based-tanks/WeaponFired.PNG)

## Getting Started

### Launching a local server

You need to install and launch the server from the **provided Server directory** for this demo to function properly. Simply follow the instructions found underneath [\"Running the demo server\" in the Unity section of these docs](https://docs.colyseus.io/getting-started/unity.md#running-the-test-server-locally).

### ColyseusSettings ScriptableObject

All server settings can be changed via the ColyseusSetting ScriptableObject located here:

![ScriptableObject](https://docs.colyseus.io/tutorial/unity/scriptable-object.png)

If you are running a local server, the default settings should be sufficient. If you wish to host a server, change the **Colyseus Server Address** and **Colyseus Server Port** values accordingly.

## Demo Overview

### Room Metadata

This demo makes use of the room&#39;s metadata to track the players in the game with their username. When a player joins or creates a room, their username is stored in a property called either `team0` or `team1`. `team0` represents the player that created the room. `team1` represents the player that joined an available room to challenge the creator.
``` javascript
this.metadata.team0
this.metadata.team1

this.setMetadata({"team0": options["creatorId"]});

```

The usernames set in the metadata are then used to filter the available rooms displayed in the lobby. Within the lobby, users see the rooms they have created, plus any room that is still waiting for a challenger to join. Rooms that you have not created and have two players will not be shown in the lobby.

``` csharp
private TanksRoomsAvailable[] TrimRooms(TanksRoomsAvailable[] originalRooms)
{
    List<TanksRoomsAvailable> trimmedRooms = new List<TanksRoomsAvailable>();
    for (int i = 0; i < originalRooms.Length; ++i)
    {
        //Check a rooms metadata. If its one of our rooms OR waiting for a player, we show it
        TanksRoomMetadata metadata = originalRooms[i].metadata;
        if (metadata.team1 == null || (metadata.team1.Equals(ExampleManager.Instance.UserName) ||
                                       metadata.team0.Equals(ExampleManager.Instance.UserName)))
        {
            trimmedRooms.Add(originalRooms[i]);
        }
    }

    return trimmedRooms.ToArray();
}
```

![Lobby](https://docs.colyseus.io/tutorial/unity/turn-based-tanks/Rooms.PNG)

### Keeping the Room Alive

To make this demo an asynchronous turn based game, we need to keep the room alive even after both players have left. The room is kept alive by setting the `autoDispose` flag to false (see the `onCreate` hook in the TanksRoom server code).

``` javascript
this.autoDispose = false;
```

We know to disconnect the room after the boolean flag `inProcessOfQuitingGame` has been set true after performing checks to determine if the room should be closed. These checks are performed when a user has quit the game.
``` javascript

// Check if creator has quit before anyone else has joined
if(this.metadata.team0 && this.metadata.team1 == null) {
    disconnectRoom = true;
}

// No other users are in the room so disconnect
if(this.inProcessOfQuitingGame && this.state.networkedUsers.size <= 1 && this.connectedUsers <= 1) {
    disconnectRoom = true;
}

// Should the room disconnect?
if(disconnectRoom) {
    this.disconnect();
}
```

### Pausing the Room

Since this is an example of an asynchronous game, our room could have no users connected to it for any amount of time. When there are no users connected to the room the server doesn't need to update the simulation loop.
When users disconnect from the room a check is performed to look if there are no more users connected to the room. When no more users are connected to the room the timestep effectively gets paused by setting the delay to a high value. In this case the value is a little more than 24 days.
``` javascript

// Within the room's `onLeave` handler
// Check if the server should pause the simulation loop because
// there are no users connected to the room
let anyConnected: boolean = false;
this.state.players.forEach((player, index) => {
    if(player.connected) {
        anyConnected = true;
    }
});

if(anyConnected == false) {
    // There are no users connected so pause the server updates
    this.setServerPause(true);
}


private setServerPause(pause: boolean) {

    if(pause) {
        this.setTimestep(dt => this.gameLoop(dt), this.pauseDelay);
    }
    else {
        // Set the timestep callback
        this.setTimestep(dt => this.gameLoop(dt));
    }

    this.serverPaused = pause;
}
```

When users rejoin a room that has been paused, the timestep is restored.
``` javascript

// Within the room's `onJoin` handler
// Check if the server needs to be unpaused
if(this.serverPaused) {
    // The server is currently paused so unpause it since a player has connected
    this.setServerPause(false);
}
```

### Playing the Demo

Start the player in the scene &quot;TanksLobby&quot; located at `Assets\TurnBasedTanks\Scenes\TanksLobby`. Input your username and create a room to begin. **If you cannot reach the room creation screen, confirm your local server is working properly and check the Unity Editor for error logs.** If you are successful, the client will load the &quot;TankArena&quot; scene.

- This demo is an asynchronous turn based game.

- You can leave a room at any point and later return to a game in progress. The game resumes where it left off.

- Only two players can play in a game.

- Goal being to destroy your opponent&#39;s tank.

- Each player has 3 Hit Points displayed in the top corners of the screen.

- When you create a room you can immediately take your turn without another player having joined yet.

- All controls are displayed in the **ESC** menu.

- You can leave the room at any time using the Exit option in the ESC menu, or Surrender the game to your opponent.

- You have 3 Action Points for your turn. Moving left/right consumes **one** AP and firing consumes **two** AP.

- Movement can be blocked by terrain that is too tall.

- To fire your tank&#39;s weapon you left click with the mouse and hold to charge the shot. Releasing the left mouse will fire.

- You have 3 weapons of varying range to choose from. Select your weapon with the 1-3 numbered keys.

- Between each movement or firing action there is a 2 second delay before another action can be taken.

- A game ends when a player&#39;s tank is destroyed or someone surrenders. A game over menu then shows a win/loss message, with options to request a rematch or quit the game. If the other player requests a rematch before you leave, a message will be displayed on the game over menu.

- There is an &quot;online indicator&quot; next to your opponents name to signal whether they are in the room at the same time with you.
	- **Red** = offline
	- **Green** = online

- You have the option to skip your remaining turn by pressing the SPACEBAR.

![Lobby](https://docs.colyseus.io/tutorial/unity/turn-based-tanks/GameplayWithLabels.png)
![Lobby](https://docs.colyseus.io/tutorial/unity/turn-based-tanks/GameOver.PNG)

## Adjusting the Demo

As you play around with this demo, you may want to make some adjustments to better familiarize yourself with what is happening. Below, you&#39;ll learn how to make these minor adjustments.

### Game Rules and Weapon Data

Both the **Game Rules** and **Weapon Data** values can be found in the server code at `ArenaServer\src\rooms\tanks\rules.ts`. The **Game Rules** control movement and firing costs as well as how many action points players get. The data in `weaponList` specifies the max charge, charge time, impact radius, and impact damage of each weapon.

```javascript
const GameRules = {
    MaxActionPoints: 3,
    MovementActionPointCost: 1,
    FiringActionPointCost: 2,
    ProjectileSpeed: 30,
    MaxMovement: 3,
    MaxHitPoints: 3,
    MovementTime: 2,
}

const weaponList = [
    {
        name: "Short Range",
        maxCharge: 5,
        chargeTime: 1,
        radius: 1,
        impactDamage: 1,
        index: 0
    },
    {
        name: "Mid Range",
        maxCharge: 8,
        chargeTime: 2,
        radius: 1,
        impactDamage: 1,
        index: 1
    },
    {
        name: "Long Range",
        maxCharge: 10,
        chargeTime: 5,
        radius: 1,
        impactDamage: 1,
        index: 2
    }
]
```

---
Source: https://docs.colyseus.io/learn/tutorial/unity/turn-based-tanks


# Matchmaking

Every join call from the SDK goes through the matchmaker. It picks the room a
client lands in, and answers with a **seat reservation** the SDK consumes to
establish the room connection. `joinOrCreate()` finds a compatible room or
spawns one, `join()` requires one to exist, and `joinById()` targets a
specific room. See [Joining Rooms](https://docs.colyseus.io/sdk.md#joining-rooms) for the frontend.

Which rooms are eligible, and in what order, is up to you:

- [Visibility & Access](https://docs.colyseus.io/matchmaker/visibility.md): How the `locked`, `private`, and `unlisted` flags control who can find and join a room.
- [Lobby Room](https://docs.colyseus.io/matchmaker/lobby.md): A live listing of available rooms, the backend for a room browser UI.
- [Queue Room](https://docs.colyseus.io/matchmaker/queue.md): A matchmaking queue that groups players over time and spawns a match room when a group is ready.
- [Standalone Matchmaker](https://docs.colyseus.io/matchmaker/standalone.md): Run matchmaking on a dedicated process, separate from your game servers.

## Matchmaking Options

Room types accept matchmaking options at definition time: which client
`options` distinguish rooms from each other, and which candidate fills first.

### Filter By (`.filterBy()`)

When a room is created by `create()` or `joinOrCreate()`, only the `options` declared in `filterBy()` are stored internally. Those stored options then filter candidate rooms in later `join()` or `joinOrCreate()` calls.

**Parameters**

- `options: string[]` - a list of option names

**Examples**

**Filter by "mode" provided by the client**

Filter matchmaking by `mode` option.

```ts filename="server.ts"
const server = defineServer({
  rooms: {
    battle: defineRoom(BattleRoom).filterBy(['mode'])
  }
})
```

    Whenever the room is created, the `mode` option is going to be stored internally.

```js filename="client.js"
client.joinOrCreate("battle", { mode: "duo" }).then(room => {/* ... */});
```

    You can handle the provided option in the `onCreate()` and/or `onJoin()` to implement the requested feature inside your room implementation.

```ts filename="BattleRoom.ts"
class BattleRoom extends Room {
    onCreate(options) {
        if (options.mode === "duo") {
            // do something!
        }
    }
    onJoin(client, options) {
        if (options.mode === "duo") {
            // put this player into a team!
        }
    }
}
```

**Filter by "maxClients" server config**

Filter matchmaking by the room's `maxClients` capacity.

    `maxClients` is stored top-level in the matchmaking cache from the **room instance's actual value**, not from the client's option, so the room must apply the option for the filter to work:

```ts filename="BattleRoom.ts"
class BattleRoom extends Room {
    onCreate(options) {
        // apply the requested capacity: the filter compares against
        // the room's real maxClients, not the stored client option
        this.maxClients = options.maxClients;
    }
}
```

```ts filename="server.ts"
const server = defineServer({
  rooms: {
    battle: defineRoom(BattleRoom).filterBy(['maxClients'])
  }
})
```

    The client can then ask to join a room with a specific capacity. Each value fills its own set of rooms:

```js filename="client.js"
client.joinOrCreate("battle", { maxClients: 10 }).then(room => {/* ... */});
client.joinOrCreate("battle", { maxClients: 20 }).then(room => {/* ... */});
```

---

### Sort By (`.sortBy()`)

You can also give a different priority for joining rooms depending on their information upon creation.

The `options` parameter is a key-value object containing the field name in the left, and the sorting direction in the right. Sorting direction can be one of these values: `-1`, `"desc"`, `"descending"`, `1`, `"asc"` or `"ascending"`.

**Example**

**Sorting by the built-in "clients"**

The `clients` is an internal variable stored for matchmaking, which contains the current number of connected clients. On the example below, the rooms with the highest amount of clients connected will have priority. Use `-1`, `"desc"` or `"descending"` for descending order:

```typescript
const server = defineServer({
  rooms: {
    battle: defineRoom(BattleRoom).sortBy({ clients: -1 })
  }
})
```

    To sort by the fewest amount of players, you can do the opposite. Use `1`, `"asc"` or `"ascending"` for ascending order:

```typescript
const server = defineServer({
  rooms: {
    battle: defineRoom(BattleRoom).sortBy({ clients: 1 })
  }
})
```

---

### Realtime Listing for Lobby

To allow the `LobbyRoom` to receive updates from a specific room type, you should define them with realtime listing enabled:

```typescript
const server = defineServer({
  rooms: {
    battle: defineRoom(BattleRoom).enableRealtimeListing()
  }
})
```

> **Note:**
>
> See [Lobby Room](https://docs.colyseus.io/matchmaker/lobby.md) for more details.

---

## Matchmaker API

The Matchmaker API gives you server-side control over room management and player matchmaking in Colyseus.

From your server code, you can create rooms, join players to existing rooms, query available rooms, and reserve seats. You can also monitor statistics across processes: connected users (CCU) and room counts. You can call methods on rooms running in a different process, too. None of it depends on a client request.

``` typescript
import { matchMaker } from "colyseus";
```

### Stats

Colyseus internally keeps track of statistics for the matchmaker.

#### Fetch All

Fetch all stats from all processes.

Returns an array of objects with the following properties:

- **`processId`**: the id of the process.
- **`roomCount`**: the number of rooms on the process.
- **`ccu`**: the number of connected clients on the process.

```typescript
import { matchMaker } from "colyseus";
const stats = await matchMaker.stats.fetchAll();

console.log(stats);
// => [
//    { processId: "xxx", roomCount: 10, ccu: 100 },
//    { processId: "yyy", roomCount: 9, ccu: 90 },
// ]
```

#### Get Global CCU

Get the total number of connected clients across all processes.

```typescript
import { matchMaker } from "colyseus";
const globalCCU = await matchMaker.stats.getGlobalCCU();

console.log(globalCCU);
// => 190
```

#### Get Local CCU

Get the number of connected clients on the current process.

```ts filename="server.ts"
matchMaker.stats.local.ccu
```

#### Get Local Room Count

Get the number of rooms on the current process.

```ts filename="server.ts"
matchMaker.stats.local.roomCount
```

### Methods

#### Create a Room

Creates a new room and return its cached data.

**Parameters:**

- **`roomName`**: the identifier you defined in the `rooms` configuration of `defineServer()`.
- **`options`**: options for `onCreate`.

```typescript
const room = await matchMaker.createRoom("battle", { mode: "duo" });
console.log(room);
/*
  { "roomId": "xxxxxxxxx", "processId": "yyyyyyyyy", "name": "battle", "locked": false }
*/
```

> **Note:**
>
> The Room may be created on a different process. The `processId` to create the room is selected via `selectProcessIdToCreateRoom` method.

#### Join or Create a Room

Join or create a room and return a client seat reservation.

**Parameters:**

- **`roomName`**: the identifier you defined in the `rooms` configuration of `defineServer()`.
- **`options`**: options for the client seat reservation (for `onJoin`/`onAuth`).

```ts filename="server.ts"
const reservation = await matchMaker.joinOrCreate("battle", { mode: "duo" });
console.log(reservation);
/*
  {
    "name": "battle",
    "sessionId": "zzzzzzzzz",
    "roomId": "xxxxxxxxx",
    "processId": "yyyyyyyyy"
  }
*/
```

> **Note:**
>
> **Consuming the seat reservation** - You can use [`consumeSeatReservation()` from the frontend](https://docs.colyseus.io/sdk.md#consuming-a-seat-reservation) to join the room by its reserved seat.

#### Reserve A Seat For

Creates a seat reservation in a specific room.

**Parameters:**

- **`room`**: room data (result from `createRoom()`, etc).
- **`clientOptions`**: options for `onJoin`.
- **`authData`**: authentication data (available during `onJoin` as `client.auth`)

```ts filename="server.ts"
const room = await matchMaker.findOneRoomAvailable("battle", { mode: "duo" });
const reservation = await matchMaker.reserveSeatFor(room, {});
console.log(reservation);
/*
  {
    "name": "battle",
    "sessionId": "zzzzzzzzz",
    "roomId": "xxxxxxxxx",
    "processId": "yyyyyyyyy"
  }
*/
```

> **Note:**
>
> **Consuming the seat reservation** - You can use [`consumeSeatReservation()` from the frontend](https://docs.colyseus.io/sdk.md#consuming-a-seat-reservation) to join the room by its reserved seat.

#### Join existing Room

Join a room and return seat reservation. An exception is thrown if there are no rooms available for `roomName`.

**Parameters:**

- **`roomName`**: the identifier you defined in the `rooms` configuration of `defineServer()`.
- **`options`**: options for the client seat reservation (for `onJoin`/`onAuth`).

```ts filename="server.ts"
const reservation = await matchMaker.join("battle", { mode: "duo" });
console.log(reservation);
/*
  {
    "name": "battle",
    "sessionId": "zzzzzzzzz",
    "roomId": "xxxxxxxxx",
    "processId": "yyyyyyyyy"
  }
*/
```

> **Note:**
>
> **Consuming the seat reservation** - You can use [`consumeSeatReservation()` from the frontend](https://docs.colyseus.io/sdk.md#consuming-a-seat-reservation) to join the room by its reserved seat.

#### Join Room by ID

Join a room by ID and return client seat reservation. An exception is thrown if a room is not found for `roomId`.

**Parameters:**

- **`roomId`**: the id of a specific room instance.
- **`options`**: options for the client seat reservation (for `onJoin`/`onAuth`).

```ts filename="server.ts"
const reservation = await matchMaker.joinById("xxxxxxxxx", {});
console.log(reservation);
/*
  {
    "name": "battle",
    "sessionId": "zzzzzzzzz",
    "roomId": "xxxxxxxxx",
    "processId": "yyyyyyyyy"
  }
*/
```

> **Note:**
>
> **Consuming the seat reservation** - You can use [`consumeSeatReservation()` from the frontend](https://docs.colyseus.io/sdk.md#consuming-a-seat-reservation) to join the room by its reserved seat.

#### Create and Reserve a Seat

Create a new room and return client seat reservation.

**Parameters:**

- **`roomName`**: the identifier you defined in the `rooms` configuration of `defineServer()`.
- **`options`**: options for the client seat reservation (for `onJoin`/`onAuth`).

``` typescript
const reservation = await matchMaker.create("battle", { mode: "duo" });
console.log(reservation);
/*
  {
    "name": "battle",
    "sessionId": "zzzzzzzzz",
    "roomId": "xxxxxxxxx",
    "processId": "yyyyyyyyy"
  }
*/
```

> **Note:**
>
> **Consuming the seat reservation** - You can use [`consumeSeatReservation()` from the frontend](https://docs.colyseus.io/sdk.md#consuming-a-seat-reservation) to join the room by its reserved seat.

#### Search for Rooms

Perform a query against cached rooms.

**Parameters:**

- **`conditions`**: key-value conditions object.
- **`sortOptions`**: key-value sort object.

**Query with conditions**

Example querying with conditions:

``` typescript
const rooms = await matchMaker.query({ name: "battle", mode: "duo" });
console.log(rooms);
/*
[
    { "roomId": "xxxxxxxxx", "processId": "yyyyyyyyy", "name": "battle", "locked": false },
    { "roomId": "xxxxxxxxx", "processId": "yyyyyyyyy", "name": "battle", "locked": false },
    { "roomId": "xxxxxxxxx", "processId": "yyyyyyyyy", "name": "battle", "locked": false }
]
*/
```

**Query with sorting**

Example querying with sort options and conditions:

``` typescript
const rooms = await matchMaker.query({ name: "battle", mode: "duo" }, { clients: -1});
```

#### Find One Room Available

Find an available room the same way `join()`/`joinOrCreate()` do: rooms flagged [`locked` or `private`](https://docs.colyseus.io/matchmaker/visibility.md#matchmaking-properties) are skipped (`unlisted` rooms still match).

**Parameters:**

- **`roomName`**: the identifier you defined in the `rooms` configuration of `defineServer()`.
- **`filterOptions`**: options matched against the room type's [`filterBy()`](#filter-by-filterby) fields.
- **`additionalSortOptions`**: _(optional)_ extra sort criteria applied on top of the room type's `sortBy()`.

``` typescript
const room = await matchMaker.findOneRoomAvailable("battle", { mode: "duo" });
console.log(room);
/*
  { "roomId": "xxxxxxxxx", "processId": "yyyyyyyyy", "name": "battle", "locked": false }
*/
```

#### Get Room by ID

Get room data by ID. This method returns the cached room data, and is safe to call from any process.

**Parameters:**

- **`roomId`**: the id of a specific room instance.

``` typescript
const room = await matchMaker.getRoomById("xxxxxxxxx");
console.log(room);
/*
  { "roomId": "xxxxxxxxx", "processId": "yyyyyyyyy", "name": "battle", "locked": false }
*/
```

#### Get Local Room by ID

Get the actual Room instance by ID. This method only returns the room instance if it's available in the current process, otherwise it will return `undefined`.

**Parameters:**

- **`roomId`**: the id of a specific room instance.

``` typescript
const room = await matchMaker.getLocalRoomById("xxxxxxxxx");
room.clients[0].send("hello", "world");
```

#### Batch Lookup by Room Id

Resolve a set of known roomIds in a single backend round trip. Use this when you already have a list of roomIds (for example, from a reverse-index lookup) and want their current matchmaker records. It's bounded at one wire op for any `K`, where `query()` would scan the whole room cache.

**Parameters:**

- **`roomIds`**: array of room ids to look up.

```typescript
const rooms = await matchMaker.findRoomsByIds(["roomId-a", "roomId-b", "roomId-missing"]);
console.log(rooms);
/*
  Map {
    "roomId-a" => { "roomId": "roomId-a", "processId": "...", "name": "battle", ... },
    "roomId-b" => { "roomId": "roomId-b", "processId": "...", "name": "battle", ... }
  }
*/
```

Missing roomIds are absent from the returned `Map`. Prefer this over `matchMaker.query({})` whenever you know the exact roomIds. The cost stays the same as your cluster grows.

#### Remote Room Call

Call a method or return a property on a remote room.

**Parameters:**

- **`roomId`**: the id of a specific room instance.
- **`method`**: method or attribute to call or retrieve.
- **`args`**: array of arguments.

``` typescript
// call lock() on a remote room by id
await matchMaker.remoteRoomCall("xxxxxxxxx", "lock");
```

---

### Restricting the frontend from creating rooms

You can restrict the frontend to be allowed only to call specific matchmaking methods.

**Example:** by exposing only `join`, `joinById`, and `reconnect` methods, the frontend is
not going to be able to perform `create` or `joinOrCreate` calls.

``` typescript
import { matchMaker } from "colyseus";

matchMaker.controller.exposedMethods = ['join', 'joinById', 'reconnect'];
```

Possible values for `exposedMethods` are:

- `'create'`
- `'join'`
- `'joinById'`
- `'joinOrCreate'`
- `'reconnect'`

---

## Next Steps

- [Authentication](https://docs.colyseus.io/auth.md) - Gate room joins with the `onAuth` hook
- [Scalability](https://docs.colyseus.io/scalability.md) - Run matchmaking across multiple processes and machines
- [Driver](https://docs.colyseus.io/server/driver.md) - Where matchmaking data is stored and queried

---
Source: https://docs.colyseus.io/matchmaker


# Lobby Room

The built-in `LobbyRoom` provides a live listing of available rooms in your game server.

**Features:**
- Live listing for rooms with `enableRealtimeListing()`.
- Automatic updates when rooms are created, joined, left, or disposed.
- Filter support by room `name`, optionally narrowed by `metadata`.

Rooms flagged [`private` or `unlisted`](https://docs.colyseus.io/matchmaker/visibility.md#matchmaking-properties) never appear in the lobby listing. (`locked` rooms remain listed, marked as locked.)

> **Note:**
>
> The source-code for `LobbyRoom` is available [here](https://github.com/colyseus/colyseus/blob/master/packages/core/src/rooms/LobbyRoom.ts). You can extend it for custom listing behavior.

## Server

### Expose the lobby room

```ts {5} filename="server.ts"
import { defineServer, defineRoom, LobbyRoom } from "colyseus";

const server = defineServer({
  rooms: {
    lobby: defineRoom(LobbyRoom)
  }
})
```

### Enable _realtime listing_ on your game room

When _realtime listing_ is enabled, the `LobbyRoom` is notified automatically during `onCreate()`, `onJoin()`, `onLeave()` and `onDispose()`.

```ts {6} filename="server.ts"
import { defineServer, defineRoom, LobbyRoom } from "colyseus";

const server = defineServer({
  rooms: {
    lobby: defineRoom(LobbyRoom),
    my_room: defineRoom(MyRoom).enableRealtimeListing()
  }
})
```

## Client

The `LobbyRoom` will send messages to the client whenever a room is added, removed or updated.

**TypeScript**

```ts {8,12,22} filename="client.ts"
import { Client, RoomAvailable } from "@colyseus/sdk";

const client = new Client("http://localhost:2567");
const lobby = await client.joinOrCreate("lobby");

let allRooms: RoomAvailable[] = [];

lobby.onMessage("rooms", (rooms) => {
  allRooms = rooms;
});

lobby.onMessage("+", ([roomId, room]) => {
  const roomIndex = allRooms.findIndex((room) => room.roomId === roomId);
  if (roomIndex !== -1) {
    allRooms[roomIndex] = room;

  } else {
    allRooms.push(room);
  }
});

lobby.onMessage("-", (roomId) => {
  allRooms = allRooms.filter((room) => room.roomId !== roomId);
});
```

**JavaScript**

```ts {8,12,22} filename="client.ts"
import * as Colyseus from "@colyseus/sdk";

const client = new Colyseus.Client("http://localhost:2567");

client.joinOrCreate("lobby").then(function(lobby) {
    let allRooms = [];

    lobby.onMessage("rooms", (rooms) => {
        allRooms = rooms;
    });

    lobby.onMessage("+", ([roomId, room]) => {
        const roomIndex = allRooms.findIndex((room) => room.roomId === roomId);
        if (roomIndex !== -1) {
            allRooms[roomIndex] = room;

        } else {
            allRooms.push(room);
        }
    });

    lobby.onMessage("-", (roomId) => {
        allRooms = allRooms.filter((room) => room.roomId !== roomId);
    });
});
```

**C#**

```cs {8,14,26} filename="LobbyClient.cs"
using Colyseus;

Client client = new Client("http://localhost:2567");
Room lobbyRoom = await client.JoinOrCreate("lobby");

List<RoomAvailable> allRooms = new List<RoomAvailable>();

lobbyRoom.OnMessage("rooms", (RoomAvailable[] rooms) =>
{
  allRooms.Clear();
  allRooms.AddRange(rooms);
});

lobbyRoom.OnMessage("+", (object[] message) =>
{
  string roomId = (string)message[0];
  var room = (RoomAvailable)message[1];
  int roomIndex = allRooms.FindIndex((r) => r.roomId == roomId);
  if (roomIndex != -1) {
    allRooms[roomIndex] = room;
  } else {
    allRooms.Add(room);
  }
});

lobbyRoom.OnMessage("-", (string roomId) =>
{
  allRooms.RemoveAll((r) => r.roomId == roomId);
});
```

**Lua**

```lua {13,17,33} filename="lobby.lua"
local Colyseus = require("colyseus.sdk")

local client = Colyseus.Client("http://localhost:2567")

client:join_or_create("lobby", {}, function(err, lobby)
    if err ~= nil then
        print("join error: " .. err)
        return
    end

    local all_rooms = {}

    lobby:on_message("rooms", function(rooms)
        all_rooms = rooms
    end)

    lobby:on_message("+", function(message)
        local room_id = message[1]
        local room = message[2]
        local found = false
        for i, r in ipairs(all_rooms) do
            if r.roomId == room_id then
                all_rooms[i] = room
                found = true
                break
            end
        end
        if not found then
            table.insert(all_rooms, room)
        end
    end)

    lobby:on_message("-", function(room_id)
        for i, r in ipairs(all_rooms) do
            if r.roomId == room_id then
                table.remove(all_rooms, i)
                break
            end
        end
    end)
end)

```

**Haxe**

```haxe {13,17,33} filename="Lobby.hx"
import io.colyseus.Client;
import io.colyseus.Room;

var client = new Client("http://localhost:2567");
client.joinOrCreate("lobby", [], function(err, lobby: Room<Dynamic>) {
    if (err != null) {
        trace("[Lobby] error: " + err);
        return;
    }

    var allRooms:Array<Dynamic> = [];

    lobby.onMessage("rooms", (rooms: Array<Dynamic>) -> {
        allRooms = rooms;
    });

    lobby.onMessage("+", (message: Dynamic) -> {
        var roomId:String = message[0];
        var room:Dynamic = message[1];
        var found = false;
        for (i in 0...allRooms.length) {
            if (allRooms[i].roomId == roomId) {
                allRooms[i] = room;
                found = true;
                break;
            }
        }
        if (!found) {
            allRooms.push(room);
        }
    });

    lobby.onMessage("-", (roomId: String) -> {
        allRooms = allRooms.filter((room) -> room.roomId != roomId);
    });
});
```

### Filtering rooms

Filter the listing by providing the `filter` option when joining the lobby. A filter **must include `name`**. The name check runs unconditionally, so a metadata-only filter matches nothing. Use `metadata` to narrow within a room name:

```ts {2-7} filename="client.ts"
const lobby = await client.joinOrCreate("lobby", {
  filter: {
    name: "my_room",
    metadata: {
      gameMode: "deathmatch",
    }
  }
});
```

Alternatively, you can also dynamically change the filter by sending a `"filter"` message to the lobby room:

```ts
lobby.send("filter", {
  name: "my_room",
  metadata: {
    gameMode: "deathmatch",
  }
});
```

---
Source: https://docs.colyseus.io/matchmaker/lobby


# Queue Room

The built-in `QueueRoom` provides a matchmaking queue that groups players over time and spawns a match room when a group is ready.

**Features:**
- Rank-based grouping with customizable compatibility (`compare`).
- Team-aware grouping (`maxTeamSize`, `teamId`).
- Timeout-based priority escalation (`maxWaitingCyclesForPriority`).
- Optional incomplete matches for bots (`allowIncompleteGroups`).
- Custom room creation hook (`onGroupReady`).

> **Note:**
>
> The source-code for `QueueRoom` is available [here](https://github.com/colyseus/colyseus/blob/master/packages/core/src/rooms/QueueRoom.ts). You can extend it or override `compare`/`onGroupReady` for custom matchmaking.

## Server

### Expose the queue room

```ts {5-10} filename="server.ts"
import { defineServer, defineRoom, QueueRoom } from "colyseus";

const server = defineServer({
	rooms: {
		queue: defineRoom(QueueRoom, {
			matchRoomName: "battle",
			maxPlayers: 4,
			maxWaitingCycles: 15,
		}),
	}
});
```

### Expose your match room

```ts {7} filename="server.ts"
import { defineServer, defineRoom, Room } from "colyseus";

class BattleRoom extends Room {}

const server = defineServer({
	rooms: {
		battle: defineRoom(BattleRoom),
		queue: defineRoom(QueueRoom, { matchRoomName: "battle" })
	}
});
```

## Options

`QueueRoom` receives the following options on `defineRoom(QueueRoom, options)`:

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `matchRoomName` | `string` | **required** | Name of the room to create when a group is ready. |
| `maxPlayers` | `number` | `4` | Number of players per match group. |
| `maxWaitingCycles` | `number` | `15` | Cycles after which a group can be marked ready if `allowIncompleteGroups` is true. |
| `maxWaitingCyclesForPriority` | `number` | `10` | Cycles after which a client becomes high-priority and can bypass `compare`. ⚠ Not applied from `defineRoom` options in 0.18.1. Subclass to change it. |
| `maxTeamSize` | `number` | — | Enables team-based grouping and limits team size per match. |
| `allowIncompleteGroups` | `boolean` | `false` | Allows groups to start before reaching `maxPlayers` (expect bots). |
| `compare` | `(client, group) => boolean` | built-in | Compatibility check for assigning a client to a group. |
| `onGroupReady` | `(group) => Promise<IRoomCache>` | built-in | Custom hook to create/choose the room to join. |

## Client

### Joining the queue

```ts filename="client.ts"
import { Client } from "@colyseus/sdk";

const client = new Client("http://localhost:2567");

const queue = await client.joinOrCreate("queue", {
	rank: 1200,
	teamId: "party-42",
	mode: "ranked",
});
```

### Queue updates

The server periodically notifies clients with the number of players currently in their group.

**TypeScript**

```ts filename="client.ts"
queue.onMessage("clients", (count) => {
  console.log("Players in your group:", count);
});
```

**JavaScript**

```js filename="client.js"
queue.onMessage("clients", (count) => {
  console.log("Players in your group:", count);
});
```

**C#**

```cs filename="Client.cs"
queue.OnMessage("clients", (int count) => {
  Debug.Log("Players in your group: " + count);
});
```

**Lua**

```lua filename="client.lua"
queue:on_message("clients", function(count)
  print("Players in your group: " .. tostring(count))
end)
```

**Haxe**

```haxe filename="client.hx"
queue.onMessage("clients", function(count: Int) {
  trace("Players in your group: " + Std.string(count));
});
```

### Receiving a seat reservation

When a group is ready, the queue sends a seat reservation for the target match room:

**TypeScript**

```ts filename="client.ts"
queue.onMessage("seat", async (reservation) => {
  // Optionally confirm the reservation to the queue
  queue.send("confirm");

  // Join the match room with the reservation
  const match = await client.consumeSeatReservation(reservation);
  console.log("Joined match", match.roomId);
});
```

**JavaScript**

```js filename="client.js"
queue.onMessage("seat", (reservation) => {
  // Optionally confirm the reservation to the queue
  queue.send("confirm");

  // Join the match room with the reservation
  client.consumeSeatReservation(reservation).then(match => {
    console.log("Joined match", match.roomId);
  });
});
```

**C#**

```cs filename="Client.cs"
queue.OnMessage("seat", async (SeatReservation reservation) => {
  // Optionally confirm the reservation to the queue
  await queue.Send("confirm");

  // Join the match room with the reservation
  var match = await client.ConsumeSeatReservation<YourStateClass>(reservation);
  Debug.Log("Joined match " + match.roomId);
});
```

**Lua**

```lua filename="client.lua"
queue:on_message("seat", function(reservation)
  -- Optionally confirm the reservation to the queue
  queue:send("confirm")

  -- Join the match room with the reservation
  client:consume_seat_reservation(reservation, function(err, match)
    if (err ~= nil) then
      print("join error: " .. err)
      return
    end
    print("Joined match " .. match.roomId)
  end)
end)
```

**Haxe**

```haxe filename="client.hx"
queue.onMessage("seat", function(reservation: Dynamic) {
  // Optionally confirm the reservation to the queue
  queue.send("confirm");

  // Join the match room with the reservation
  client.consumeSeatReservation(reservation, YourStateClass, function(err, match: Room<YourStateClass>) {
    if (err != null) {
      trace("join error: " + err);
      return;
    }
    trace("Joined match " + match.roomId);
  });
});
```

## Matching behavior

### Rank-based grouping

By default, clients are grouped by rank and split into multiple groups if the rank difference becomes too high. You can customize this logic with `compare`:

```ts filename="server.ts"
import { defineRoom, QueueRoom } from "colyseus";

defineRoom(QueueRoom, {
	matchRoomName: "battle",
	compare: (client, group) => {
		const diff = Math.abs(client.rank - group.averageRank);
		return diff <= 50; // strict rank matching
	}
});
```

### Team-based grouping

Provide `maxTeamSize` and pass `teamId` from the client to enforce team cohesion:

```ts filename="server.ts"
defineRoom(QueueRoom, {
	matchRoomName: "battle",
	maxPlayers: 6,
	maxTeamSize: 3,
});
```

```ts filename="client.ts"
await client.joinOrCreate("queue", {
	rank: 980,
	teamId: "party-7",
});
```

### Incomplete groups and bots

If you want matches to start even when groups are not full, enable `allowIncompleteGroups`. Your match room should fill the remaining slots with bots.

```ts filename="server.ts"
defineRoom(QueueRoom, {
	matchRoomName: "battle",
	maxPlayers: 4,
	allowIncompleteGroups: true,
	maxWaitingCycles: 8,
});
```

## Custom room creation

Use `onGroupReady` to decide how and where a match room is created:

```ts filename="server.ts"
import { defineRoom, QueueRoom, matchMaker } from "colyseus";

defineRoom(QueueRoom, {
	matchRoomName: "battle",
	onGroupReady: async function (group) {
		// Create a new room with match options
		return await matchMaker.createRoom("battle", {
			averageRank: group.averageRank,
			players: group.clients.length,
		});
	}
});
```

---
Source: https://docs.colyseus.io/matchmaker/queue


# Standalone Matchmaker

In the default Colyseus setup, matchmaking and room handling run together in the same process. You can separate them so that a **dedicated matchmaker process** handles all matchmaking logic, while **separate game server processes** handle the actual room connections.

```
┌─────────────────────────┐
│   Matchmaker Process   │  ← handles join/create/query
│   (no rooms here)       │
└────────────┬────────────┘
             │  IPC via Redis
      ┌──────┴──────┐
      ▼             ▼
┌───────────┐ ┌───────────┐
│ Game Srv  │ │ Game Srv  │  ← rooms run here
│ (rooms)   │ │ (rooms)   │
└───────────┘ └───────────┘
```

This architecture is useful when you want to:

- Have a single entry point for matchmaking while distributing room workload across multiple game servers
- Scale game servers independently from the matchmaking layer
- Run the matchmaker behind a lightweight HTTP service without a WebSocket transport

## Requirements

The matchmaker process and the game server processes must share the same **Presence** and **Driver** instances. Use [Redis](https://docs.colyseus.io/server/presence.md) for the presence, and [Redis, Postgres, or the Database driver](https://docs.colyseus.io/server/driver.md) for the driver. Sharing them lets the processes communicate via IPC and share room cache state.

## Game Server Processes

Each game server process runs a full Colyseus server with its rooms defined using `defineServer()`. These processes handle the actual WebSocket connections and room logic.

```ts filename="app.config.ts"
import { defineServer, defineRoom } from "colyseus";
import { RedisPresence } from "@colyseus/redis-presence";
import { RedisDriver } from "@colyseus/redis-driver";
import { WebSocketTransport } from "@colyseus/ws-transport";
import { BattleRoom } from "./rooms/BattleRoom";

const gameServer = defineServer({
    transport: new WebSocketTransport(),
    presence: new RedisPresence(),
    driver: new RedisDriver(),
    publicAddress: "game-server-1.example.com:2567",
    rooms: {
        battle: defineRoom(BattleRoom),
    },
});
```

> **Note:**
>
> Each game server must have a unique `publicAddress` so that the client SDK knows where to establish its WebSocket connection after receiving a seat reservation.

## Matchmaker Process

To run a standalone matchmaker, use `defineServer()` with the `isStandaloneMatchMaker` option set to `true`. This option tells Colyseus that the process only handles matchmaking. A standalone matchmaker will not spawn rooms locally, subscribe to IPC room creation requests, or register itself as an available game server process.

```ts {7} filename="app.config.ts"
import { defineServer, defineRoom } from "colyseus";
import { RedisPresence } from "@colyseus/redis-presence";
import { RedisDriver } from "@colyseus/redis-driver";
import { BattleRoom } from "./rooms/BattleRoom";

const server = defineServer({
    isStandaloneMatchMaker: true,
    presence: new RedisPresence(),
    driver: new RedisDriver(),
    rooms: {
        battle: defineRoom(BattleRoom),
    },
});
```

When `isStandaloneMatchMaker` is enabled, the process:

- **Skips IPC subscription**: it will not receive or handle remote room creation requests
- **Skips health checks**: it does not register itself in the process stats, so room creation never targets it while a healthy game server is registered. Two fallbacks still land a room here: when **no** game-server stats exist yet, and when a remote room-creation request times out over IPC.
- **Delegates room creation**: when a matchmaking request requires a new room, the default `selectProcessIdToCreateRoom` will select one of the available game server processes

> **Warning:**
>
> The matchmaker process must register the same room types as the game servers. Room classes are needed for `filterBy()` options and `onAuth()` validation during matchmaking, even though rooms are not instantiated on this process.

### Custom process selection

By default, rooms are created on the game server process with the fewest rooms. You can override this with `selectProcessIdToCreateRoom`:

```ts {7-12} filename="app.config.ts"
import { defineServer, defineRoom } from "colyseus";
import { RedisPresence } from "@colyseus/redis-presence";
import { RedisDriver } from "@colyseus/redis-driver";
import { BattleRoom } from "./rooms/BattleRoom";

const server = defineServer({
    isStandaloneMatchMaker: true,
    presence: new RedisPresence(),
    driver: new RedisDriver(),
    selectProcessIdToCreateRoom: async (roomName, clientOptions) => {
        // Custom logic to select which game server should create the room
    },
    rooms: {
        battle: defineRoom(BattleRoom),
    },
});
```

## How it works

1. A client sends a matchmaking request (e.g. `joinOrCreate`) to the matchmaker process
2. The matchmaker finds or creates a room (room creation is delegated to a game server process via IPC)
3. The matchmaker returns a **seat reservation** containing the `sessionId`, `roomId`, and the game server's `publicAddress`
4. The client SDK uses the `publicAddress` to establish a WebSocket connection directly to the game server hosting the room

> **Note:**
>
> Clients receive a seat reservation with the `publicAddress` of the game server that created the room. The client SDK uses this address to connect directly to the game server. Traffic does not flow through the matchmaker process after matchmaking.

---
Source: https://docs.colyseus.io/matchmaker/standalone


# Room Visibility & Access

Which rooms a player can discover, and which they can actually enter, are two
different questions. Three flags answer them.

## Matchmaking Properties

Three boolean flags control who can find and join a room: `locked`, `private`, and `unlisted`. They sound similar but behave differently on each join path:

| | `join()` / `joinOrCreate()` | `joinById()` | Lobby / listing queries |
|---|---|---|---|
| **`locked`** | skipped | rejected (`room "…" is locked`) | listed (as locked) |
| **`private`** | skipped | **allowed** | hidden |
| **`unlisted`** | **matched** | allowed | hidden |

- **`locked`**: no new clients can join, on any path. Set automatically when the room fills up (`maxClients` reached, releases itself when a seat frees), or explicitly via [`lock()`](#lock-room). [Reconnections](https://docs.colyseus.io/room/reconnection.md) still work: a reconnecting client returns to the seat it already owned.
- **`private`**: invite-only. Never matched by `join()`/`joinOrCreate()` and never shown in listings, but anyone holding the room ID can enter through `joinById()`. Use it for invite links and party codes. Set via `setPrivate()` or `setMatchmaking({ private: true })`.
- **`unlisted`**: hidden, but still matchmade. The room doesn't show up in lobby/listing queries, yet `join()`/`joinOrCreate()` keep filling it normally. Use it to keep rooms out of your room browser without pulling them from matchmaking. Set via `setMatchmaking({ unlisted: true })`.

> **Note:**
>
> **Looking for passwords?** There is no built-in password concept: `private` does not imply a password. To gate a room behind a password, combine `filterBy()`, `unlisted`, and an `onAuth()` check: see [Password Protect Room](https://docs.colyseus.io/recipes/password-protect-room.md).

### `setMatchmaking(updates)`

Updates multiple matchmaking/listing properties at once, with a single persist operation. This method is the recommended way to update room listing properties.

- `metadata` (optional): room metadata (**replaces** the existing value)
- `private` (optional): whether the room should be private
- `locked` (optional): whether the room should be locked
- `maxClients` (optional): maximum number of clients allowed
- `unlisted` (optional): whether the room should be hidden from listing queries

```ts filename="MyRoom.ts"
// Update multiple properties at once
await this.setMatchmaking({
    metadata: { difficulty: "hard", rating: 1500 },
    private: true,
    locked: true,
    maxClients: 10
});
```

> **Warning:**
>
> `metadata` is **replaced**, never merged. To merge, spread the current value yourself:
> `setMatchmaking({ metadata: { ...this.metadata, round: 2 } })`.

You can also set individual properties:

- **`setPrivate(bool?)`**: toggle `private` (defaults to `true`)
- **`setMetadata(meta)`**: replace `metadata`
- **[`lock()`](#lock-room) / [`unlock()`](#unlock-room)**: toggle `locked`
- **`this.maxClients = N`**: forwards to `setMatchmaking({ maxClients: N })`

---

## Lock Room

Locking removes the room from matchmaking: `join()`/`joinOrCreate()` skip it, and `joinById()` rejects with a `room "<roomId>" is locked` error. No new clients can join until it's unlocked.

```ts filename="MyRoom.ts"
this.lock();
```

The room also locks **automatically** when it reaches `maxClients`. The two differ in how they release: an automatic lock releases itself as soon as a seat frees up, while an explicit `lock()` is sticky. The room stays locked until you call `unlock()`.

---

## Unlock Room

Returns the room to the pool of available rooms. New clients can join again, as long as `maxClients` hasn't been reached.

```ts filename="MyRoom.ts"
this.unlock();
```

---
Source: https://docs.colyseus.io/matchmaker/visibility


# Migrating between versions

Each guide covers the breaking changes and new APIs when upgrading from the previous version. Upgrade one major version at a time.

- [**Migrating to 0.18** (from 0.17)](https://docs.colyseus.io/migrating/0.18.md): built-in client-side prediction & lag compensation ([netcode](https://docs.colyseus.io/netcode.md)), `setSimulationInterval` → `setTimestep`, `@colyseus/database` / `@colyseus/admin`, auth password-reset requirement.
- [**Migrating to 0.17** (from 0.16)](https://docs.colyseus.io/migrating/0.17.md)
- [**Migrating to 0.16** (from 0.15)](https://docs.colyseus.io/migrating/0.16.md)
- [**Migrating to 0.15** (from 0.14)](https://docs.colyseus.io/migrating/0.15.md)

Upgrading from something older? Follow the guides in sequence. The archived docs for each version remain available from the **Versions** menu above.

---
Source: https://docs.colyseus.io/migrating


# Migrating to version 0.15 (from 0.14)

See [version 0.15 release announcement](https://github.com/colyseus/colyseus/releases/tag/0.15.0).

- [`@colyseus/arena` has been renamed to `@colyseus/tools`](#colyseusarena-has-been-renamed-to-colyseustools)
- [Schema's `.triggerAll()` has been deprecated.](#schema-callbacks-api-slightly-changed)
- [Schema callbacks API change](#schema-callbacks-api-slightly-changed)
- [Schema's `onChange` behaviour change](#schemas-onchange-behaviour-change)
- [`MapSchema` is now strict on property accessors](#mapschema-is-now-strict-on-property-accessors)
- [`client.reconnect()` API slightly changed](#clientreconnect-api-slightly-changed)
- [`allowReconnection()`: second argument is now mandatory](#allowreconnection-second-argument-is-now-mandatory)
- [`@colyseus/loadtest` has been reworked!](#colyseusloadtest-has-been-reworked)
- [`@colyseus/command` typings update](#colyseuscommand-typings-update)
- [Built-in `client.auth` is gone! `@colyseus/social` fully deprecated](#built-in-clientauth-is-gone-colyseussocial-fully-deprecated)
- [`RedisDriver` and `RedisPresence` constructor change](#redisdriver-and-redispresence-constructor-change)
- [onLeave `1001` and `4000` error codes range](#onleave-1001-and-4000-error-codes-range)

---

## `@colyseus/arena` has been renamed to `@colyseus/tools`

You can remove `@colyseus/arena` and install `@colyseus/tools`:

```sh filename="npm install"
npm install --save @colyseus/tools
```

```ts filename="arena.config.ts"
// 0.14 (old)
import Arena from "@colyseus/arena";
export default Arena({...})

// 0.15 (new)
import config from "@colyseus/tools";
export default config({...})
```

You can also rename the `arena.config.ts` file to `app.config.ts` for consistency.

---

## Schema's `.triggerAll()` has been deprecated

Now, whenever you register an `onAdd()` callback, it is called immediately for already existing items - thus, making the usage of `.triggerAll()` not necessary anymore.

You can prevent the `onAdd()` callback from being triggered automatically, though, if necessary.

```ts
state.players.onAdd(() => {
    /*
     * a player has been added
     */
}, false);
```

By providing `false` in the second argument, the `onAdd()` callback is not going to be triggered for already existing items.

---

## Schema callbacks API slightly changed

Now, instead of assigning a single callback per `onAdd`/`onChange`/`onRemove`, you attach them by calling as a method instead. You can attach more than one callback this way.

See example below:

=== "TypeScript"

``` typescript
// 0.14 (old)
state.players.onAdd = function(value, key) {/* do stuff */};
state.players.onChange = function(value, key) {/* do stuff */};
state.players.onRemove = function(value, key) {/* do stuff */};

// 0.15 (new)
state.players.onAdd(function(value, key) {/* do stuff */});
state.players.onChange(function(value, key) {/* do stuff */});
state.players.onRemove(function(value, key) {/* do stuff */});
```

=== "C#"

``` csharp
// 0.14 (old)
state.players.OnAdd += (key, value) => {/* do stuff */};
state.players.OnChange += (key, value) => {/* do stuff */};
state.players.OnRemove += (key, value) => {/* do stuff */};

// 0.15 (new)
state.players.OnAdd((key, value) => {/* do stuff */})
state.players.OnChange((key, value) => {/* do stuff */})
state.players.OnRemove((key, value) => {/* do stuff */})
```

=== "Lua"

``` lua
-- 0.14 (old)
state.players.on_add = function(value, key) --[[ do stuff ]] end
state.players.on_change = function(value, key) --[[ do stuff ]] end
state.players.on_remove = function(value, key) --[[ do stuff ]] end

-- 0.15 (new)
-- ATTENTION: this is a method call. make sure to use `:` instead of `.` here.
state.players:on_add(function(value, key) --[[ do stuff ]] end)
state.players:on_change(function(value, key) --[[ do stuff ]] end)
state.players:on_remove(function(value, key) --[[ do stuff ]] end)
```

=== "Haxe"

``` haxe
// 0.14 (old)
state.players.onAdd = function(value, key) {/* do stuff */};
state.players.onChange = function(value, key) {/* do stuff */};
state.players.onRemove = function(value, key) {/* do stuff */};

// 0.15 (new)
state.players.onAdd(function(value, key) {/* do stuff */});
state.players.onChange(function(value, key) {/* do stuff */});
state.players.onRemove(function(value, key) {/* do stuff */});
```

The return value of `onAdd()`/`onChange()`/`onRemove()` is a function that can detach the callback that have been added.

=== "TypeScript"

``` typescript
const detachCallback = state.players.onAdd(function(value, key) {/* do stuff */});

// detaches the onAdd callback.
detachCallback();
```

=== "C#"

``` csharp
var detachCallback = state.players.OnAdd((key, value) => {/* do stuff */})

// detaches the onAdd callback.
detachCallback();
```

=== "Lua"

``` lua
local detach_callback = state.players:on_add(function(value, key) --[[ do stuff ]] end)

-- detaches the onAdd callback.
detach_callback();
```

=== "Haxe"

``` haxe
var detachCallback = state.players.onAdd(function(value, key) {/* do stuff */});

// detaches the onAdd callback.
detachCallback();
```

---

## Schema's `onChange` behaviour change

### On `Schema` instances

The list of `changes` inside the `onChange` callback is not provided anymore.
You can still use `onChange` to detect wheter the instance object had changes,
but you should use `.listen()` to listen for its particular properties:

``` typescript
// 0.14 (old)
state.player.onChange = function(changes) {
    console.log("player changed!");
    changes.forEach((change) => {
        if (change.field === "fieldname") {
            console.log(change.value);
        }
    })
}

// 0.15 (new)
state.player.onChange(() =>{
    console.log("player changed!");
});
state.player.listen("field", (value) => {
    console.log(value);
})
```

### On `ArraySchema` and `MapSchema`

Previously, the `onChange` callback wouldn't be fired during `onAdd` and `onRemove` when attached to a collection of items (`MapSchema`, `ArraySchema`, etc).

Now, `onChange` is triggered alongside with `onAdd` and `onRemove`.

---

## `MapSchema` is now strict on property accessors

Only JavaScript/TypeScript is affected. If you use a frontend SDK other than JavaScript/TypeScript, no change is needed on the frontend for you.

```ts
// 0.14 (old)
this.state.players[client.sessionId] = new Player();

// 0.15 (new)
this.state.players.set(client.sessionId, new Player());
```

> **Reasoning:** `MapSchema` used to be treated as a regular JavaScript object in the early days. Since version 0.14 `MapSchema` uses a real `Map` internally, with a "proxy" compatibility layer in order to avoid breaking existing projects. Now the "proxy" layer has been removed, improving the performance slightly.

---

## `client.reconnect()` API slightly changed

The previous reconnection implementation had a [security vulnerability](https://github.com/colyseus/colyseus/issues/354), although very unlikely to be explored, we had to update its implementation to make it secure.

``` typescript
// 0.14 (old)
client.reconnect(cachedRoomId, cachedSessionId)

// 0.15 (new)
client.reconnect(cachedReconnectionToken)
```

Insterad of providing the previously active `room.roomId` and `room.sessionId` for reconnection, you only provide the `room.reconnectionToken` instead.

Reconnection tokens are unique and private for each client.

---

## `allowReconnection()`: second argument is now mandatory

Previously, by omitting the second argument of `allowReconnection()`, you were in control over when to cancel the possibility for reconnection.

To make this intent more explicit, the second argument is now mandatory, either `"manual"` or the number of seconds to wait for reconnection:

=== "Manual"

```ts
async onLeave (client: Client, consented: boolean) {
// ...
try {
    if (consented) { throw new Error("consented leave"); }

    //
    // Get reconnection token
    // NOTE: do not use `await` here yet!
    //
    const reconnection = this.allowReconnection(client, "manual");

    //
    // here is the custom logic for rejecting the reconnection.
    // for demonstration purposes of the API, an interval is created
    // rejecting the reconnection if the player has missed 2 rounds,
    // (assuming he's playing a turn-based game)
    //
    // in a real scenario, you would store the `reconnection` in
    // your Player instance, for example, and perform this check during your
    // game loop logic
    //
    const currentRound = this.state.currentRound;
    const interval = setInterval(() => {
    if ((this.state.currentRound - currentRound) > 2) {
        // manually reject the client reconnection
        reconnection.reject();
        clearInterval(interval);
    }
    }, 1000);

    // now it's time to `await` for the reconnection
    await reconnection;

    // client returned! let's re-activate it.
    // ...

} catch (e) {

    // reconnection has been rejected. let's remove the client.
    // ...
}
}
```

=== "Number of seconds"

```ts
async onLeave (client: Client, consented: boolean) {
try {
    if (consented) { throw new Error("consented leave"); }

    // allow disconnected client to reconnect into this room until 20 seconds
    await this.allowReconnection(client, 20);

} catch (e) {

    // 20 seconds expired. reconnection not successful.
}
}
```

---

## `@colyseus/loadtest` has been reworked!

The loadtest tool has been reworked to allow for more complex scripting, so your loadtest scripts will need to be slightly rewritten. The new format looks like this:

```ts
import { Client, Room } from "colyseus.js";
import { cli, Options } from "@colyseus/loadtest";

async function main(options: Options) {
    const client = new Client(options.endpoint);
    const room: Room = await client.joinOrCreate(options.roomName, {/*
        your join options here...
    */});

    console.log("joined successfully!");

    room.onMessage("message-type", (payload) => {
        // logic
    });

    room.onStateChange((state) => {
        console.log("state change:", state);
    });

    room.onLeave((code) => {
        console.log("left");
    });
}

// execute
cli(main);
```

## `@colyseus/command` typings update

On latest version of `@colyseus/command` (`0.2.0`), instead of providing the state as a generic when extending the `Command`, you now provide your whole `Room` type:

```diff
import { Command } from "@colyseus/command";
export class MyRoom extends Room<State> {/* ... */}
-export class MyCommand extends Command<State> {/* ... */}
+export class MyCommand extends Command<MyRoom> {/* ... */}
```

---

## Built-in `client.auth` is gone! `@colyseus/social` fully deprecated.

The [documentation has been discouraging the use of `@colyseus/social`](https://0-14-x.docs.colyseus.io/colyseus/tools/colyseus-social/) since version 0.14.

Now `@colyseus/social` has been officially deprecated. If you **really** rely on it please reach out to the devs on Discord on how to proceed if you still need to use it.

---

## `RedisDriver` and `RedisPresence` constructor change

Providing a URI as connection string for `RedisDriver` or `RedisPresence` has
changed to:

```diff
-new RedisDriver({ url: "redis://xyz:123" })
+new RedisDriver("redis://xyz:123")
```

## onLeave `1001` and `4000` error codes range

If you had a condition like this:
```
if (1001 <= code) {
    // process any abnormal shutdown
}
```

Now you need to validate the higher limit as well since we have the custom error codes starting on `4000`.
```
if (1001 <= code && 1015 >= code) {
    // process any abnormal shutdown
}
```
See https://docs.colyseus.io/sdk/#on-leave-event and https://docs.colyseus.io/room/#leave-room

---
Source: https://docs.colyseus.io/migrating/0.15


# Migrating to version 0.16 (from 0.15)

Use this guide to migrate your existing 0.15 projects to version 0.16.

> **Note:**
>
> See [version 0.16 release announcement](https://colyseus.io/blog/colyseus-016-is-here/).

Make sure `colyseus` and all `@colyseus/*` packages on `package.json` are pointing to `^0.16.0`. Having different versions of `colyseus` and `@colyseus/*` packages may lead to unexpected behavior.

**Backend:**

```json filename="package.json"
    "@colyseus/schema": "^3.0.0",
    "colyseus": "^0.16.0",
    "@colyseus/auth": "^0.16.0",
    "@colyseus/core": "^0.16.0",
    "@colyseus/loadtest": "^0.16.0",
    "@colyseus/monitor": "^0.16.0",
    "@colyseus/playground": "^0.16.0",
    "@colyseus/testing": "^0.16.0",
    "@colyseus/tools": "^0.16.0",
    "@colyseus/uwebsockets-transport": "^0.16.0",
```

**Frontend:**

```json filename="package.json"
    "colyseus.js": "^0.16.0",
```

Make sure you don't have any packages under `0.15.x`, neither `@colyseus/schema` under `2.0.x`. You may need to remove `node_modules` and `package-lock.json` before running `npm install`.

---

## Schema callbacks and `$(instance)` proxy

The callback methods have been extracted out of the `Schema` instances. To attach callbacks, you now have to get a proxied version of your instances via `$(yourInstance)`.

```ts filename="client.ts"
import { getStateCallbacks } from "colyseus.js";

const room = await client.joinOrCreate("my_room");
const $ = getStateCallbacks(room);

$(room.state).players.onAdd((player, sessionId) => {
    // this is the raw Schema instance
    console.log(player);

    // this is the proxied version, where you can attach the callbacks
    $(player).listen("x", (value, previousValue) => {
        console.log("player.x has been updated!", value, previousValue);
    });
});
```

The proxy is capable of entering nested objects, even if they're not available at the time you're attaching the callback.

```ts filename="client.ts"
$(room.state)
    .yourInstance // this is a Schema instance (may not be immediately available)
    .yourItems // this is a MapSchema or ArraySchema (may also not be immediately available)
    .onAdd((item, index) => {
        console.log("item added at index", index);
    });
```

> For more context on why these changes are being applied, see [colyseus/colyseus#709](https://github.com/colyseus/colyseus/issues/709)

## `@filter()` and `@filterChildren()` are now removed!

The `StateView` feature has been introduced in version 0.16, which allows you to create a view of your state with a subset of the data.

```ts filename="MyState.ts"
import { view, type, Schema, MapSchema } from "@colyseus/schema";

class MyState extends Schema {
    @type({ map: Player }) players = new MapSchema<Player>();
}

class Player extends Schema {
    // this property is visible to all
    @type("string") name: string;

    // this property is only visible a `StateView` that has added this Player instance.
    @view() @type("number") position: number;
}
```

The `StateView` must be assigned to the `client.view`. The room serializer is going to use the `client.view` to serialize the state before sending it to the client.

```ts filename="MyRoom.ts"
import { StateView } from "@colyseus/schema";

// ...
    onJoin(client, options) {
        const player = new Player();

        client.view = new StateView();
        client.view.add(player);

        this.state.players.set(client.sessionId, player);
    }
```

Each `StateView` instance is going to add a new encoding step for state serialization. You may re-use the same `StateView` instance for multiple clients, or create a new one for each client.

See more in the [`StateView` documentation](https://docs.colyseus.io/state/view.md).

## Breaking changes

### Attaching `playground` routes:

The `playground` routes are now returned from a method call instead:

```diff filename="src/app.config.ts"
import { playground } from "@colyseus/playground";

// ...
if (process.env.NODE_ENV !== "production") {
-   app.use("/", playground);
+   app.use("/", playground());
}
```

This change was necessary to avoid the internal monkey-patching coming from the playground module when using in production environment.

### SDKs: `getAvailableRooms()` method has been removed!

The `getAvailableRooms()` method has been removed from the SDKs. The usage of `getAvailableRooms()` was considered a security risk for many use-cases, as it was exposing the full list of rooms to any client.

If you rely on this method, you can easily re-implement it on your backend code. A more secure way to query rooms is recommended, such as using the `LobbyRoom`.

```ts filename="app.config.ts"
import { matchMaker } from "colyseus";

// ...
express (app) {
    app.get("/rooms/:roomName?", (req, res) => {
        const conditions: any = {
            locked: false,
            private: false,
        };
        if (roomName) {
            conditions["name"] = roomName;
        }
        res.json(await matchMaker.query(conditions));
    });
}
```

From the client SDK, you can use `client.http.get("/rooms/:roomName")` to get the list of rooms.

### `matchMaker.getRoomById()`

- `matchMaker.getRoomById()` now returns the cached room data. This method will return properly when called from any process.
- `matchMaker.getLocalRoomById()` returns the room instance itself, if it's available in the current process.

### `ArraySchema.deleteAt()` has been removed.

You can use `ArraySchema.splice()` instead:

```diff
- array.deleteAt(index);
+ array.splice(index, 1);
```

### Sending schema-encoded messages is now deprecated

Sending schema instances as messages via `client.send(instance)` or `this.broadcast(instance)` is now deprecated. This feature it was introduced in previous versions due to lack of strong types in C# for messages.

### `.encode()`, `.encodeAll()` and `.decode()` methods have been moved

The Schema instances used to provide `.encode()`, `.encodeAll()` and `.decode()` methods. These methods are called internally by the framework, and if you were not using them, you don't need to worry about this change.

If you were using these methods, you can now use them from the `Encoder` and `Decoder` classes:

```ts
import { Encoder, Decoder } from "@colyseus/schema";

const encoder = new Encoder(new MyState());
const encodeAllBytes = encoder.encodeAll();

const decoded = new Decoder(new MyState());
decoded.decode(encodeAllBytes);
```

---
Source: https://docs.colyseus.io/migrating/0.16


# Migrating to version 0.17 (from 0.16)

> **Note:**
>
> See [0.17 release notes](https://github.com/colyseus/colyseus/releases/tag/0.17) for more details.

## Upgrading packages

Get all the latest 0.17.x versions for the package names you already have in your `package.json`:

```json filename="package.json"
{
    "dependencies": {
        "colyseus": "^0.17.8",
        "@colyseus/core": "^0.17.32",
        "@colyseus/tools": "^0.17.18",
        "@colyseus/ws-transport": "^0.17.9",
        "@colyseus/monitor": "^0.17.7", // (optional)
        "@colyseus/playground": "^0.17.10", // (optional)
        "@colyseus/redis-driver": "^0.17.6", // (optional)
        "@colyseus/redis-presence": "^0.17.6", // (optional)
        "@colyseus/auth": "^0.17.6", // (optional)
        "@colyseus/loadtest": "^0.17.8", // (optional)
        "@colyseus/testing": "^0.17.11", // (optional)
        "@colyseus/uwebsockets-transport": "^0.17.13", // (optional)
    }
}
```

The `@colyseus/schema` package is now at version 4.0.x

```diff filename="package.json"
-   "@colyseus/schema": "^3.0.x",
+   "@colyseus/schema": "^4.0.8",
```

On the frontend, replace `colyseus.js` with the `@colyseus/sdk` package:

```diff filename="package.json"
-   "colyseus.js": "^0.16.x",
+   "@colyseus/sdk": "^0.17.26",
```

### uWebSockets.js (`@colyseus/uwebsockets-transport`)

If you use uWebSockets.js, it is now required to add `uwebsockets-express` as a dependency to your project.

```diff filename="package.json"
-   "uwebsockets-express": "^1.3.x",
+   "uwebsockets-express": "^1.4.1",
```

(If you'd like to migrate to Express v5, you should use `uwebsockets-express@2.0.1` instead.)

### New recommended structure for `app.config.ts`

We are soft-deprecating how to structure the `app.config.ts` file. The previous syntax is still supported, but we recommend using the new one. Eventually, the previous syntax will be removed.

```diff filename="app.config.ts"
-import config from "@colyseus/tools";
+import { defineServer, defineRoom } from "colyseus";
+import { MyRoom } from "./rooms/MyRoom";

-export default config({
+const server = defineServer({
-    initializeGameServer: (gameServer) => {
-        gameServer.define("my_room", MyRoom);
-    },
+    rooms: {
+        my_room: defineRoom(MyRoom),
+    },
-    initializeTransport: () => new uWebSocketsTransport(),
+    transport: new uWebSocketsTransport(),
-    initializeExpress: (app) => {}
+    express: (app) => {}
-    options: {/* presence: new RedisPresence(), driver: new RedisDriver(), etc. */}
+    /* presence: new RedisPresence(), driver: new RedisDriver(), etc. */
});
```

(The [`create-colyseus-app` templates](https://github.com/colyseus/create-colyseus-app/tree/master/templates) are now using this new structure.)

## Breaking Changes

### Backend

#### Matchmaker: Seat reservation format has changed

The seat reservation returned by `matchMaker.reserveSeatFor(room)` has a new format. Update any code that manually accesses its `.room` object.

```diff
{
    "sessionId": "zzzzzzzzz",
-    "room": { "roomId": "xxxxxxxxx", "processId": "yyyyyyyyy", "name": "battle", ...other room data...}
+    "name": "battle",
+    "roomId": "xxxxxxxxx",
+    "processId": "yyyyyyyyy",
+    "sessionId": "zzzzzzzzz",
+    "publicAddress": "subdomain.domain.com",
}
```

Accessing the `.roomId` from the seat reservation object has changed:

```diff
const seatReservation = await matchMaker.reserveSeatFor(room);
-const roomId = seatReservation.room.roomId;
+const roomId = seatReservation.roomId;
```

The `"room"` object has been removed from the seat reservation object.

We basically removed redundant and unecessary information from the seat reservation object.

#### TypeScript: `Room` generic types have changed:

The `Room<State, Metadata>` generic type has changed to `Room<{ state: S, metadata: M, client: C }>`.

If you only use `Room<State>`, you can remove the generic types, and assign the state instance to the `state` property.

```diff filename="MyRoom.ts"
-export class MyRoom extends Room<MyState> {
+export class MyRoom extends Room {
+    state = new MyState();
```

Alternatively, if you need to initialize the state in `onCreate()` (e.g., passing arguments to the state constructor), use the new generic type format:

```ts filename="MyRoom.ts"
export class MyRoom extends Room<{ state: MyState }> {
    onCreate(options) {
        this.state = new MyState(options.someArg);
    }
}
```

#### LobbyRoom: `updateLobby()` calls are not required anymore

There is no need to manually call `updateLobby()` after `.setMetadata()` anymore. The lobby update happens automatically.

#### Room's `this.presence.subscribe()` / `this.presence.unsubscribe()`

There is no need to manually unsubscribe from presence channels in the `onDispose()` method anymore. Subscriptions are removed automatically when the room is disposed.

#### TypeScript: `Client` generic types have changed:

The `Client<UserData, AuthData>` generic types have changed to `Client<{ userData: U, auth: A, messages: M }>`.

```diff
interface UserData {
    your: any;
    custom: any;
    data: any;
}
interface AuthData {
    id: string;
    name: string;
}

-onJoin(client: Client<UserData, AuthData>) {
+onJoin(client: Client<{ userData: UserData, auth: AuthData }>) {
    console.log(client.userData);
    console.log(client.auth);
    console.log(client.messages);
}
```

Alternatively, you can create your own `Client` type alias:

```typescript
import { type Client as MyClient } from "colyseus";
type Client = MyClient<{ userData: UserData, auth: AuthData }>;
// ...
onJoin(client: Client) {
    console.log(client.userData.custom);
    console.log(client.auth.name);
}
```

#### TypeScript: `ClientArray` generic types have changed:

Similar to `Client`, the `ClientArray<UserData, AuthData>` generic types have changed to `ClientArray<Client<{ userData: U, auth: A, messages: M }>>`.

```diff
-clients: ClientArray<UserData, AuthData>;
+clients: ClientArray<Client<{ userData: UserData, auth: AuthData }>>;
```

#### `.setSeatReservationTime()` method has moved:

The `.setSeatReservationTime()` method has moved to the `.seatReservationTimeout` property.

```diff
-   this.setSeatReservationTime(15);
+   this.seatReservationTimeout = 15;
```

#### Room `onLeave()`'s `consented` parameter have changed

The `consented: boolean` parameter have changed to `code: number`:

```diff
-   async onLeave (client: Client, consented: boolean) {
+   async onLeave (client: Client, code: number) {
}
```

In order to keep the same behavior, you can use the following:

```typescript
import { CloseCode } from "colyseus";

async onLeave (client: Client, code: number) {
    const consented = (code === CloseCode.CONSENTED);
    // ... your existing code ...
}
```

#### Internal and undocumented Room properties have changed

If you were accessing or modifying internal undocumented properties of the `Room` class, you may need to update your code.

```diff filename="Example"
-this.resetAutoDisposeTimeout();
+this["resetAutoDisposeTimeout"]();
```

List of renamed protected members:

| Old Member | New Member |
|--------|-------------|
| `this.resetAutoDisposeTimeout` | `this["resetAutoDisposeTimeout"]` |
| `this.listing` | `this["_listing"]` |
| `this.reservedSeats` | `this["_reservedSeats"]` |
| `this.reservedSeatTimeouts` | `this["_reservedSeatTimeouts"]` |
| `this._events` | `this["_events"]` |
| `this._reconnections` | `this["_reconnections"]` |

#### `onMessage()` now supports multiple handlers per message type

Previously, registering a new handler for the same message type would replace the existing one. Starting from 0.17, `onMessage()` supports multiple handlers for the same message type. All registered handlers will be invoked when a matching message is received.

```typescript
this.onMessage("move", (client, message) => { /* handler 1 */ });
this.onMessage("move", (client, message) => { /* handler 2 */ });
// Both handlers will run when a "move" message is received.
```

If your code previously relied on re-registration to replace a handler, you must now explicitly unbind the previous one using the function returned by `onMessage()`:

```typescript
const unbind = this.onMessage("move", (client, message) => { /* ... */ });

// Later, replace the handler:
unbind();
this.onMessage("move", (client, message) => { /* new handler */ });
```

#### Fallback for all messages

If you were using the `onMessageHandlers` property directly to register a fallback for all messages, you need to update your code to use the `onMessageFallbacks` property instead.

```diff filename="Example"
-this.onMessageHandlers["__no_message_handler"] = {
-    callback: (client, type, payload) => {
-       // ... your existing code ...
-    }
-}}
+this["onMessageFallbacks"]["__no_message_handler"] = (client, type, payload) => {
+    // ... your existing code ...
+}
```

#### `Protocol.WS_*` constants have been moved to `CloseCode`

```diff
-import { Protocol } from "colyseus";
+import { CloseCode } from "colyseus";
```

| Old (`Protocol.WS_*`) | New (`CloseCode.*`) |
|----------------------|---------------------|
| `WS_CLOSE_NORMAL` | `NORMAL_CLOSURE` |
| `WS_CLOSE_GOING_AWAY` | `GOING_AWAY` |
| `WS_CLOSE_CONSENTED` | `CONSENTED` |
| `WS_CLOSE_WITH_ERROR` | `WITH_ERROR` |
| `WS_CLOSE_DEVMODE_RESTART` | `MAY_TRY_RECONNECT` |
| `WS_SERVER_DISCONNECT` | `SERVER_SHUTDOWN` |
| `WS_TOO_MANY_CLIENTS` | (removed) |

> **Important:**
>
> **Important: WebSocket Close Codes Conflict**
>
> Colyseus now uses close codes in the 4000-4010 range:
> - `4000` - `CONSENTED`
> - `4001` - `SERVER_SHUTDOWN`
> - `4002` - `WITH_ERROR`
> - `4003` - `FAILED_TO_RECONNECT`
> - `4010` - `MAY_TRY_RECONNECT`
>
> If your application was previously using codes in the 4xxx range for custom purposes (e.g., account banned, kicked), update your code to avoid conflicts. Choose values outside the codes listed above.
>
> The [WebSocket specification](https://github.com/Luka967/websocket-close-codes) reserves 4000-4999 for application use, but Colyseus now uses part of this range internally.

### Frontend

#### Accessing `refId` of Schema instances

You could previously access the `refId` of Schema instances via the `room.serializer.decoder.root.refIds` object.

```diff
-room.serializer.decoder.root.refIds.get(schemaInstance)
```

You may now access the `refId` of a Schema instance via the `[$refId]` property.

```diff
+import { $refId } from "@colyseus/schema";
+const refId = schemaInstance[$refId]
```

---
Source: https://docs.colyseus.io/migrating/0.17


# Migrating to version 0.18 (from 0.17)

> **Note:**
>
> See [0.18 release notes](https://github.com/colyseus/colyseus/releases/tag/0.18) for the full changelog.

## Upgrading packages

Get all the latest 0.18.x versions for the package names you already have in your `package.json`:

```json filename="package.json"
{
    "dependencies": {
        "colyseus": "^0.18.1",
        "@colyseus/core": "^0.18.1",
        "@colyseus/tools": "^0.18.1",
        "@colyseus/ws-transport": "^0.18.1",
        "@colyseus/monitor": "^0.18.1",     // (optional)
        "@colyseus/playground": "^0.18.1",  // (optional)
        "@colyseus/redis-driver": "^0.18.1", // (optional)
        "@colyseus/redis-presence": "^0.18.1", // (optional)
        "@colyseus/auth": "^0.18.1",        // (optional)
        "@colyseus/loadtest": "^0.18.1",    // (optional)
        "@colyseus/testing": "^0.18.1",     // (optional)
        "@colyseus/uwebsockets-transport": "^0.18.1" // (optional)
    }
}
```

The `@colyseus/schema` package is now at version **5.0.x**. 0.18 requires it (reconnect resync and input schema reflection build on it):

```diff filename="package.json"
-   "@colyseus/schema": "^4.0.8",
+   "@colyseus/schema": "^5.0.8",
```

On the frontend, bump `@colyseus/sdk` as well:

```diff filename="package.json"
-   "@colyseus/sdk": "^0.17.26",
+   "@colyseus/sdk": "^0.18.1",
```

### New packages in 0.18

Two new official packages ship alongside the framework. Both are optional. Install them only if you want the features they provide:

- [`@colyseus/database`](https://docs.colyseus.io/database.md): the recommended persistence layer (Drizzle ORM, SQLite/PostgreSQL, user store, cloud saves, leaderboards, configs, analytics, audit log).
- [`@colyseus/admin`](https://docs.colyseus.io/admin.md): the production operations console (CRUD over your tables, live room inspector, dashboard, RBAC). Depends on `@colyseus/database` and `@colyseus/auth`.

```sh npm2yarn
npm install --save @colyseus/database @colyseus/admin
```

### Client-side prediction & lag compensation

0.18 adds first-class primitives for **server-authoritative simulation with client-side prediction** (zero-latency local control, smooth remote entities, and "what you see is what you hit" lag-compensated hits, without hand-rolling a netcode stack):

- **Server:** `defineInput()` (per-client input + buffering), `setFixedTimestep()` (fixed-rate authoritative loop), `allowRewindState()` (lag compensation).
- **Client:** `room.input()` (reliable or unreliable input channel), `Predict` (`reconciler` / `sim` for rollback, `attachAll` for remote smoothing, `defineEvent` for optimistic events, `spawns` for predicted projectiles), and `room.clock` (synchronized server clock: `serverNow()`, `renderNow()`, `rtt()`, `jitter()`).

These are additive. Existing rooms are unaffected. See [Netcode](https://docs.colyseus.io/netcode.md) for the full guide.

### Request/response messaging

Clients can now `await` a reply from a message handler. No more hand-rolled ping/pong message pairs:

```ts filename="client.ts"
const profile = await room.request("get-profile", { userId: 42 });
```

On the server, the same `messages` handlers serve both fire-and-forget sends and requests. **Return a value** to answer, or use the new optional `ctx` argument to reject with a typed reason:

```ts filename="MyRoom.ts"
messages = {
    "get-profile": async (client, { userId }) => {
        return await db.profiles.findById(userId); // becomes the client's response
    },
    "buy-item": (client, { itemId }, ctx) => {
        const item = shop.get(itemId);
        if (!item) return ctx.reject("unknown-item"); // rejects the client's promise
        return { balance: item.buy(client) };
    },
}
```

This change is additive. Existing two-argument handlers are unaffected. See [Room → Responding to a message](https://docs.colyseus.io/room.md#responding-to-a-message-requestresponse) and [SDK → Request/Response](https://docs.colyseus.io/sdk.md#requestresponse).

### `setSimulationInterval()` → `setTimestep()`

`setSimulationInterval()` was renamed to **`setTimestep()`**. The old name still works (it forwards), so this is **not** a breaking change:

```ts
// ✅ still works (deprecated alias)
this.setSimulationInterval((deltaTime) => this.update(deltaTime));

// ✅ preferred
this.setTimestep((deltaTime) => this.update(deltaTime));
```

For client-predicted games, use the new fixed-step loop `setFixedTimestep(step, tickRate)` instead. See [Server Input & Fixed Timestep](https://docs.colyseus.io/netcode/server-input.md).

`@colyseus/testing` follows the same rename in 0.18.2: `room.waitForNextSimulationTick()` became [`room.waitForNextTimestep()`](https://docs.colyseus.io/tools/unit-testing.md#wait-for-next-timestep), with the old name kept as a forwarding alias:

```ts
// ✅ still works (deprecated alias)
await room.waitForNextSimulationTick();

// ✅ preferred
await room.waitForNextTimestep();
```

## Breaking Changes

### A `Schema` now holds at most 63 fields

0.17 allowed 64 fields, but the last slot was already unsafe. An operation on the field at index 63 could encode as the byte that starts a new structure. The client then misread the rest of the patch, and the state desynchronized.

0.18 rejects the 64th field where the class is defined, so the problem surfaces at startup instead of in production:

```
Can't define field 'lastOne'.
Schema instances may only have up to 63 fields.
```

Move the extra fields onto a nested child `Schema`. Inherited fields count toward the limit, so check the parent class too. See [State → Limitations](https://docs.colyseus.io/state.md#limitations).

### `Room#setMetadata()` now replaces instead of merging

In 0.17, `room.setMetadata({ ... })` (and `room.setMatchmaking({ metadata: { ... } })`) would shallow-merge the provided fields into the existing metadata. In 0.18 these calls **replace** the entire metadata object, matching the behaviour of the `this.metadata = ...` setter and the rest of `setMatchmaking()`.

To preserve the previous merging behaviour, spread `this.metadata` yourself at the call site:

```ts
// ❌ 0.17: partial update, other fields were preserved
await this.setMetadata({ status: "in_progress" });

// ✅ 0.18: spread existing fields explicitly to merge
await this.setMetadata({ ...this.metadata, status: "in_progress" });

// Same applies to setMatchmaking()
await this.setMatchmaking({
  metadata: { ...this.metadata, status: "in_progress" },
});
```

The type of the `meta` parameter changed from `Partial<Metadata>` to the full `Metadata` to reflect the new semantics.

### `client.id` was removed

The `Client#id` property, deprecated for several versions, is gone. Use `sessionId`:

```diff
-   console.log(client.id);
+   console.log(client.sessionId);
```

### `@colyseus/fossil-delta-serializer` was removed

The legacy fossil-delta state serializer (deprecated since schema-based serialization became the default) has been removed, along with its SDK-side decoder. If you were still using it, migrate your state to [`@colyseus/schema`](https://docs.colyseus.io/state.md).

### Playground is locked down in production

`@colyseus/playground`'s data endpoints (room listing/inspection, API schemas, CPU profiles) now return **404 on production mounts** (`NODE_ENV=production`, outside devMode). The opt-in is a guard middleware passed through the `use` option. If you exposed the playground in production before, add one; see [Playground → Password protection](https://docs.colyseus.io/tools/playground.md#password-protection).

### `@colyseus/auth`: password hashing changed

`@colyseus/auth` 0.18 ships a new default password hasher that derives its own per-password salt. The legacy `scrypt` hasher (used in 0.17 and earlier) relied on a global `AUTH_SALT` environment variable and is now deprecated.

**Existing email/password users will need to reset their passwords.** Their pre-0.18 hashes cannot be verified by the new hasher and stay in the database until each user runs through the password-reset flow.

#### Migration steps

1. **Keep `AUTH_SALT` set in your environment** during the transition. The legacy hasher remains available to verify pre-0.18 hashes. That keeps existing sessions and legacy verification paths working while you roll out the change.

2. **Notify your email/password users and force a password reset.** Two ways:
    - **Email everyone a reset link** through the standard [forgot-password flow](https://docs.colyseus.io/auth/module.md#send-password-reset-email). When the user submits a new password, the 0.18 default hasher writes a fresh hash with its own salt.
    - **Invalidate sessions to force the reset on next login**: call `db.auth.bumpTokenVersion(userId)`, or your own equivalent if you're not using `@colyseus/database`. Existing JWTs are then rejected and the user is sent through the login → reset flow.

3. **After every user has reset their password, remove `AUTH_SALT`** from your environment. New deployments and post-reset users don't need it; the legacy hasher has no remaining hashes to verify.

> **Note:**
>
> New 0.18 projects (no pre-existing users) can skip setting `AUTH_SALT` entirely. The variable is only relevant to upgrades that need to verify pre-0.18 hashes during the transition.

See [Auth Module → Required Environment Secrets](https://docs.colyseus.io/auth/module.md#required-environment-secrets) for the up-to-date secrets list.

---
Source: https://docs.colyseus.io/migrating/0.18


# Netcode

Fast-paced games can't wait for the network. If your character only moves after a round-trip to the server, controls feel sluggish. But if the client simply moves itself, the server is no longer in charge and cheating becomes trivial.

Colyseus 0.18 gives you both: the server stays authoritative, and the client **predicts**. Your own movement responds instantly, remote players move smoothly, and hits register against what you saw on screen. The framework runs the prediction, reconciliation, and rewind loops. You supply the deterministic step function.

> **Note:**
>
> **Available in Colyseus 0.18+.** These APIs (`room.input()`, `Predict`, `defineInput()`, `setFixedTimestep()`, `allowRewindState()`) are new in 0.18 and have no equivalent in earlier versions.

## The mental model

The stack is one loop split across the server and the client. Each half is configured independently, but they only make sense together:

- The **server** runs the authoritative simulation at a **fixed tick rate**.
- The **client predicts** its own entity by running the same step function locally. When the server's authoritative state arrives, it **reconciles**: roll back, replay the inputs the server hasn't processed yet, and smoothly correct any mismatch.
- **Remote** entities are smoothed from the server stream (interpolated a little in the past, or dead-reckoned forward).
- For hits, the server **rewinds** other entities to where the shooter *saw* them (their render time). That way, a well-aimed shot at a moving target registers.

> One input per fixed step; one `predict.tick()` per render frame drives everything.

```mermaid
flowchart TB
    subgraph S["SERVER: authoritative"]
        buffer["<b>defineInput()</b><br/>input buffer"]
        step["<b>setFixedTimestep()</b><br/>step(ctx) at tickRate"]
        rewind["<b>allowRewindState()</b><br/>record() / rewind.lastSeenBy()"]
    end

    subgraph C["CLIENT: predicts"]
        input["sample input"]
        predict["predict own entity<br/>(<b>reconciler</b> / <b>sim</b>)"]
        reconcile["reconcile: roll back, replay<br/>inputs newer than the ack"]
        remotes["smooth remotes<br/>(<b>Predict</b> lerp)"]
    end

    input --> predict
    input ==>|"<b>room.input().send()</b>"| buffer
    buffer --> step
    step --> rewind
    step ==>|"state patch + ack"| reconcile
    reconcile --> predict
    remotes -.->|"renderTime stamp"| rewind
```

## Which primitive for which interaction?

Every interaction in your game maps onto a small set of primitives. Find the row that matches, then jump to the page that documents it:

| Interaction | Primitive | Page |
|---|---|---|
| Your own movement (one entity, flat fields) | `predict.reconciler` | [Client Prediction](https://docs.colyseus.io/netcode/client-prediction.md) |
| Anything your inputs push / carry / throw (paddle + puck, vehicle + cargo) | `predict.sim` (composite scalars) | [Client Prediction](https://docs.colyseus.io/netcode/client-prediction.md#composite--engine-state-predictsim) |
| Your movement inside a physics engine (Rapier/crashcat) | `predict.sim` (engine handle) | [Client Prediction](https://docs.colyseus.io/netcode/client-prediction.md#composite--engine-state-predictsim) |
| Remote players you don't control | `Predict` `lerp` | [Client Prediction](https://docs.colyseus.io/netcode/client-prediction.md#remote-entities) |
| Server-driven ballistics nobody touches | `Predict` `reckon` | [Recipes](https://docs.colyseus.io/netcode/recipes.md) |
| Discrete events your timeline produces (a goal, a kill, a pickup) | `predict.defineEvent` + `ctx.predict` | [Client Prediction](https://docs.colyseus.io/netcode/client-prediction.md#optimistic-events-defineevent) |
| Projectiles you spawn (predicted → authoritative handoff) | `predict.spawns` | [Recipes](https://docs.colyseus.io/netcode/recipes.md#predicted-projectiles-predictspawns) |
| Hitscan against others (instantaneous, server-owned target) | `allowRewindState` + `rewind.lastSeenBy` | [Lag Compensation](https://docs.colyseus.io/netcode/lag-compensation.md) |

## Read in order

New to prediction? Read top to bottom. Each page builds on the one before it:

- [Server Input & Timestep](https://docs.colyseus.io/netcode/server-input.md)
- [Client Prediction](https://docs.colyseus.io/netcode/client-prediction.md)
- [Lag Compensation](https://docs.colyseus.io/netcode/lag-compensation.md)
- [Determinism & The Contract](https://docs.colyseus.io/netcode/determinism.md)
- [Recipes](https://docs.colyseus.io/netcode/recipes.md)

## Runnable reference

The [**Prediction Playground**](https://prediction-colyseus.vercel.app/) covers this whole section as twelve small labs, each isolating one concept. Rollback and reconciliation, the interpolation modes, dead reckoning, lag compensation, optimistic events, predicted spawns, composite worlds. Every lab has a latency slider and visualizations of the SDK internals (server ghosts, pending-input chips, rewind markers). Each also shows the SDK-facing code it runs. The [source is on GitHub](https://github.com/colyseus/prediction-playground).

### Premium demos

The playground isolates each concept. These {premiumDemos.length} prototypes combine them: authoritative server, client prediction, smoothed remotes and lag compensation running as one stack. Each is playable in the browser.

The set is actively expanding, with new prototypes and with more engine ports of the existing ones. Air Hockey already ships Godot and Unity clients alongside its Three.js build.

> **Note:**
>
> Coming from the manual approach? The [Phaser tutorial](https://docs.colyseus.io/learn/tutorial/phaser/linear-interpolation.md) builds prediction, interpolation, and a fixed tick rate **by hand** to teach the concepts. This section documents the built-in 0.18 API that does the same work for you.

---
Source: https://docs.colyseus.io/netcode


# Client Prediction & Reconciliation

This page is the **client half** of the netcode stack. Send input, predict your own entity, reconcile to the server's authoritative state, and smooth the entities you don't control. The matching server half lives in [Server Input & Timestep](https://docs.colyseus.io/netcode/server-input.md).

> **Note:**
>
> **Available in Colyseus 0.18+** across the official SDKs. Pick your SDK inside each example below. The GameMaker and C ports expose the same surface. Building with React? `@colyseus/react` wraps these APIs as [netcode hooks](https://docs.colyseus.io/getting-started/react.md#netcode-hooks-colyseus-018).

## At a glance

**TypeScript**

```ts
import { Predict } from "@colyseus/sdk";
import { applyInput } from "./shared/applyInput";   // SAME function the server runs

const predict = Predict.get(room, { mode: "lerp", delay: 100 });

// Remote players: render 100ms in the past, interpolated between snapshots.
predict.attachAll("players", { mode: "lerp", fields: ["x", "y"] });

// Local player: the input handle is the ONLY thing that stages + sends.
const input = room.input({ type: MoveInput });
const me = predict.reconciler(self, {
  input,                                     // every scalar field of `self` mirrors by default
  step: (ctx, s, cmd) => applyInput(s, cmd, LEVEL, ctx.dt),
  smoothMs: 65,
});

function frame(now) {                      // pass the rAF timestamp through
  const n = predict.tick(now);             // fixed input steps due this frame
  for (let i = 0; i < n; i++) {
    input.data.moveX = moveX();            // stage the wire input
    input.data.jump = jump();
    input.send();                          // transmit + buffer, the reconciler observes
  }
  for (const [, p] of room.state.players) {
    draw(predict.value(p, "x"), predict.value(p, "y"));  // ONE read idiom, local + remote
  }
  requestAnimationFrame(frame);
}
```

**C#**

```cs
using Colyseus.Predict;

var predict = Predict.Get(room, new PredictGetOptions { Mode = PredictMode.Lerp, Delay = 100 });

// Remote players: render 100ms in the past, interpolated between snapshots.
predict.AttachAll("players", new AttachOptions { Mode = PredictMode.Lerp, Fields = new[] { "x", "y" } });

// Local player: the input handle is the ONLY thing that stages + sends.
var cmd = new MoveInput();
var input = room.Input(cmd);
var me = predict.Reconciler(self, new ReconcilerOptions<Player, MoveInput> {
    Input = input,                                 // every scalar field of `self` mirrors by default
    SmoothMs = 65,
    Step = (ctx, s, c) => ApplyInput(s, c, LEVEL, ctx.Dt),  // SAME function the server runs
});

void Update() {                            // once per render frame
    int steps = predict.Tick();            // fixed input steps due this frame
    for (int i = 0; i < steps; i++) {
        cmd.moveX = MoveX();               // stage the wire input
        cmd.jump = Jump();
        input.Send();                      // transmit + buffer, the reconciler observes
    }
    Draw(me.Value("x"), me.Value("y"));    // your entity: the reconciled read
    // remotes: predict.Value(p, "x"), the smoothed read
}
```

**Lua**

```lua
local Predict = require 'colyseus.predict.predict'

local predict = Predict.get(room)

-- Remote players: interpolated between snapshots, 100ms in the past (the default delay).
predict:attach_all("players", { x = "lerp", y = "lerp" })

-- Local player: the input handle is the ONLY thing that stages + sends.
local input = room:input()
local me = predict:reconciler(self_player, {
  input = input,
  fields = { "x", "y", "vx", "vy" },        -- the fields the step touches
  smooth_ms = 65,
  -- the SAME function the server runs
  step = function(ctx, s, cmd) apply_input(s, cmd, LEVEL, ctx.dt) end,
})

function update(self, dt)                   -- once per render frame
  local steps = predict:tick()              -- fixed input steps due this frame
  for _ = 1, steps do
    input.data.moveX = move_x()             -- stage the wire input
    input.data.jump = jump()
    input:send()                            -- transmit + buffer, the reconciler observes
  end
  draw(me:value("x"), me:value("y"))        -- your entity: the reconciled read
  -- remotes: predict:value(p, "x"), the smoothed read
end
```

**Haxe**

```haxe
import io.colyseus.predict.Predict;

var predict = Predict.get(room, { mode: "lerp", delay: 100 });

// Remote players: render 100ms in the past, interpolated between snapshots.
predict.attachAll("players", { mode: "lerp", fields: ["x", "y"] });

// Local player: the input handle is the ONLY thing that stages + sends.
var input = room.input({ type: MoveInput });
var cmd = input.data;
var me = predict.reconciler(self, {
    input: input,
    fields: ["x", "y", "vx", "vy"],         // the fields the step touches
    smoothMs: 65,
    // the SAME function the server runs
    step: (ctx, s, inp) -> applyInput(s, inp, LEVEL, ctx.dt),
});

function frame() {                          // once per render frame
    var steps = predict.tick();             // fixed input steps due this frame
    for (_ in 0...steps) {
        cmd.moveX = moveX();                // stage the wire input
        cmd.jump = jump();
        input.send();                       // transmit + buffer, the reconciler observes
    }
    draw(me.value("x"), me.value("y"));     // your entity: the reconciled read
    // remotes: predict.value(p, "x"), the smoothed read
}
```

**GDScript**

```gdscript
var predict = Colyseus.Predict.of(room)

# Remote players: interpolated between snapshots, 100ms in the past (the default delay).
# The third argument leaves your own entity out: the reconciler owns it.
predict.attach_all("players", {
    "x": Colyseus.Predict.LERP, "y": Colyseus.Predict.LERP,
}, room.get_session_id())

# Local player: the input handle is the ONLY thing that stages + sends.
var input = room.input()
var me = predict.reconciler(self_player, {
    "input": input,
    "fields": ["x", "y", "vx", "vy"],   # the fields the step touches
    "smooth_ms": 65.0,
    "step": _apply_input,               # the SAME function the server runs
})

func _process(_delta):                  # once per render frame
    var steps: int = predict.tick()     # fixed input steps due this frame
    for i in steps:
        input.data.moveX = move_x()     # stage the wire input
        input.data.jump = jump()
        input.send()                    # transmit + buffer, the reconciler observes
    draw(me.value("x"), me.value("y"))  # your entity: the reconciled read
    # remotes: predict.value(p, "x"), the smoothed read
```

**Dart**

```dart
final predict = Predict.get(room);

// Remote players: interpolated between snapshots, 100ms in the past (the default delay).
predict.attachAll('players',
    config: {'x': PredictMode.lerp, 'y': PredictMode.lerp},
    exceptKey: room.sessionId);   // leave your own entity out: the reconciler owns it

// Local player: the input handle is the ONLY thing that stages + sends.
final input = room.input()!;
final me = predict.reconciler(self,
  input: input,
  fields: const ['x', 'y', 'vx', 'vy'],   // the fields the step touches
  smoothMs: 65,
  step: (ctx, s, cmd) => applyInput(s, cmd, level, ctx.dt), // SAME fn as the server
);

void onFrame() {                          // once per render frame
  Colyseus.pump();                        // decode inbound, deliver events
  final steps = predict.tick();           // fixed input steps due this frame
  for (var i = 0; i < steps; i++) {
    input.data['moveX'] = moveX();        // stage the wire input
    input.data['jump'] = jump();
    input.send();                         // transmit + buffer, the reconciler observes
  }
  draw(me.value('x'), me.value('y'));     // your entity: the reconciled read
  // remotes: predict.value(p, 'x'), the smoothed read
}
```

The reconciler is a pure **observer**: it watches the handle's sends and predicts each one. You never feed input to the reconciler directly. The frame driver runs `predict.tick()`, sends that many inputs through the handle, and everything downstream reacts. For taps and edges that must land on exactly one step, see [buffer, then consume](https://docs.colyseus.io/netcode/recipes.md#taps-between-steps-buffer-then-consume).

> **Warning:**
>
> **Send before you read.** Within a frame, run the send loop right after `predict.tick()`, then read render values. A `predict.value()` read between `tick()` and the sends is one step stale (the SDK warns once).

## `room.input(options)`

Returns the per-room [`InputHandle`](#inputhandle-reference): the single surface that stages and sends input. Created once: later calls return the same handle.

**TypeScript**

```ts
const input = room.input({
  type: MoveInput,          // input schema constructor (matches the server's defineInput)
});
```

**C#**

```cs
var cmd = new MoveInput();      // the instance you stage fields on
var input = room.Input(cmd);
```

**Lua**

```lua
-- the input schema arrives via the join handshake (the server's defineInput)
local input = room:input()
```

**Haxe**

```haxe
var input = room.input({ type: MoveInput });
```

**GDScript**

```gdscript
# takes no options: the schema arrives via the join handshake
var input = room.input()
```

**Dart**

```dart
// null when the server room declares no defineInput()
final input = room.input();
```

- **`type`**: the input schema constructor. Optional when the server called `defineInput()`: the schema then arrives via the join handshake and is used automatically. An explicit constructor always wins.
- **`mode`**: `"reliable"` (default) or `"unreliable"`. Over plain WebSocket, stay reliable. On a datagram-capable transport, `{ mode: "unreliable", historySize: 4 }` is the recommended rollback setup. Each packet carries the last N inputs as redundancy, so a drop costs nothing and nothing head-of-line blocks. That transport is [WebTransport](https://docs.colyseus.io/server/transport/webtransport.md) alone: experimental, and supported by the JavaScript/TypeScript SDK only. Other SDKs reject `"unreliable"` at construction for now.
- **`historySize`**: unreliable-mode redundancy depth (default 3). Ignored in reliable mode.
- **`renderDelay`**: your remote interp buffer in ms, used for the lag-comp stamp. **Usually omit it**: wiring the handle through `predict.reconciler`/`predict.sim` binds it to the Predict's lerp `delay` automatically. The buffer you render at and the server's rewind instant then come from one number. The binding reads the Predict's *default* `delay` (from `Predict.get` or `setDefaults`) live, not a per-attach `delay`. Any explicit value, `0` included, wins over the binding. In C# the option is a `double?`: leave `InputOptions.RenderDelay` null to bind, and note that assigning `input.RenderDelay` later also counts as explicit.
- **`allowRewind`**: a predicate selecting which inputs carry the lag-comp timestamp. It's a bandwidth trim: stamp only the inputs the server actually rewinds for, e.g. `(d) => d.fire`. Reliable mode only: an unreliable packet stamps its whole redundancy ring or none of it, so the predicate is ignored there. See [Lag Compensation](https://docs.colyseus.io/netcode/lag-compensation.md).

The GDScript handle accepts no options object: `render_delay` is a property, and `input.set_rewind_field("fire")` replaces `allowRewind`.

Stage fields on `input.data`, then `input.send()`, one call per fixed step:

**TypeScript**

```ts
input.data.moveX = 1;
input.data.jump = true;
input.send();
```

**C#**

```cs
cmd.moveX = 1;        // the instance passed to Room.Input()
cmd.jump = true;
input.Send();
```

**Lua**

```lua
input.data.moveX = 1
input.data.jump = true
input:send()
```

**Haxe**

```haxe
input.data.moveX = 1;
input.data.jump = true;
input.send();
```

**GDScript**

```gdscript
input.data.moveX = 1
input.data.jump = true
input.send()
```

**Dart**

```dart
input.data['moveX'] = 1;
input.data['jump'] = true;
input.send();
```

Only declared schema fields ride the wire. Writing an undeclared field does nothing, and with the debug panel active the SDK warns you once per key at `send()`.

The handle also surfaces the server-advertised rates from the handshake: `input.tickRate`, `input.stepSeconds`, `input.stepMs`, `input.patchRate`, `input.subSteps`. Predict at `input.stepSeconds` so your replay stays bit-identical with the server.

> **Warning:**
>
> The server must advertise a fixed rate (via `setFixedTimestep`) for `input.tickRate` to be defined. A robust client asserts it:
> ```ts
> if (input.tickRate === undefined) throw new Error("server did not advertise a fixed tick rate");
> ```
>     The same check ports as `input.TickRate == null` (C#), `input.tick_rate == nil` (Lua), and `input.tickRate == null` (Haxe). The GDScript and Flutter bindings report `0` instead of null when the rate is unadvertised.

## `Predict.get(room, options)`

The entry point for all client-side smoothing and prediction. Create one per room and share the instance. Each `Predict.get` call constructs a fresh, independent `Predict`:

**TypeScript**

```ts
const predict = Predict.get(room, { mode: "lerp", delay: 100 });
```

**C#**

```cs
var predict = Predict.Get(room, new PredictGetOptions { Mode = PredictMode.Lerp, Delay = 100 });
```

**Lua**

```lua
local predict = Predict.get(room, { mode = "lerp", delay = 100 })
```

**Haxe**

```haxe
var predict = Predict.get(room, { mode: "lerp", delay: 100 });
```

**GDScript**

```gdscript
# takes only the room: declare mode/delay per attach
var predict = Colyseus.Predict.of(room)
```

**Dart**

```dart
// takes only the room: declare mode/delay per attach
final predict = Predict.get(room);
```

The options seed the room-wide defaults every attach inherits when it omits an option (`mode`, `delay`, `smoothMs`, `snap`, and a reckon `step`/`substep`). `predict.setDefaults(opts)` changes them later, and `predict.mode` reads the current default mode (`SetDefaults` / `Mode` in C#). A change only reaches attaches made *after* the call, since each attach snapshots what it resolved.

`name` labels the instance in logs and the debug panel, and `predict.name` reads it back (`PredictGetOptions.Name` / `predict.Name` in C#). It defaults to `predict#N`, numbered per process. Only `Predict.get` sets it: `setDefaults` ignores it.

> **Note:**
>
> The construction options object is available in JavaScript, C#, Haxe and Lua. The GDScript and Dart bindings take only the room and declare `mode`/`delay` per attach.

Call `predict.tick(now)` **once per render frame**, passing the rAF timestamp. It returns the number of fixed input steps due this frame. It also drives everything it owns: reconcile on new acks, correction decay, remote smoothing, event settlement.

`now` is optional in every SDK. Omit it and the room clock is read for you, which is what the examples above do. That saves picking a platform clock that may not share the SDK's epoch. Pass it in JavaScript anyway: the rAF timestamp is the exact frame time, on the same axis as the default.

### Remote entities

For entities you **don't** control, attach smoothing. `attachAll` covers every entry of a collection; `attach` a single instance:

**TypeScript**

```ts
predict.attachAll("players", { mode: "lerp", fields: ["x", "y"] });
```

**C#**

```cs
// one options set spread over a list of fields:
predict.AttachAll("players", new AttachOptions { Mode = PredictMode.Lerp, Fields = new[] { "x", "y" } });

// or a per-field map, each field picking its own mode:
predict.AttachAll("players", new AttachConfig {
    ["x"] = PredictMode.Lerp, ["y"] = PredictMode.Lerp,
});

// per-field options instead of a bare mode:
predict.AttachAll("players", new AttachConfig {
    ["x"] = new PredictFieldOptions { Mode = PredictMode.Lerp, Delay = 100 },
});
```

**Lua**

```lua
-- one config spread over a list of fields:
predict:attach_all("players", { mode = "lerp", fields = { "x", "y" } })

-- or a per-field map, each field picking its own mode:
predict:attach_all("players", { x = "lerp", y = "lerp" })

-- per-field options instead of a bare mode:
predict:attach_all("players", { x = { mode = "lerp", delay = 100 } })
```

**Haxe**

```haxe
// one config spread over a list of fields:
predict.attachAll("players", { mode: "lerp", fields: ["x", "y"] });

// or a per-field map, each field picking its own mode:
predict.attachAll("players", { x: "lerp", y: "lerp" });

// per-field options instead of a bare mode:
predict.attachAll("players", { x: { mode: "lerp", delay: 100 } });
```

**GDScript**

```gdscript
# the third argument skips your own entity: the reconciler owns it
predict.attach_all("players", {
    "x": Colyseus.Predict.LERP, "y": Colyseus.Predict.LERP,
}, room.get_session_id())

# per-field options instead of a bare mode:
predict.attach_all("players", {
    "x": { "mode": Colyseus.Predict.LERP, "delay": 100 },
})
```

**Dart**

```dart
predict.attachAll('players',
    config: {'x': PredictMode.lerp, 'y': PredictMode.lerp},
    exceptKey: room.sessionId);   // skip your own entity: the reconciler owns it

// per-field options instead of a bare mode:
predict.attachAll('players',
    config: {'x': FieldOptions(mode: PredictMode.lerp, delay: 100)});
```

In C#, Lua, and Haxe the collection attaches in full, your own entity included. The reconciler's overlay wins for your own entity. The GDScript and Dart bindings take an except-key to leave it out explicitly.

In C#, `AttachOptions` extends `PredictFieldOptions` with `Fields`, a reckon `Step` and a `Substep`, so one object carries the field list and the options. `Attach(instance, options)` takes the same object for a single instance. An omitted `Mode` follows the Predict's default, and `Reckon` needs a `Step` from the options or from the Predict. Fields the instance's type doesn't declare are skipped, and a call that matches no field warns once.

Read the smoothed value with `predict.value(entity, field)`. Smoothing modes:

| Mode | Behaviour | Use for |
|---|---|---|
| `lerp` | Interpolate snapshots at `now − delay`: smooth, lagged, faithful | Remote players |
| `extrapolate` | Forecast forward: live, can overshoot | Low-latency-critical movers |
| `damped` | Ease toward the latest value: never exact, never jittery | Cosmetic entities |
| `reckon` | Dead-reckon forward via a step fn | Server-driven AI / ballistics |
| `raw` | Unsmoothed (the live synced value) | Debugging |

Three per-attach options are worth knowing:

- **`smoothMs`**: an output-smoothing time constant in milliseconds. On `damped` and `extrapolate` it is the chase rate (default 50). On `lerp` it arms a display-only output spring (default 0, exact interpolation): see [Rough snapshot streams](https://docs.colyseus.io/netcode/recipes.md#rough-snapshot-streams-smoothms).
- **`snap`**: a value-space threshold past which a jump is treated as a teleport: smoothing resets and the entity pops instead of gliding. Use it for respawns, blinks, warps.
- **`angle`**: treat the field as radians, interpolating over the shortest arc. Attach angular fields in a separate call from linear ones.

### `reconciler`: your own entity (flat fields)

Active prediction for **one** entity you control, mirrored off the instance's scalar fields:

**TypeScript**

```ts
const me = predict.reconciler(self, {
  input,
  step: (ctx, state, cmd) => applyInput(state, cmd, LEVEL, ctx.dt),
  smoothMs: 65,
});
```

**C#**

```cs
var me = predict.Reconciler(self, new ReconcilerOptions<Player, MoveInput> {
    Input = input,
    SmoothMs = 65,
    Step = (ctx, state, cmd) => ApplyInput(state, cmd, LEVEL, ctx.Dt),
});
```

**Lua**

```lua
local me = predict:reconciler(self_player, {
  input = input,
  fields = { "x", "y", "vx", "vy" },
  smooth_ms = 65,
  step = function(ctx, state, cmd) apply_input(state, cmd, LEVEL, ctx.dt) end,
})
```

**Haxe**

```haxe
var me = predict.reconciler(self, {
    input: input,
    fields: ["x", "y", "vx", "vy"],
    smoothMs: 65,
    step: (ctx, state, cmd) -> applyInput(state, cmd, LEVEL, ctx.dt),
});
```

**GDScript**

```gdscript
var me = predict.reconciler(self_player, {
    "input": input,
    "fields": ["x", "y", "vx", "vy"],
    "smooth_ms": 65.0,
    "step": _apply_input,     # func(ctx, state, cmd)
})
```

**Dart**

```dart
final me = predict.reconciler(self,
  input: input,
  fields: const ['x', 'y', 'vx', 'vy'],
  smoothMs: 65,
  step: (ctx, state, cmd) => applyInput(state, cmd, level, ctx.dt),
);
```

- `step(ctx, state, cmd)`: the deterministic step function, **shared with the server**. `cmd` is the buffered wire input recorded at `send()` (the exact value the server decodes), so lossy wire fields (a quantized angle) reconcile by construction. Keep everything the step reads on the input schema.
- `fields`: optional, and usually best omitted. Every scalar field of the instance's schema is then mirrored, which is the right default. Pass an explicit subset only to exclude scalars deliberately. With the dev panel active, the SDK warns once if the step touches a field the list excludes. Numeric fields get smooth error correction; non-numeric fields (e.g. `grounded`) are copied verbatim on reconcile.
- `smoothMs`: how long a reconcile correction takes to fade, as a time constant in milliseconds (a correction fades ~63% per `smoothMs`, ~95% by 3×). Defaults to one server patch interval; `0` applies corrections instantly.
- `snap`: teleport threshold in world units, the active-controller mirror of the [per-attach `snap`](https://docs.colyseus.io/netcode/recipes.md#teleports--respawns-snap). A reconcile correction past it **pops** to the corrected pose instead of gliding across the map, and doesn't count toward divergence telemetry.
- `warnOnDivergence`: drift tolerance in world units. The SDK warns in the console when the **persistent** reconcile-correction EMA crosses it: a determinism break, not jitter. The telemetry behind it (`me.drift.ema` / `me.drift.peak`) runs while watched (this option set, or the dev panel active). See [Diagnosing divergence vs jitter](https://docs.colyseus.io/netcode/determinism.md#diagnosing-divergence-vs-jitter). Not exposed in the GDScript and Flutter bindings: read the drift telemetry directly (`me.drift_ema` in GDScript, `me.drift.ema` in Dart).

One-shot effects inside `step` need care, because a step can replay several times during rollback. Three tools, split by what the one-shot *is*:

- A **value** replay can't re-derive (an RNG roll, a collision outcome) → freeze it with [`ctx.memo`](#ctxmemo-freeze-a-value-replay-cant-re-derive).
- A discrete **event** that needs settlement (a goal, a kill, a pickup) → declare it with [`ctx.predict`](#optimistic-events-defineevent).
- Fire-and-forget **presentation** (a sound, particles, a timestamp) → a plain `if (!ctx.isReplay) { … }` branch. The branch *is* the idiom; there is deliberately no wrapper API for it.

Lifecycle is automatic: on reconnect the SDK resets the input handle and observing controllers follow (they poll `input.epoch`), and `snap` absorbs respawn-sized jumps. Call `me.reset()` yourself only for discontinuities the library can't see: a map swap, or in-flight inputs the app knows are void (a death).

### Composite & engine state: `predict.sim`

When your inputs affect **more** than one flat-field entity (a paddle *and* the puck it strikes, or an opaque physics engine), use `predict.sim`. You own a `world` (any object) and the SDK runs the same predict → adopt-on-ack → replay loop over it.

**Composite scalars** need no callbacks: put the decoded schema instances themselves in `world` and they are **auto-bound**. The SDK replaces them in place with plain scalar mirrors that it seeds, re-adopts from server truth on every ack, and smooths:

**TypeScript**

```ts
const me = predict.sim({
  input,
  world: {
    paddle: player,             // decoded schema instance ⇒ auto-bound
    puck:   room.state.puck,    // ⇒ auto-bound (x, y, vx, vy)
  },
  step: (ctx, w, cmd) => stepWorld(w, cmd, ctx.dt),   // the SAME fn the server runs
  smoothMs: 65,
});

draw(predict.value(player, "x"), predict.value(room.state.puck, "x"));  // one read idiom
aim(me.world.paddle);           // raw predicted mirror for game logic
```

**C#**

```cs
// your world: any class whose entries hold the decoded instances
var me = predict.Sim(new SimReconcilerOptions<HockeyWorld, MoveInput> {
    Input = input,
    World = new HockeyWorld { paddle = player, puck = room.State.puck },  // ⇒ auto-bound
    Step = (ctx, w, cmd) => StepWorld(w, cmd, ctx.Dt),   // the SAME fn the server runs
    SmoothMs = 65,
});

Draw(predict.Value(player, "x"), predict.Value(room.State.puck, "x"));  // one read idiom
```

**Lua**

```lua
local me = predict:sim({
  input = input,
  world = {
    paddle = player,            -- decoded schema instance ⇒ auto-bound
    puck   = room.state.puck,   -- ⇒ auto-bound (x, y, vx, vy)
  },
  step = function(ctx, w, cmd) step_world(w, cmd, ctx.dt) end,  -- the SAME fn the server runs
  smooth_ms = 65,
})

draw(predict:value(player, "x"), predict:value(room.state.puck, "x"))  -- one read idiom
```

**Haxe**

```haxe
// your world: any class whose entries hold the decoded instances
var me = predict.sim({
    input: input,
    world: new HockeyWorld(player, room.state.puck),  // entries ⇒ auto-bound
    step: (ctx, w, cmd) -> stepWorld(w, cmd, ctx.dt), // the SAME fn the server runs
    smoothMs: 65,
});

draw(predict.value(player, "x"), predict.value(room.state.puck, "x"));  // one read idiom
```

**GDScript**

```gdscript
var me = predict.sim({
    "input": input,
    "world": { "paddle": player, "puck": puck },  # decoded instances ⇒ auto-bound
    "step": _step_world,     # the SAME fn the server runs
    "smooth_ms": 65.0,
})

draw(predict.value(player, "x"), predict.value(puck, "x"))  # one read idiom
```

**Dart**

```dart
final me = predict.sim(
  input: input,
  options: SimOptions(
    parts: [SimPart('paddle', player), SimPart('puck', puck)],  // ⇒ auto-bound
    smoothMs: 65,
  ),
  step: (ctx, world, cmd) {
    stepWorld(world.part('paddle')!, world.part('puck')!, cmd, ctx.dt);
  },
);

draw(predict.value(player, 'x'), predict.value(puck, 'x'));  // one read idiom
```

`step` mutates the mirrors, never the decoded tree. Bound entities render through the same `predict.value(instance, field)` read as remotes. One caveat: bound sources are pinned at construction. If the server *replaces* an instance (`state.puck = new Puck()`), recreate the controller.

For an **opaque engine** (Rapier), the `world` is the solver + body handle, and you supply the two callbacks auto-binding can't derive:

```ts
const me = predict.sim({
  input,
  world: { world, body },
  step:  (ctx, w, cmd) => { applyInput(w.body, cmd); w.world.step(); },   // timestep = ctx.dt
  adopt: (w) => { w.body.setTranslation({ x: self.x, y: self.y }, true); },
  pose:  (w) => { const t = w.body.translation(); return { x: t.x, y: t.y }; },
});
```

> **Note:**
>
> The opaque-engine face (`adopt` + `pose`) is JavaScript-only. The ports run `sim` over auto-bound schema mirrors instead. The C# (`Adopt`) and Flutter bindings additionally accept `adopt` for opaque extras, with poses still derived from bound parts.

- `adopt(world)`: seed the server's authoritative scalars into the opaque entries on each ack, before replay. Runs after any bound entries' auto-adopt, so it may derive from just-adopted mirrors.
- `pose(world)`: read the opaque entries into a flat render pose; smoothing operates on these numbers in addition to the bound parts' auto-derived `"part.field"` fields.

> **Warning:**
>
> `adopt` reseeds **scalars**; replay re-derives the rest. Engine-internal non-scalar state (contact caches, sleeping islands, solver accumulators) is **not** rolled back across reconcile. Reseed every scalar your sim depends on (position **and** velocity).

## Reading values

Three reads, split by purpose:

- **Rendering**: `predict.value(instance, field)`, the smoothed render read. One idiom for everything: passively-smoothed remotes, your reconciled entity, sim-bound instances. Falls back to the raw synced value before spawn / after dispose. The batch form `predict.read(instance, fields, out?)` (JavaScript and C#, as `predict.Read(instance, fields, output)` into a `double[]`) reads every listed field into one object, the client mirror of the server's [`seen.read`](https://docs.colyseus.io/netcode/lag-compensation.md#rewindview). On per-frame paths, pass a reused scratch and hoist the `fields` array; extra scratch properties are left untouched.
- **Game logic**: `me.state` (reconciler) / `me.world` (sim), the exact predicted state with no smoothing offset. A hit test against the smoothed render value would lag the truth by the correction offset.
- **A moment in time**: `predict.valueAt(instance, field, time)`, a remote entity reckoned at an arbitrary server-time instant. Sample remotes at `ctx.reckonTime` inside your step and your client-side hit verdict matches the server's lag-comp rewind by construction. See [Lag Compensation](https://docs.colyseus.io/netcode/lag-compensation.md). The batch form `predict.readAt(instance, fields, time, out?)` (JavaScript and C#, as `predict.ReadAt(instance, fields, time, output)`) runs one forward reckon integration per entity instead of one per field.

## Optimistic events: `defineEvent`

A predicted timeline produces discrete **events** (a goal, a kill, a pickup) that deserve instant feedback but need server settlement. A channel owns one event type end-to-end:

**TypeScript**

```ts
const goals = predict.defineEvent<Team>({
  onPredict: (team) => { celebrate(team); hidePuck(); },   // fires immediately, ~RTT early
  onReject:  ()     => showPuck(),                         // the prediction was wrong: undo
});

// inside the reconciler step (fires on the LIVE step only, never on rollback replay):
if (crossedGoalLine) ctx.predict(goals, scoredBy);

// settlement (the authoritative broadcast):
room.onMessage("score", () => goals.confirm());
```

**C#**

```cs
var goals = predict.DefineEvent(new PredictedEventChannelOptions<string> {
    OnPredict = team => { Celebrate(team); HidePuck(); },  // fires immediately, ~RTT early
    OnReject  = _    => ShowPuck(),                        // the prediction was wrong: undo
});

// inside the reconciler step (fires on the LIVE step only, never on rollback replay):
if (crossedGoalLine) ctx.Predict(goals, scoredBy);

// settlement (the authoritative broadcast):
room.OnMessage<Dictionary<string, object>>("score", _ => goals.Confirm());
```

**Lua**

```lua
local goals = predict:define_event({
  on_predict = function(team) celebrate(team) end,  -- fires immediately, ~RTT early
  on_reject  = function() show_puck() end,          -- the prediction was wrong: undo
})

-- inside the reconciler step (fires on the LIVE step only, never on rollback replay):
if crossed_goal_line then ctx:predict(goals, scored_by) end

-- settlement (the authoritative broadcast):
room:on_message("score", function() goals:confirm() end)
```

**Haxe**

```haxe
var goals = predict.defineEvent({
    onPredict: (team) -> { celebrate(team); hidePuck(); },  // fires immediately, ~RTT early
    onReject:  (_)    -> showPuck(),                        // the prediction was wrong: undo
});

// inside the reconciler step (fires on the LIVE step only, never on rollback replay):
if (crossedGoalLine) ctx.predict(goals, scoredBy);

// settlement (the authoritative broadcast):
room.onMessage("score", (_) -> goals.confirm(null));
```

**GDScript**

```gdscript
var goals = predict.define_event({
    "on_predict": func(team): celebrate(team),   # fires immediately, ~RTT early
    "on_reject":  func(_key): show_puck(),       # the prediction was wrong: undo
})

# inside the reconciler step (fires on the LIVE step only, never on rollback replay):
if crossed_goal_line: ctx.predict(goals, scored_by)

# settlement (the authoritative broadcast):
room.message_received.connect(func(type, _data):
    if type == "score": goals.confirm())
```

**Dart**

```dart
final goals = predict.defineEvent(
  onPredict: (team) => celebrate(team),   // fires immediately, ~RTT early
  onReject:  (_)    => showPuck(),        // the prediction was wrong: undo
);

// inside the reconciler step (LIVE step only; a string key addresses the entry):
if (crossedGoalLine) ctx.predict(goals, 'goal:${ctx.tick}');

// settlement (the authoritative broadcast):
room.onMessage('score').listen((_) => goals.confirm());
```

Settlement is automatic where it can be. A sim-born prediction auto-rejects once the server has processed `graceTicks` (default 10) past its birth step without a `confirm()`. The server ran the very timeline that predicted the event, and stayed silent. UI-born predictions (`goals.predict(payload)` called outside the sim) can't count ticks, so they fall back to a wall-clock TTL (`ttlMs`, default `max(2×rtt, 600ms)`).

Four more options:

- **`label`**: a diagnostic name. Nothing resolves by it; it names the channel in warnings, which starts to matter once a room has several.
- **`uniqueBy`**: gives entries identity: dedupe while pending, and address one among several on confirm/reject. Available in C#, Lua, and Haxe; the GDScript and Flutter channels use explicit string keys instead.
- **`cooldownMs`**: rate-limits feedback channel-wide.
- **`onConfirm`**: available but usually empty; the optimistic feedback already played.

Flag-shaped consumers can skip callbacks entirely and derive from `goals.has(key)` each frame: `has` is available everywhere except the GDScript binding.

### Confirming from state: `confirmOn`

> **Note:**
>
> `confirmOn` is available in JavaScript and C#. In the other SDKs, wire the settlement manually: listen for the state change with your schema callbacks and call `channel.confirm(key)`. The grace-tick auto-reject behaves identically.

A broadcast is one settlement signal; more often the signal is **state itself**: a crate's `alive` flipping, a banana joining or leaving its collection. Declare that shape and the channel wires the schema listeners for you (and tears them down with the channel):

**TypeScript**

```ts
const breaks = predict.defineEvent<string>({
  confirmOn: { collection: "crates", field: "alive", equals: false },
});

// inside the step:
if (smashed) ctx.predict(breaks, crateId);

// render (flag-shaped): derive, no callbacks needed
const broken = !crate.alive || breaks.has(crateId);
```

**C#**

```cs
var breaks = predict.DefineEvent(new PredictedEventChannelOptions<string> {
    ConfirmOn = new ConfirmOn { Collection = "crates", Field = "alive", Equals = false },
});

// inside the step:
if (smashed) ctx.Predict(breaks, crateId);

// render (flag-shaped): derive, no callbacks needed
bool broken = !crate.alive || breaks.Has(crateId);
```

**Lua**

```lua
-- not available: call channel:confirm(key) from a schema callback watching `alive`
```

**Haxe**

```haxe
// not available: call channel.confirm(key) from a schema callback watching `alive`
```

**GDScript**

```gdscript
# not available: call channel.confirm(key) from a schema callback watching `alive`
```

**Dart**

```dart
// not available: call channel.confirm(key) from a schema callback watching `alive`
```

When a child's `field` becomes `equals`, the entry keyed by that child's **collection key** confirms, so key your entries by collection key. Two membership variants complete the set:

```ts
confirmOn: { collection: "bananas", event: "remove" }              // the removal confirms its key
confirmOn: { collection: "bananas", event: "add", mine: "owner" }  // OUR arrival settles the pending drop
```

```cs
ConfirmOn = new ConfirmOn { Collection = "bananas", Event = "remove" }                 // the removal confirms its key
ConfirmOn = new ConfirmOn { Collection = "bananas", Event = "add", Mine = "owner" }   // OUR arrival settles the pending drop
```

A predicted **spawn** can't know the key the server will assign, so `add` settles keyless. The channel holds a single anonymous pending entry. The `mine` property (a field name compared against your `sessionId`) keeps a remote player's spawn from confirming yours. All three forms are plain data: no listener plumbing, nothing to unsubscribe. Signals that don't fit (a broadcast, entry keys that aren't collection keys) stay one manual `confirm()` line, as above.

### The other player's event: `onUnpredicted`

A `confirm()` for an event nobody predicted settles nothing: that's a **remote actor's** event arriving (their pickup, their goal). `onUnpredicted(key)` is that branch: play the feedback `onPredict` skipped.

```ts
const boxPickups = predict.defineEvent<string>({
  confirmOn:     { collection: "itemBoxes", field: "active", equals: false },
  onPredict:     () => { hideBox(); startRoulette(); },          // ours, instantly
  onUnpredicted: (id) => pickupBurstAt(id),                      // theirs, on arrival
});
```

> **Note:**
>
> `onUnpredicted` exists in the C#, Lua, Haxe, and Flutter ports (not GDScript). The `confirmOn` wiring shown here is available in JavaScript and C#: the other ports call `confirm()` from their own state callbacks.

Branch on the callbacks: `onConfirm` means *we* predicted it, `onUnpredicted` means we didn't. Never branch on a `has()` read racing a confirm: the entry is removed *before* `onConfirm` fires.

### `ctx.memo`: freeze a value replay can't re-derive

`ctx.predict` handles one-shot *events*; `ctx.memo` handles one-shot *values* the sim itself consumes: a lag-comp'd collision outcome, an RNG roll, a server-assigned id. `compute` runs exactly once, on the live step; every replay of that step gets the frozen value back:

**TypeScript**

```ts
const hit = ctx.memo(() => collide(state, ctx.reckonTime));
if (hit) state.vx = hit.vx;   // re-applied identically on every replay
```

**C#**

```cs
var hit = ctx.Memo(() => Collide(state, ctx.ReckonTime));
if (hit != null) state.vx = hit.Vx;   // re-applied identically on every replay
```

**Lua**

```lua
local hit = ctx:memo(function() return collide(state, ctx.reckon_time) end)
if hit ~= nil then state.vx = hit.vx end   -- re-applied identically on every replay
```

**Haxe**

```haxe
var hit = ctx.memo(() -> collide(state, ctx.reckonTime));
if (hit != null) state.vx = hit.vx;   // re-applied identically on every replay
```

**GDScript**

```gdscript
# keyed and numeric-only: memo_vec freezes a tuple like [hit, vx, vy]
var verdict: Array = ctx.memo_vec("collide", func(): return _collide(state, ctx.reckon_time))
if not verdict.is_empty() and verdict[0] != 0.0: state.vx = verdict[1]
```

**Dart**

```dart
// keyed and numeric-only: memoVec freezes a tuple like [hit, vx, vy]
final verdict = ctx.memoVec('collide', () => collide(state, ctx.reckonTime));
if (verdict.isNotEmpty && verdict[0] != 0) state.vx = verdict[1];
```

Call `memo` on every step and let `compute` decide the value: return `undefined` for "nothing" (stored sparsely). Need more than one memo per step? Disambiguate with a key: `ctx.memo("collide", …)`. The key-less form is **one shared slot per step**. Two calls landing on that slot (two key-less calls, or a repeated key) silently corrupt replay with one frozen value for both. With the dev panel active, the SDK warns on the collision. Prefer reconciled `fields` when the value **is** derivable by re-running the step: that replays *and* self-corrects for free. The key-less shared slot exists in TypeScript, C#, Lua, and Haxe; the Godot and Flutter bindings always take a key and freeze numbers (`memo_vec`/`memoVec` for small tuples).

C# has no `undefined`, so `ctx.Memo<T>` returns `default` when the live step stored nothing under the key. For a value type, that reads the same as a memoized zero. Calling `Memo` on every step avoids the case: return a nullable type such as `int?`, with `null` for "nothing". When a memo has to sit behind a branch, use `ctx.TryMemo`. A correction can send a replay down that branch on a step the live run skipped, and `TryMemo` then returns `false` instead of a zero that looks real. A stored `null` counts as a value, and `compute` never runs on a replay in either form.

```cs
if (state.x >= LootZoneX) {
    // a correction can bring a replay here on a step the live run never reached
    if (ctx.TryMemo("loot", () => rng.Next(0, 6), out int lootIndex)) {
        state.lootIndex = lootIndex;   // Memo<int> would return 0 here, a real item
    }
}
```

## `room.clock`

Your window into server time and connection latency: what time it is on the server, and how long your packets take to get there. It's always safe to call: `room.clock` is never `undefined` and no method needs optional chaining or a fallback. Rooms that use input (`defineInput()`) get a real clock-sync estimator during the join handshake; other rooms keep a stub that reads from your local clock. Three timelines, split by what you compare against:

- **`clock.now()`**: local monotonic ms. For **self-imposed relative gates**: a cooldown or fire-rate *you* started (`now() - lastFired >= COOLDOWN_MS`). Needs no clock sync, immune to offset jitter.
- **`clock.serverNow()`**: estimated server clock (ms since room start). For **server-stamped absolute deadlines**: invuln windows, respawn timers, hit stamps (anything the server wrote a timestamp for).
- **`clock.renderNow()`**: `serverNow()` on a slew-limited **render** timeline (default on for drawing via `Predict`). Strips the per-patch offset wobble so dead-reckoned remotes don't jitter at speed. Never use it for hit stamps.

Latency accessors: `clock.rtt()`, `clock.smoothedRtt()` (preferred for forward-prediction), `clock.jitter()` (connection quality), `clock.lastServerTime()` (server time of the newest patch: `serverNow() − lastServerTime()` is the snapshot's age).

Bringing your own sync algorithm? Swap it in right after joining: `room.clock = new MyClock()`. Implement `renderNow()` too: returning `serverNow()` is all it takes if your clock has no smoothing of its own.

## `InputHandle` reference

Member names follow each SDK's casing convention: PascalCase in C# (`Send()`, `LastProcessed`, `TickRate`), snake_case in Lua and GDScript (`last_processed`, `tick_rate`), camelCase in Haxe and Dart.

| Member | Role |
|---|---|
| `data` | Mutable schema instance: stage fields, then `send()` |
| `send()` | Encode and transmit **one** input (body-less frame when unchanged); returns its seq |
| `onSend(cb)` | Synchronous post-send hook: how reconcilers observe the stream; returns an unsubscribe |
| `mode` | The channel: `"reliable"` or `"unreliable"` |
| `reset()` | Drop encoder + seq state and bump `epoch`. The SDK calls it on the reconnect path itself. Call it only for scene transitions the library can't see |
| `epoch` | Monotonic reset counter: observing reconcilers poll it and self-reset when it moves (compare with `!==`, never `+1`) |
| `at(seq)` | The buffered input sent as `seq`, for replay (reused instance: read synchronously) |
| `reckonTimeAt(seq)` | The **raw** reckon stamp on that seq (`0` when unstamped). `ctx.reckonTime` is the resolved read |
| `lastProcessed` | Last input seq the server acked **processing** (the canonical reconcile ack) |
| `sentCount` | Inputs sent, the latest assigned seq |
| `pendingCount` | In-flight (unacked) inputs = `sentCount − lastProcessed` |
| `replayBufferSize` | Capacity of the `at(seq)` replay ring |
| `tickRate` / `stepSeconds` / `stepMs` | Server-advertised fixed step |
| `patchRate` | Server state-patch interval (ms), the correction cadence |
| `subSteps` / `subStepSeconds` / `subStepMs` | Physics sub-steps per input tick |

The Godot and Flutter bindings do not expose `at(seq)`, `onSend`, `reckonTimeAt`, `mode`, or `replayBufferSize`, because the native core owns the replay ring internally.

> **Note:**
>
> **Dev tooling:** `import "@colyseus/sdk/debug"` (a side-effect import, JavaScript SDK only) enables the in-page dev panel. The panel shows per-reconciler drift telemetry, profiles, and connection internals. It's a no-op in production builds that skip the import.

## Next

→ [Lag Compensation](https://docs.colyseus.io/netcode/lag-compensation.md): make the server judge your shots against what you saw.

→ [Determinism & The Contract](https://docs.colyseus.io/netcode/determinism.md): the rules that keep prediction matching the server.

---
Source: https://docs.colyseus.io/netcode/client-prediction


# Determinism & The Contract

Client prediction only matches the server if **both run the same simulation**. None of the rules below is hard to follow, but each is easy to break by accident. The resulting bugs look mysterious: rubber-banding, re-firing sounds, hits that don't land. This page collects the rules and the symptom each break produces. Read it alongside [Client Prediction](https://docs.colyseus.io/netcode/client-prediction.md) and [Server Input](https://docs.colyseus.io/netcode/server-input.md).

> **Note:**
>
> **Available in Colyseus 0.18+.**

## The contract

None of these is optional. Break one and prediction drifts or hits stop registering:

1. **One `input.send()` per fixed step.** `predict.tick()` returns how many fixed steps are due this frame; stage and send exactly that many inputs. Every `send()` transmits one input (a body-less frame when nothing changed), so the predicted set equals the server-applied set. Don't send per render frame, and don't skip sends while predicting movement.

2. **Everything the step reads must live on the input schema.** `step` receives the buffered *wire* input (`input.at(seq)`), the exact value the server decodes, on the live step and on every replay. State you read from outside the input (a captured variable, a DOM read) won't replay and diverges silently.

3. **Send before you read.** Within a frame: `predict.tick()` → the send loop → render reads. A `predict.value()` read between `tick()` and the sends renders one step stale (the SDK warns once).

4. **One-shot effects never go raw inside `step`.** A step replays 0..N times during rollback. Use `ctx.predict` for events (a sound, a celebration): they fire on the live step only. Use `ctx.memo` for values replay can't re-derive (an RNG roll, a lag-comp'd collision). For fire-and-forget presentation (particles, camera shake), a plain `if (!ctx.isReplay)` branch is itself the idiom.

5. **Inputs must be flat primitives**: no nested schemas or collections in an input.

6. **Input rate = fixed-step rate = server tick.** Change one, change all. Lowering `tickRate` to save bandwidth therefore also lowers the simulation rate, unless you [sub-step](https://docs.colyseus.io/netcode/server-input.md#sub-stepping-high-rate-physics-on-a-low-network-rate): physics can run at `tickRate × subSteps` while the wire stays at `tickRate`.

7. **Lag comp rewinds to the *acting client's* render time, not the server's now.** [`rewind.lastSeenBy(shooterId)`](https://docs.colyseus.io/netcode/lag-compensation.md#rewindlastseenbysessionid) gets the direction right for you.

Two more facts ride the same ack channel, but they're bookkeeping the framework does, not rules you can break. **`lastProcessed`** is the server's consumed count, echoed via the acks: reconcile triggers when it advances. There is no seq field to manage: in `"unreliable"` mode, the framework's own sequence plus the redundant input history make drops harmless. And **`room.clock`** syncs through those same acks, which is why it requires `defineInput()`. Without it the clock is a stub: `serverNow()` falls back to a local monotonic clock, and `rtt` / `lastServerTime` are 0.

## Determinism

Prediction matches the server only if both run the **same** simulation:

- **One shared `step` / `applyInput` function**: a single source of truth, imported by both client and server. Don't maintain two copies.
- **Identical fixed `dt` on both sides**: `setFixedTimestep` advertises it; the client `reconciler` / `sim` read it back through `ctx.dt` / `input.stepSeconds`. Never hand-write `1/60` on the client.
- **Matching engine versions** for physics, e.g. the same Rapier build on client and server. Different builds produce different floating-point results and diverge.

Divergence shows up as **constant small corrections** (rubber-banding) even on a LAN. **Jitter** shows up as *occasional* corrections that scale with packet loss: that's the network, not your simulation.

### Diagnosing divergence vs jitter

You don't have to guess from feel. Every `reconciler`/`sim` controller keeps rolling drift telemetry (fed once per reconcile, not per frame) that separates the two:

- **`me.drift.ema`**: EMA of the correction magnitude: the **persistent** component. Steadily above ~0 means the two simulations genuinely disagree: divergence.
- **`me.drift.peak`**: a decaying max: **recent spikes**. A high `peak` over a near-zero `ema` is network jitter (loss / reorder), not a bug; smoothing absorbs it.
- **`me.lastCorrectionMag`** / **`me.lastCorrection`**: the latest reconcile's max |correction| and its per-field breakdown.

Set **`warnOnDivergence`** (a tolerance in world units) on the controller to get a console warning when the persistent component crosses it. Telemetry runs while watched (this option set, or the dev panel active):

**TypeScript**

```ts
const me = predict.reconciler(self, { input, step, warnOnDivergence: 0.05 });
```

**C#**

```cs
var me = predict.Reconciler(self, new ReconcilerOptions<Player, MoveInput> {
    Input = input,
    Step = (ctx, s, cmd) => ApplyInput(s, cmd, ctx.Dt),
    WarnOnDivergence = 0.05,
});
```

**Lua**

```lua
local me = predict:reconciler(self_player, {
  input = input, step = step, warn_on_divergence = 0.05,
})
```

**Haxe**

```haxe
var me = predict.reconciler(self, { input: input, step: step, warnOnDivergence: 0.05 });
```

**GDScript**

```gdscript
# No warnOnDivergence option. Read the drift telemetry yourself:
if me.drift_ema > 0.05:
    push_warning("prediction diverging from the server")
```

**Dart**

```dart
// No warnOnDivergence option. Read the drift telemetry yourself:
if (me.drift.ema > 0.05) log('prediction diverging from the server');
```

The dev panel (`import "@colyseus/sdk/debug"`) classifies through the **same rule** and shows a per-controller verdict: **✓ matched** (both ~0), **~ jitter** (spikes that decay out), **✗ diverging** (persistent `ema`). The panel and the warning can therefore never disagree about what the numbers mean. `me.reset()` zeroes the telemetry, and a `snap`-absorbed correction is excluded from it, so a deliberate pose jump doesn't read as divergence.

### A determinism check

Suspect your `step` itself? Test it in isolation: run the same input sequence through it twice from the same starting state and assert the outputs are bit-identical:

```ts
function isDeterministic(start, inputs, dt) {
  const a = clone(start), b = clone(start);
  for (const cmd of inputs) {
    applyInput(a, cmd, dt);
  }
  for (const cmd of inputs) {
    applyInput(b, cmd, dt);
  }
  return JSON.stringify(a) === JSON.stringify(b);   // must be true
}
```

If this fails, the culprit is inside `step`: `Math.random()`, `Date.now()`, iteration order over an unordered map, or reading mutable shared state. (When the non-derivable value is *intentional*, such as an RNG roll or a timestamp, freeze it with [`ctx.memo`](https://docs.colyseus.io/netcode/client-prediction.md#ctxmemo-freeze-a-value-replay-cant-re-derive) so replay reuses it.)

## Troubleshooting

| Symptom | Likely cause |
|---|---|
| Local player rubber-bands constantly | Non-determinism: different `dt`, divergent `step`, or engine-version mismatch. Confirm with [drift telemetry](#diagnosing-divergence-vs-jitter): persistent `me.drift.ema` ⇒ diverging. |
| Local player renders one step behind, warns once | Render values read before the frame's send loop. Reorder to tick → send → read. |
| Sounds/FX re-fire on corrections | Raw side effects inside `step`. Declare them with `ctx.predict` (events) or `ctx.memo` (values). |
| Remotes stutter / teleport | Interp `delay` too small (buffer underruns); raise it past 1–2 patch intervals, or check the patch rate. |
| "I hit them but no damage" on moving targets | Not rewinding (or rewinding to server-now). Use [`rewind.lastSeenBy(shooterId)`](https://docs.colyseus.io/netcode/lag-compensation.md). |
| Hits register *behind* a dead-reckoned target | The target renders forward-reckoned but rewinds on the snapshot timeline (double compensation). Attach it with `mode: "reckon"`. See [snapshot vs reckon](https://docs.colyseus.io/netcode/lag-compensation.md#snapshot-vs-reckon). |
| Hits land slightly *ahead* of the crosshair | `maxRewindMs` too small: it truncates the real rewind (`renderDelay + RTT + a tick`); raise it. |
| `rewind.lastSeenBy` throws | The room never called `defineInput()` (the stamps ride the input channel); or use `rewind.at(time)` with your own time. |
| `room.clock` returns local time | The room never called `defineInput()` (the clock rides input acks). |
| Bullet overshoots / tunnels past a target | Point hit test on a fast projectile. Use a swept (segment) test. See [Recipes](https://docs.colyseus.io/netcode/recipes.md). |

## Next

→ [Recipes](https://docs.colyseus.io/netcode/recipes.md): task-oriented patterns built on these APIs.

---
Source: https://docs.colyseus.io/netcode/determinism


# Lag Compensation

When you aim at another player, you're aiming at the past. The target on your screen is delayed by the network (≈ `rtt/2`) and rendered further behind on purpose (the `delay` of your interp buffer). If the server judged shots against where targets are *now*, every player would have to lead moving targets by their own latency. Lag compensation removes that burden. The server **rewinds** each target to the moment the shooter saw it, then runs the hit test: "what you see is what you hit."

It's the server-side dual of [client prediction](https://docs.colyseus.io/netcode/client-prediction.md): where the client forward-predicts entities it *receives*, the server rewinds entities it *owns*.

> **Note:**
>
> **Available in Colyseus 0.18+.** `allowRewindState()` / `Rewind` / `RewindView` are from `@colyseus/core`.

## Two pieces

Enabling it takes a stamp on the client's inputs and a rewind on the server. The first one is automatic.

### Client: the render-time stamp

Each input carries a timestamp telling the server *when* the client's view of the world was. Once the room enables rewind, the SDK stamps every input on its own. Wiring the handle through `predict.reconciler` / `predict.sim` then binds the stamp's interp-buffer term to the `Predict` lerp `delay`. The buffer you render at and the instant the server rewinds to come from **one number**, so they can't drift apart.

**TypeScript**

```ts
const predict = Predict.get(room, { mode: "lerp", delay: 100 });
const input = room.input({ type: MoveInput });   // stamp auto-derived from delay: 100
```

**C#**

```cs
var predict = Predict.Get(room, new PredictGetOptions { Mode = PredictMode.Lerp, Delay = 100 });
predict.AttachAll("players", new AttachOptions { Fields = new[] { "x", "y" } });
var input = room.Input(cmd);
var me = predict.Reconciler(self, new ReconcilerOptions<Player, MoveInput> {
    Input = input,   // binds the stamp to Delay = 100
    Step = (ctx, s, c) => ApplyInput(s, c, ctx.Dt),
});
```

**Lua**

```lua
local predict = Predict.get(room)
predict:attach_all("players", {
  x = { mode = "lerp", delay = 100 },
  y = { mode = "lerp", delay = 100 },
})
local input = room:input()   -- stamp auto-derived from the lerp delay
```

**Haxe**

```haxe
var predict = Predict.get(room);
predict.attachAll("players", {
    x: { mode: "lerp", delay: 100 },
    y: { mode: "lerp", delay: 100 },
});
var input = room.input({ type: MoveInput });   // stamp auto-derived from the lerp delay
```

**GDScript**

```gdscript
var predict = Colyseus.Predict.of(room)
predict.attach_all("players", {
    "x": { "mode": Colyseus.Predict.LERP, "delay": 100 },
    "y": { "mode": Colyseus.Predict.LERP, "delay": 100 },
}, room.get_session_id())
var input = room.input()   # stamp auto-derived from the lerp delay
```

**Dart**

```dart
final predict = Predict.get(room);
predict.attachAll('players', config: {
  'x': FieldOptions(mode: PredictMode.lerp, delay: 100),
  'y': FieldOptions(mode: PredictMode.lerp, delay: 100),
}, exceptKey: room.sessionId);
final input = room.input()!;   // stamp auto-derived from the lerp delay
```

Two knobs, both optional:

- **`renderDelay`**: pass it to `room.input()` only when you smooth remotes *outside* `Predict`; it must equal your actual interp buffer. The SDK adds the latency term itself. Pass only the buffer. The automatic value is the Predict's default lerp `delay`, read live, so a later `setDefaults({ delay })` moves the stamp too. In C#, `InputOptions.RenderDelay` is a `double?`: null binds, and any value, `0` included, is explicit.
- **`allowRewind`**: a per-input predicate gating which inputs carry the stamp, as a bandwidth trim: `room.input({ allowRewind: (d) => d.fire })` stamps only the inputs the server actually rewinds for. Don't use it when your *own* step hit-tests at `ctx.reckonTime`, because then every input needs the stamp. In GDScript, call `input.set_rewind_field("fire")` instead; in Dart, pass `allowRewind:` a predicate over the input view.

### Server: rewind targets to where the shooter saw them

```ts
import { Room } from "@colyseus/core";

class GameRoom extends Room {
  rewind = this.allowRewindState({ maxRewindMs: 500 });

  onCreate() {
    this.rewind.attachAll(this.state.players, { fields: ["x", "y"] });
    this.setFixedTimestep((ctx) => this.step(ctx), 30);
  }

  // In your hit test, for a shot fired by `shooterId`:
  fire(shooterId, bullet) {
    const seen = this.rewind.lastSeenBy(shooterId);     // clamp + live-fallback baked in
    for (const [, target] of this.state.players) {
      if (overlaps(bullet, seen.value(target, "x"), seen.value(target, "y"), HIT_RADIUS)) {
        this.hit(target);
      }
    }
  }
}
```

## `allowRewindState({ maxRewindMs })`

Enables lag compensation and returns a `Rewind`. The framework auto-records attached entities on **each broadcast**, snapshotting exactly what clients receive. The rewind therefore reproduces the client's interpolation even when the broadcast rate differs from the sim rate (`patchRate ≠ timestep`). Call `rewind.record()` yourself during a tick to take over that cadence (you then own correctness against your own broadcast rate). `maxRewindMs` (default 500) sizes the per-entity history ring and bounds how far back a hit can rewind.

### `rewind.attachAll(collection, options)` / `rewind.attach(instance, options)`

Track the numeric `fields` of every entity in a collection (or a single instance, e.g. a boss). The element type is inferred from the live collection (no state-type generic):

```ts
this.rewind.attachAll(this.state.players, { fields: ["x", "y"] });

// Per-entity interpolation: hold discrete-motion snaps sharp under rewind.
this.rewind.attachAll(this.state.enemies, {
  fields: ["x", "y"],
  interpolate: (e) => (e.kind === "teleporter" ? "step" : "linear"),
});
```

Options:

- **`fields`**: the numeric fields to record (an array, or a per-entity function). Fields a type doesn't declare are skipped and read live.
- **`interpolate`**: `"linear"` (default, continuous motion) or `"step"` (hold the last sample: discrete motion like teleports, where a lerp would smear across the jump). May be a per-entity function.
- **`mode`**: the rewind **timeline** (see [snapshot vs reckon](#snapshot-vs-reckon)).
- **`maxRewindMs`**: per-attach history-ring size for this group. The anti-spoof rewind clamp always uses the room-level `allowRewindState({ maxRewindMs })` default. A larger per-attach window does not extend how far a view rewinds.

## `rewind.lastSeenBy(sessionId)`

Returns a [`RewindView`](#rewindview) of the world as that client last saw it. The method resolves the client's stamped render time and **clamps** it to `[now − maxRewindMs, now]` (anti-spoof / clock-skew bound). When the client hasn't synced yet, it **falls back to the live position**.

A client that merely hasn't stamped yet (clock still syncing, or an unknown `sessionId`) is **not** an error: the view just reads live. `lastSeenBy` does require the framework input API (`defineInput`); if you stamp render times yourself, use `rewind.at(time)` and supply the time.

### `RewindView`

The view assumes nothing about your schema. You name the fields at the call site (same shape as the client's `predict.value`, and the batch is mirrored too: `seen.read` ⇄ [`predict.read`](https://docs.colyseus.io/netcode/client-prediction.md#reading-values)):

```ts
const seen = this.rewind.lastSeenBy(shooterId);

seen.value(target, "x");                         // one tracked numeric field
const pos = seen.read(target, ["x", "y"]);       // batch → { x, y }
seen.read(enemy, ENEMY_POS, this.seenScratch);   // zero-alloc: fills + returns a reused scratch
```

> **Note:**
>
> `at()` / `lastSeenBy()` re-aim and return the room's **internal default view**: the usual one-view-at-a-time flow is zero-alloc with nothing to declare. Need two views alive at once (compare two shooters)? Pass your own as `out`:
> ```ts
> const a = this.rewind.lastSeenBy(shooterA);                     // shared default view
> const b = this.rewind.lastSeenBy(shooterB, new RewindView());   // independent second view
> ```
>     Don't store a view across calls or ticks: the default is re-aimed by the next call, and any view's clamp goes stale at the next record.

## Snapshot vs reckon

The rewind **timeline** must match how the **client displays** the target. That's the "what you see" half of "what you see is what you hit". Declare it per attach group with `mode`:

- **`"snapshot"`** (default): rewind to the client's `renderTime`, for targets it shows **interpolated** (`Predict` `lerp`/`damped`), behind real time by its interp buffer + `rtt/2`.
- **`"reckon"`**: rewind to the client's `reckonTime` (≈ its `serverNow`), for targets it **forward-extrapolates** (`Predict` `reckon`). Rewinding a forward-reckoned target to the raw snapshot stamp would double-compensate.

```ts
// Players are lerped by clients; AI is dead-reckoned (two groups, two timelines):
this.rewind.attachAll(this.state.players, { fields: ["x", "y"] });                     // snapshot
this.rewind.attachAll(this.state.enemies, { fields: ["x", "y"], mode: "reckon" });
```

Keep the pairing in one shared constant if you like: the server's `mode` and the client's `predict.attachAll` mode describe the same decision. You can attach the same collection twice with disjoint `fields` to mix timelines on one entity. The room ships exactly the stamp(s) its attached groups need. Nothing extra crosses the wire.

> **Warning:**
>
> **Don't break the delay pairing.** When the input handle is wired through `predict.reconciler`/`predict.sim`, the lerp `delay` and the rewind stamp share one source: nothing to keep in sync. That source is the Predict's *default* `delay`, so a per-attach `delay` that differs from it breaks the pairing too. If you pass `renderDelay` explicitly, it must equal the delay your remotes actually render at. Reverting remotes to `damped` (no fixed delay) silently degrades the rewind to an approximation.

## Tuning `maxRewindMs`

The real rewind distance is roughly `renderDelay + RTT + one tick`. If `maxRewindMs` is **smaller** than that, the clamp truncates legitimate rewinds and hits land slightly **ahead** of the crosshair. Raise it. Too large only widens the anti-spoof window; 500ms is a sane default for most games.

## Predicting the verdict client-side

The shooter's *own* step can pre-judge the hit with the same timeline the server will use. `ctx.reckonTime` is the same value the server reads for that input. `predict.valueAt(target, field, ctx.reckonTime)` samples the target where the rewind will place it, so your client-side verdict matches the server's by construction. Batch the pose with `predict.readAt(target, fields, ctx.reckonTime)` to run one reckon integration per target instead of one per field. Pair it with an [optimistic event](https://docs.colyseus.io/netcode/client-prediction.md#optimistic-events-defineevent) for instant feedback that auto-rejects if the server disagrees.

`ctx.reckonTime` is **always a usable instant**. A seq that wasn't stamped (the room doesn't rewind, the clock is still syncing) resolves to the live `serverNow()` automatically. The backend mirrors this: `channel.reckonTime` resolves unstamped reads to the room clock. There is no fallback to hand-write on either end. The rare consumer that needs the distinction ("was this seq actually stamped for lag comp?") reads `ctx.lagCompActive`.

## Next

→ [Recipes](https://docs.colyseus.io/netcode/recipes.md): projectiles, dead-reckoned AI, and physics-engine hit tests.

→ [Determinism & The Contract](https://docs.colyseus.io/netcode/determinism.md#troubleshooting): troubleshooting "I hit them but no damage".

---
Source: https://docs.colyseus.io/netcode/lag-compensation


# Netcode Recipes

Task-oriented patterns that build on the [Client Prediction](https://docs.colyseus.io/netcode/client-prediction.md), [Server Input](https://docs.colyseus.io/netcode/server-input.md), and [Lag Compensation](https://docs.colyseus.io/netcode/lag-compensation.md) APIs. Each recipe stands alone. Jump to the one that matches what you're building.

> **Note:**
>
> **Available in Colyseus 0.18+.**

## Choosing a remote smoothing mode

`Predict.attachAll` smooths entities you don't control. Pick the mode by what the entity *is*:

- **`lerp`**: remote **players**. Faithful (renders exactly where the server put them, a little in the past). The default for anything you also want lag-compensated, because rewind can match the interpolated instant.
- **`reckon`**: **AI / NPCs** you can forward-simulate from a known step function. Renders at ≈ `serverNow`, hiding latency; attach the server group with `mode: "reckon"` so hits line up.
- **`damped`**: **cosmetic** entities where "never jittery" beats "exact" (floating pickups, ambient critters). No fixed delay, so it can't be exactly lag-compensated.

Full behavior reference: [the modes table](https://docs.colyseus.io/netcode/client-prediction.md#remote-entities).

## Rough snapshot streams: `smoothMs`

`lerp` renders exactly what the server sent. When the snapshot stream itself is rough (server stamp jitter, uneven per-patch motion), that faithfulness shows as velocity judder: playback speeds up and slows down at each snapshot boundary. The eye punishes velocity jumps far harder than a small, steady offset.

`smoothMs` on a lerp attach arms a display-only **output spring** over the interpolated result, keeping rendered velocity continuous. The default is `0`: exact interpolation, no spring.

**TypeScript**

```ts
// Display-only output spring over the lerp result (default 0 = exact).
predict.attachAll("players", { mode: "lerp", fields: ["x", "y"], smoothMs: 25 });
```

**C#**

```cs
// Display-only output spring over the lerp result (default 0 = exact).
predict.AttachAll("players", new AttachOptions { Mode = PredictMode.Lerp, Fields = new[] { "x", "y" }, SmoothMs = 25 });
```

**Lua**

```lua
-- Display-only output spring over the lerp result (default 0 = exact).
predict:attach_all("players", {
  x = { mode = "lerp", smooth_ms = 25 },
  y = { mode = "lerp", smooth_ms = 25 },
})
```

**Haxe**

```haxe
// Display-only output spring over the lerp result (default 0 = exact).
predict.attachAll("players", {
    x: { mode: "lerp", smoothMs: 25 },
    y: { mode: "lerp", smoothMs: 25 },
});
```

**GDScript**

```gdscript
# Display-only output spring over the lerp result (default 0 = exact).
predict.attach_all("players", {
    "x": { "mode": Colyseus.Predict.LERP, "smooth_ms": 25 },
    "y": { "mode": Colyseus.Predict.LERP, "smooth_ms": 25 },
}, room.get_session_id())
```

**Dart**

```dart
// Display-only output spring over the lerp result (default 0 = exact).
predict.attachAll('players', config: {
  'x': FieldOptions(mode: PredictMode.lerp, smoothMs: 25),
  'y': FieldOptions(mode: PredictMode.lerp, smoothMs: 25),
}, exceptKey: room.sessionId);
```

Sizing: during steady motion the spring trails the exact interpolant by `speed × smoothMs`, at any frame rate. Start near `25`: it removes the velocity discontinuities at minimal added lag. `65` smooths rougher streams, at that much more display lag. On `damped` and `extrapolate` the same option is the chase rate and defaults to `50`.

Two boundaries:

- The spring is display-only. Server-side rewind reconstructs the unsmoothed interpolation, so the drawn position trails the hit position by the same `speed × smoothMs` bound. Leave it at `0` where draw and hit must agree exactly (lag-compensated shooters).
- Judder from network **arrival** jitter is a different problem: size `delay` (or use `tickInterval`) for that first. The spring is for streams that are uneven at the source.

## Taps between steps: buffer, then consume

Input is sampled once per **fixed step**, not per render frame. Frames and steps don't line up. A 120 Hz display on a 30 Hz tick runs a step every ~4th frame, and a hitchy frame can run several steps at once. Two traps follow. A tap on a **0-step frame** must not be lost (it belongs to the next step). A tap spanning a **multi-step frame** must not fire twice. "Is the key down right now?" sampling gets both wrong.

**Buffer the press when it happens; consume it inside the step loop on exactly one step:**

**TypeScript**

```ts
let jumpBuffered = false;
onKeyDown("Space", () => jumpBuffered = true);  // buffer: the tap happened

function frame(now) {
  const n = predict.tick(now);
  for (let i = 0; i < n; i++) {
    input.data.moveX = readAxis();    // held state: sample live, no buffer
    input.data.jump = jumpBuffered;
    jumpBuffered = false;             // consume: fires on exactly one step
    input.send();
  }
}
```

**C#**

```cs
bool jumpBuffered = false;
void OnJumpPressed() => jumpBuffered = true;    // buffer: the tap happened

void Update() {
    int steps = predict.Tick();
    for (int i = 0; i < steps; i++) {
        cmd.moveX = ReadAxis();       // held state: sample live, no buffer
        cmd.jump = jumpBuffered;
        jumpBuffered = false;         // consume: fires on exactly one step
        input.Send();
    }
}
```

**Lua**

```lua
local jump_buffered = false

function on_input(self, action_id, action)
  if action_id == hash("jump") and action.pressed then
    jump_buffered = true              -- buffer: the tap happened
  end
end

function update(self, dt)
  local steps = predict:tick()
  for _ = 1, steps do
    input.data.moveX = read_axis()    -- held state: sample live, no buffer
    input.data.jump = jump_buffered
    jump_buffered = false             -- consume: fires on exactly one step
    input:send()
  end
end
```

**Haxe**

```haxe
var jumpBuffered = false;
onKeyDown(Space, () -> jumpBuffered = true);  // buffer: the tap happened

function frame() {
    var steps = predict.tick();
    for (_ in 0...steps) {
        cmd.moveX = readAxis();       // held state: sample live, no buffer
        cmd.jump = jumpBuffered;
        jumpBuffered = false;         // consume: fires on exactly one step
        input.send();
    }
}
```

**GDScript**

```gdscript
var jump_buffered := false

func _input(event):
    if event.is_action_pressed("jump"):
        jump_buffered = true            # buffer: the tap happened

func _process(_delta):
    var steps: int = predict.tick()
    for i in steps:
        input.data.moveX = read_axis()  # held state: sample live, no buffer
        input.data.jump = jump_buffered
        jump_buffered = false           # consume: fires on exactly one step
        input.send()
```

**Dart**

```dart
var jumpBuffered = false;
onKeyDown('Space', () => jumpBuffered = true);  // buffer: the tap happened

void onFrame() {
  Colyseus.pump();
  final steps = predict.tick();
  for (var i = 0; i < steps; i++) {
    input.data['moveX'] = readAxis();   // held state: sample live, no buffer
    input.data['jump'] = jumpBuffered;
    jumpBuffered = false;               // consume: fires on exactly one step
    input.send();
  }
}
```

Variants of the same shape:

- **Held buttons** (movement, auto-fire) sample the live state directly: no buffer.
- **Buffer windows** (a jump buffer with a grace period): buffer a timestamp instead of a flag; the consuming step decides whether it's still fresh.
- **Analog deltas** (pointer aim, mouselook): accumulate into a pending total and let each step consume its budget (`pending -= taken`). Fast motion carries over to later steps instead of clipping.

Buffer outside the loop, consume inside it: draining an edge anywhere else either drops taps (0-step frames) or double-fires them (multi-step frames).

## Unreliable input over WebTransport

On a datagram-capable transport, input frames don't need reliable delivery. Each packet carries the last few inputs as redundancy, so a dropped datagram costs nothing and nothing head-of-line blocks.

> **Warning:**
>
> **Experimental, and WebTransport only.** Unreliable input needs a datagram channel, which only [WebTransport](https://docs.colyseus.io/server/transport/webtransport.md) provides today (itself experimental). Right now only the JavaScript/TypeScript SDK supports WebTransport, and with it unreliable input.
>
> Other SDKs **reject** `mode: "unreliable"` at construction for now: over their WebSocket-only transports the redundancy ring would cost bandwidth for no benefit. Use `mode: "reliable"` there.

**TypeScript**

```ts
const input = room.input({ type: MoveInput, mode: "unreliable", historySize: 4 });
```

**C#**

```cs
// Not available yet: Room.Input() rejects mode "unreliable"
// (WebSocket-only transport). Use "reliable".
```

**Lua**

```lua
-- Not available yet: room:input() rejects mode "unreliable"
-- (WebSocket-only transport). Use "reliable".
```

**Haxe**

```haxe
// Not available yet: room.input() rejects mode "unreliable"
// (WebSocket-only transport). Use "reliable".
```

**GDScript**

```gdscript
# Not available: the Godot SDK sends input over the reliable channel only.
```

**Dart**

```dart
// Not available yet: room.input() throws on InputMode.unreliable
// (WebSocket-only transport). Use InputMode.reliable.
```

That's the whole migration. The framework runs its own sequence numbers and acks by seq **value**, so rollback reconciliation works unchanged. No user-side bookkeeping, no seq field on your schema. `historySize` is the redundancy depth (how many recent inputs ride along in each datagram; default 3).

## Predicted projectiles: `predict.spawns`

A fired bullet needs zero-latency feedback, but the server assigns its identity ~RTT later. `predict.spawns` runs the whole lifecycle: render the predicted local instantly, then correlate it to the authoritative entity when it arrives. One **stable id** persists across the handoff, so the sprite never flickers:

**TypeScript**

```ts
const rockets = predict.spawns("rockets", {
  owned:     r => r.owner === room.sessionId,      // which server entities are mine
  spawnTime: r => r.bornMs,                        // exact per-shot input lead
  step:      stepRocket,                           // shared client/server sim
  fields:    ["x", "z"],                           // reckon confirmed entities
});

// on the predicted fire (live input step):
rockets.spawn({ x, z, heading });

// render: one path, handoff-invisible, keyed on the stable entry id:
for (const e of rockets.entries()) {
  draw(e.id, rockets.value(e, "x"), rockets.value(e, "z"));
}
```

**C#**

```cs
var rockets = predict.Spawns<Rocket, Shot>("rockets",
    new PredictedSpawnsOptions<Rocket, Shot> {
        Owned     = r => r.owner == room.SessionId,     // which server entities are mine
        SpawnTime = r => r.bornMs,                      // exact per-shot input lead
        Step      = (shot, dt) => StepRocket(shot, dt), // shared client/server sim
        Fields    = new[] { "x", "z" },                 // reckon confirmed entities
    });

// on the predicted fire (live input step):
rockets.Spawn(new Shot { x = x, z = z, heading = heading });

// render: one path, handoff-invisible, keyed on the stable entry id:
foreach (var e in rockets.Entries()) {
    Draw(e.Id, rockets.Value(e, "x"), rockets.Value(e, "z"));
}
```

**Lua**

```lua
local rockets = predict:spawns("rockets", {
  owned      = function(r) return r.owner == room.session_id end,  -- mine?
  spawn_time = function(r) return r.bornMs end,   -- exact per-shot input lead
  step       = step_rocket,                       -- shared client/server sim
  fields     = { "x", "z" },                      -- reckon confirmed entities
})

-- on the predicted fire (live input step):
rockets:spawn({ x = x, z = z, heading = heading })

-- render: one path, handoff-invisible, keyed on the stable entry id:
for _, e in ipairs(rockets:entries()) do
  draw(e.id, rockets:value(e, "x"), rockets:value(e, "z"))
end
```

**Haxe**

```haxe
var rockets = predict.spawns("rockets", {
    owned:     (r) -> r.owner == room.sessionId,   // which server entities are mine
    spawnTime: (r) -> r.bornMs,                    // exact per-shot input lead
    step:      stepRocket,                         // shared client/server sim
    fields:    ["x", "z"],                         // reckon confirmed entities
});

// on the predicted fire (live input step):
rockets.spawn({ x: x, z: z, heading: heading });

// render: one path, handoff-invisible, keyed on the stable entry id:
for (e in rockets.entries()) {
    draw(e.id, rockets.value(e, "x"), rockets.value(e, "z"));
}
```

**GDScript**

```gdscript
var rockets = predict.spawns("rockets", {
    "owned":      func(r): return r.owner == room.get_session_id(),
    "spawn_time": func(r): return r.bornMs,     # exact per-shot input lead
    "step":       _step_rocket,                 # shared client/server sim
    "fields":     ["x", "z"],                   # reckon confirmed entities
})

# on the predicted fire (live input step):
rockets.spawn({ "x": x, "z": z, "heading": heading })

# render: one path, handoff-invisible, keyed on the stable entry id:
for e in rockets.entries():
    draw(e.id, rockets.value(e.id, "x"), rockets.value(e.id, "z"))
```

**Dart**

```dart
final rockets = predict.spawns('rockets', SpawnsOptions(
  owned:     (r) => r['owner'] == room.sessionId,       // which server entities are mine
  spawnTime: (r) => (r['bornMs'] as num).toDouble(),    // exact per-shot input lead
  step:      (local, dt) => stepRocket(local, dt),      // shared client/server sim
  fields:    const ['x', 'z'],                          // reckon confirmed entities
));

// on the predicted fire (live input step):
rockets.spawn(Shot(x, z, heading));

// render: one path, handoff-invisible, keyed on the stable entry id:
for (final e in rockets.entries) {
  draw(e.id, rockets.value(e, 'x'), rockets.value(e, 'z'));
}
```

With `spawnTime`, an **owned** projectile keeps flying the *shooter's* timeline through the handoff. No snap-back, and the rendered trajectory is the one a favor-the-shooter rewind actually judges. Foreign projectiles (other players') render at server-present, aged forward automatically. An unmatched prediction expires after a TTL (`max(2×rtt, 600ms)` by default) and `onReject` fires: the ghost reverts.

For fast projectiles, hit-test the swept **segment** between last and current position, not a point. Otherwise a frame-step can tunnel through a thin target.

## Optimistic hit FX: `defineEvent`

Impact feedback (hit marker, sound, decal) shouldn't wait for the server, but a mispredicted hit must clean up after itself. Key the channel by projectile so multiple in-flight shots settle independently:

**TypeScript**

```ts
const impacts = predict.defineEvent<{ projectileId: string; x: number; y: number }>({
  uniqueBy:  (h) => h.projectileId,          // payload carries FX data; identity is the projectile
  onPredict: (h) => spawnImpactFx(h.x, h.y),
  onReject:  (h) => removeImpactFx(h.projectileId),
});

// inside the step, on a predicted impact:
if (hit) ctx.predict(impacts, { projectileId: id, x: hit.x, y: hit.y });

// settlement:
room.onMessage("impact", (m) => impacts.confirm(m.projectileId));
```

**C#**

```cs
var impacts = predict.DefineEvent(new PredictedEventChannelOptions<Hit> {
    UniqueBy  = h => h.projectileId,          // payload carries FX data; identity is the projectile
    OnPredict = h => SpawnImpactFx(h.x, h.y),
    OnReject  = h => RemoveImpactFx(h.projectileId),
});

// inside the step, on a predicted impact:
if (hit) ctx.Predict(impacts, new Hit { projectileId = id, x = hit.x, y = hit.y });

// settlement:
room.OnMessage<Dictionary<string, object>>("impact",
    m => impacts.Confirm((string)m["projectileId"]));
```

**Lua**

```lua
local impacts = predict:define_event({
  unique_by  = function(h) return h.projectileId end,  -- identity is the projectile
  on_predict = function(h) spawn_impact_fx(h.x, h.y) end,
  on_reject  = function(h) remove_impact_fx(h.projectileId) end,
})

-- inside the step, on a predicted impact:
if hit then ctx:predict(impacts, { projectileId = id, x = hit.x, y = hit.y }) end

-- settlement:
room:on_message("impact", function(m) impacts:confirm(m.projectileId) end)
```

**Haxe**

```haxe
var impacts = predict.defineEvent({
    uniqueBy:  (h) -> h.projectileId,          // payload carries FX data; identity is the projectile
    onPredict: (h) -> spawnImpactFx(h.x, h.y),
    onReject:  (h) -> removeImpactFx(h.projectileId),
});

// inside the step, on a predicted impact:
if (hit) ctx.predict(impacts, { projectileId: id, x: hit.x, y: hit.y });

// settlement:
room.onMessage("impact", (m) -> impacts.confirm(m.projectileId));
```

**GDScript**

```gdscript
# string-keyed: the projectile id IS the entry identity (no uniqueBy, no payloads);
# FX coordinates come from your own app state.
var impacts = predict.define_event({
    "on_predict": func(id): spawn_impact_fx_for(id),
    "on_reject":  func(id): remove_impact_fx(id),
})

# inside the step, on a predicted impact:
if hit: ctx.predict(impacts, id)

# settlement:
room.message_received.connect(func(type, m):
    if type == "impact": impacts.confirm(m.projectileId))
```

**Dart**

```dart
// string-keyed: the projectile id IS the entry identity (no uniqueBy, no payloads);
// FX coordinates come from your own app state.
final impacts = predict.defineEvent(
  onPredict: (id) => spawnImpactFxFor(id),
  onReject:  (id) => removeImpactFx(id),
);

// inside the step, on a predicted impact:
if (hit) ctx.predict(impacts, id);

// settlement:
room.onMessage('impact').listen((m) => impacts.confirm(m['projectileId']));
```

A sim-born prediction auto-rejects once the server processes past its birth step without confirming. See [Optimistic events](https://docs.colyseus.io/netcode/client-prediction.md#optimistic-events-defineevent).

## Optimistic pickups & breakables: `confirmOn`

Kills, pickups, and breakables share one shape. Predict a flag keyed by entity id, derive the visual from `has(id)` OR'd with authoritative state, and confirm when the entity's field flips. You declare the settlement; the channel does the wiring:

```ts
const pickups = predict.defineEvent<string>({
  confirmOn: { collection: "items", field: "alive", equals: false },
  // a remote player's pickup (nothing pending): play the FX we skipped
  onUnpredicted: (id) => {
    const item = state.items.get(String(id));
    if (item) burstAt(item.x, item.y);
  },
});

// inside the step, on predicted contact:
if (touching) ctx.predict(pickups, itemId);

// render: hidden the instant WE predict it, or when the server says so:
const hidden = !item.alive || pickups.has(id);
```

A mispredict needs no cleanup code: the entry auto-rejects once the server processes past it silently, `has(id)` flips back, the derived view recovers. See [`confirmOn`](https://docs.colyseus.io/netcode/client-prediction.md#confirming-from-state-confirmon) for the `add`/`remove` membership variants (predicted drops and consumables).

> **Note:**
>
> `confirmOn` is available in JavaScript and C# (`ConfirmOn = new ConfirmOn { Collection = "items", Field = "alive", Equals = false }`). The other ports get the same behavior with two lines: `ctx.predict(pickups, itemId)` in the step, and `confirm(itemId)` from a schema callback watching `alive`. The `has(id)` derive works everywhere except the GDScript binding.

## Dead-reckoned AI (server-driven)

Some entities move predictably but nobody controls them directly (patrolling AI, ballistics). For these, pair the client's `reckon` display with a `reckon` rewind timeline (both sides describe the same decision):

**TypeScript**

```ts
predict.attachAll("enemies", { mode: "reckon", fields: ["x", "y"], step: stepEnemy });
```

**C#**

```cs
predict.AttachAll("enemies", new ReckonOptions<Enemy> {
    Fields = new[] { "x", "y" },
    Step = (e, dt, elapsedMs) => StepEnemy(e, dt),
});
```

**Lua**

```lua
predict:attach_all("enemies", { mode = "reckon", fields = { "x", "y" }, step = step_enemy })
```

**Haxe**

```haxe
predict.attachAll("enemies", { mode: "reckon", fields: ["x", "y"], step: stepEnemy });
```

**GDScript**

```gdscript
predict.attach_all_reckon("enemies", ["x", "y"], _step_enemy)
```

**Dart**

```dart
predict.attachAllReckon('enemies', const ['x', 'y'], stepEnemy);
```

The server rewinds on the matching timeline (no double compensation):

```ts
this.rewind.attachAll(this.state.enemies, { fields: ["x", "y"], mode: "reckon" });
```

For discrete movers (teleporters), keep snaps sharp under rewind with `interpolate`:

```ts
this.rewind.attachAll(this.state.enemies, {
  fields: ["x", "y"],
  interpolate: (e) => (e.kind === "teleporter" ? "step" : "linear"),
});
```

## Teleports & respawns: `snap`

Smoothing turns a respawn into a glide across the map. The `snap` option (on any attach or reconciler config) declares a value-space threshold past which a jump is a **teleport**. Smoothing resets and the entity pops to the new value:

**TypeScript**

```ts
// Remotes: a passive attach pops past the threshold.
predict.attachAll("players", { mode: "lerp", fields: ["x", "y"], snap: 300 });

// Your own entity: a reconcile correction past it pops instead of gliding
// (and doesn't count toward divergence telemetry).
const me = predict.reconciler(self, { input, step, snap: 300 });
```

**C#**

```cs
// Remotes: a passive attach pops past the threshold.
predict.AttachAll("players", new AttachOptions { Mode = PredictMode.Lerp, Fields = new[] { "x", "y" }, Snap = 300 });

// Your own entity: a reconcile correction past it pops instead of gliding.
var me = predict.Reconciler(self, new ReconcilerOptions<Player, MoveInput> {
    Input = input,
    Step = (ctx, s, cmd) => ApplyInput(s, cmd, ctx.Dt),
    Snap = 300,
});
```

**Lua**

```lua
-- Remotes: a passive attach pops past the threshold.
predict:attach_all("players", {
  x = { mode = "lerp", snap = 300 },
  y = { mode = "lerp", snap = 300 },
})

-- Your own entity: a reconcile correction past it pops instead of gliding.
local me = predict:reconciler(self_player, { input = input, step = step, snap = 300 })
```

**Haxe**

```haxe
// Remotes: a passive attach pops past the threshold.
predict.attachAll("players", {
    x: { mode: "lerp", snap: 300 },
    y: { mode: "lerp", snap: 300 },
});

// Your own entity: a reconcile correction past it pops instead of gliding.
var me = predict.reconciler(self, { input: input, step: step, snap: 300 });
```

**GDScript**

```gdscript
# Remotes: a passive attach pops past the threshold.
predict.attach_all("players", {
    "x": { "mode": Colyseus.Predict.LERP, "snap": 300 },
    "y": { "mode": Colyseus.Predict.LERP, "snap": 300 },
}, room.get_session_id())

# Your own entity: a reconcile correction past it pops instead of gliding.
var me = predict.reconciler(self_player, {
    "input": input, "step": _step, "snap": 300,
})
```

**Dart**

```dart
// Remotes: a passive attach pops past the threshold.
predict.attachAll('players', config: {
  'x': FieldOptions(mode: PredictMode.lerp, snap: 300),
  'y': FieldOptions(mode: PredictMode.lerp, snap: 300),
}, exceptKey: room.sessionId);

// Your own entity: a reconcile correction past it pops instead of gliding.
final me = predict.reconciler(self, input: input, step: step, snap: 300);
```

Size it well above per-patch motion (`maxSpeed × patchInterval`) and below your smallest legitimate teleport. Respawns that land on the same position induce zero correction and never trip it.

## Cooldowns & timers: pick the right clock

Three kinds of "wait", three homes:

- **Self-imposed rate limits** (fire rate, ability spam guard the client enforces on itself): `room.clock.now()`, local monotonic: `now() - lastFired >= COOLDOWN_MS`. No clock sync involved, so no jitter.
- **Server-stamped windows** (invulnerable-until, respawn-at, round-end): compare against `room.clock.serverNow()`; the server wrote the absolute deadline.
- **Cooldowns that gate the simulation itself** (a dash the step must refuse during cooldown): make the cooldown a **reconciled field ticked inside `step`** (`dashCooldown--` per tick, in `fields`). It predicts, replays, and self-corrects like any other simulated state; a wall-clock gate inside `step` would break replay.

## Physics-engine prediction (`predict.sim` + Rapier)

When the local simulation is an opaque engine, bridge it into `predict.sim`'s `step`: the engine handle is your `world`. On the server, consume one input per tick with `next()` and step the world once:

```ts
// server
step(ctx) {
  for (const [sid, body] of this.bodies) {
    const cmd = this.inputs.get(sid).next();
    if (cmd) applyInput(body, cmd);
  }
  this.world.step(ctx.dt);
}
```

```ts
// client: same applyInput, same dt
const me = predict.sim({
  input,
  world: { world, body },
  step:  (ctx, w, cmd) => { applyInput(w.body, cmd); w.world.step(ctx.dt); },
  adopt: (w) => { w.body.setTranslation({ x: self.x, y: self.y }, true);
                  w.body.setLinvel({ x: self.vx, y: self.vy }, true); },
  pose:  (w) => { const t = w.body.translation(); return { x: t.x, y: t.y }; },
});
```

> **Note:**
>
> The opaque-engine face (`adopt` + `pose`) is JavaScript-only. See [the sim note](https://docs.colyseus.io/netcode/client-prediction.md#composite--engine-state-predictsim). On the other SDKs, keep engine state in bound schema mirrors (C# and Flutter still take `adopt` for opaque extras). See [Composite scalars](#composite-scalars-predictsim-no-engine) below.

> **Warning:**
>
> Reseed **every** scalar the sim depends on in `adopt` (position **and** velocity). Engine-internal non-scalar state isn't rolled back. See [the warning on `predict.sim`](https://docs.colyseus.io/netcode/client-prediction.md#composite--engine-state-predictsim).

## Composite scalars (`predict.sim`, no engine)

When an input pushes more than your own entity (a paddle striking a puck), put the decoded schema instances in the `world`. They **auto-bind**: no `adopt` or `pose` callbacks, and the bound entities render through the ordinary `predict.value(instance, field)` read. See [Composite & engine state](https://docs.colyseus.io/netcode/client-prediction.md#composite--engine-state-predictsim).

## Hand-rolled simulation (no physics engine)

You don't need an engine. The simplest way to satisfy [the determinism contract](https://docs.colyseus.io/netcode/determinism.md) is plain math. `applyInput` integrates velocity and gravity by hand, shared verbatim between client and server (no engine build to keep in sync).

## Next

→ [Determinism & The Contract](https://docs.colyseus.io/netcode/determinism.md): the rules these patterns rely on, and the troubleshooting table.

→ [Client Prediction](https://docs.colyseus.io/netcode/client-prediction.md): the full API reference behind every recipe here.

---
Source: https://docs.colyseus.io/netcode/recipes


# Server Input & Fixed Timestep

This page covers the **server half** of the netcode stack. Declare what input each client sends, consume it, and advance the authoritative simulation at a fixed tick rate. The matching client half lives in [Client Prediction](https://docs.colyseus.io/netcode/client-prediction.md).

> **Note:**
>
> **Available in Colyseus 0.18+.**

## At a glance

```ts filename="GameRoom.ts"
import { Room } from "@colyseus/core";
import { MoveInput } from "./shared/MoveInput";
import { applyInput } from "./shared/applyInput";

class GameRoom extends Room<{ input: MoveInput }> {
  state = new GameState();

  // Per-client input schema (flat primitives only), buffered per session.
  inputs = this.defineInput(MoveInput, { bufferMaxSize: 64 });

  // Records attached entities' positions (auto, on each broadcast).
  rewind = this.allowRewindState({ maxRewindMs: 500 });

  onCreate() {
    this.rewind.attachAll(this.state.players, { fields: ["x", "y"] });
    // Fixed-step loop @ 30 Hz: advertises the rate to predicting clients.
    this.setFixedTimestep((ctx) => this.step(ctx), 30);
  }

  step(ctx) {
    for (const [sid, p] of this.state.players) {
      const cmd = this.inputs.get(sid).next();     // one input per tick
      if (cmd) applyInput(p, cmd, ctx.dt);          // SAME fn the client predicts with
    }
    // ...advance world, then hit tests (see Lag Compensation).
  }
}
```

## `defineInput(type, options)`

Declares the per-client input schema and buffers inbound frames. Assign it once (typically as a class field): it returns the input API you consume as `this.inputs.get(sessionId)`, the same per-session lookup verb as `room.clients.get()`.

```ts
inputs = this.defineInput(MoveInput, { bufferMaxSize: 64 });
```

Options and their defaults:

- **`bufferMaxSize`**: per-client buffer depth (default 32). `0` disables buffering (only `.latest` remains readable).
- **`seqField`**: most rooms leave this unset: on a reliable, in-order channel every frame is unique, and the framework tracks its own sequence. Name a monotonic numeric field of your input only when you need dedupe and `at(value)` lookup (lockstep, or a hand-rolled rollback).
- **`sanitize`** / **`idle`**: see below.

Inputs are **flat schemas: primitives only**. No nested schemas or collections in an input. Use `int8`/`uint8`/`float32` etc. and refine the legal set with generics (`t.int8<-1 | 0 | 1>()`):

```ts filename="shared/MoveInput.ts"
import { schema, t, type SchemaType } from "@colyseus/schema";

export const MoveInput = schema({
  moveX: t.int8<-1 | 0 | 1>(),
  moveZ: t.int8<-1 | 0 | 1>(),
  jump:  t.boolean(),
  yaw:   t.float32(),
});

// schema() returns a value. Derive the TS type for Room<{ input: ... }>:
export type MoveInput = SchemaType<typeof MoveInput>;
```

> **Note:**
>
> Calling `defineInput()` does more than buffer input: it powers the client's [`room.clock`](https://docs.colyseus.io/netcode/client-prediction.md#roomclock) (clock-sync and RTT ride the input acks). The call also lets `room.input()` resolve the schema without a client-side constructor. A room that never calls it leaves the client clock as a stub.

### Consuming input

The accessor `this.inputs.get(sessionId)` exposes the per-client buffered stream. Pick **one** consumption style per room, matched to how your simulation steps:

- **Iterate**: the per-entity loop. Consumes one frame at a time, so the lag-comp `renderTime` stamp tracks each individual input:

  ```ts
  step(ctx) {
    for (const [sid, p] of this.state.players) {
      // frame by frame: the ack and renderTime advance once per input
      for (const cmd of this.inputs.get(sid)) {
        applyInput(p, cmd, ctx.dt);
      }
    }
  }
  ```

- **`next()`**: take **exactly one**. Right when a single shared solver step moves every body together: consume one input per entity, then step the world once:

  ```ts
  step(ctx) {
    for (const [sid, p] of this.state.players) {
      const cmd = this.inputs.get(sid).next();   // oldest pending frame, or undefined
      if (cmd) applyInput(p, cmd, ctx.dt);
    }
    this.world.step(ctx.dt);                     // one solver step moves every body
  }
  ```

- **`drain()`**: take **all** buffered frames as an array. The ack (`lastProcessed`) lands on the newest frame. Use it when you need the array itself: its length, a replay recording, or a physics call that accepts a list.

  ```ts
  step(ctx) {
    for (const [sid, p] of this.state.players) {
      const cmds = this.inputs.get(sid).drain();  // whole burst, oldest first
      for (const cmd of cmds) {
        applyInput(p, cmd, ctx.dt);
      }
    }
  }
  ```

> **Warning:**
>
> Draining all frames but simulating only the latest jumps the ack past inputs you never ran. The client then reconciles against state it can't reproduce. Match the consumption style to how you step.

Beyond consuming, the accessor offers non-consuming reads and bookkeeping:

- **`latest`**: the most recent decoded frame, without consuming it. `peek()`, `take(n)` and `size` round out the buffer access.
- **`consumedCount`**: how many inputs this room has consumed; this is the reconcile ack the client sees.
- **`wasIdle`**: whether the last read was a synthesized idle frame.
- **`renderTime`** / **`reckonTime`**: the lag-comp instants. `renderTime` is the raw stamp of the last consumed input (`0` until one is stamped). `reckonTime` is always usable: it resolves to the room clock's current time until a reckon-stamped input is consumed, so `channel.reckonTime` needs no fallback. For hit tests, prefer [`rewind.lastSeenBy()`](https://docs.colyseus.io/netcode/lag-compensation.md) over reading these directly.

### Never trust the wire: `sanitize`

The wire carries whatever the client chooses to encode: an `int8` axis can arrive as `127` (a speed hack), a `float32` as `NaN`. Declare each field's legal domain **once** at `defineInput`, and every decoded frame is fixed up **in place** before anything reads it:

```ts
inputs = this.defineInput(MoveInput, {
  bufferMaxSize: 64,
  sanitize: {                                // map form: range clamps
    moveX: [-1, 1],
    moveZ: [-1, 1],
    yaw:   [-Math.PI, Math.PI],
  },
  // or a callback for anything beyond ranges:
  // sanitize: (f) => { f.yaw = wrapAngle(f.yaw); },
});
```

- Sanitizers **modify, never reject**: a malformed value becomes a legal one. Honest clients are untouched (in-range values pass through as-is), so they never diverge from the server's sanitized result.
- The map form is **NaN-safe**: `NaN` lands on the clamp floor, closing the classic `Math.min(NaN, …)` poisoning hole that hand-rolled clamps share.
- Sanitizing handles **value domains**, not game rules. Semantic checks ("slot must name an owned weapon") stay in your simulation.

### Empty ticks: the `idle` policy

What should happen on a tick where a client sent nothing? Pick one of three policies, declared **once** at `defineInput({ idle })` and applied automatically when you consume:

- **Skip** (default): don't declare `idle`. An empty tick yields nothing: `drain()` returns `[]`, `next()` returns `undefined`, and you keep the `if (cmd)` guard from the [loops above](#consuming-input). Right for strict fixed-timestep games where the client sends one input per step.

- **Synthesize**: declare a policy, and an empty tick yields one frame: the schema's **defaults** overlaid with your overrides. The callback runs lazily (only on actually-empty ticks) and closes over the room. On the consuming side, `next()` always yields a frame, so the loop loses its `if (cmd)` branch:

  ```ts
  inputs = this.defineInput(MoveInput, {
    bufferMaxSize: 64,
    idle: ({ latest, sessionId }) => {
      const p = this.state.players.get(sessionId);
      if (!p) return true;                       // defaults frame for the empty seat
      return { yaw: p.yaw, jump: false };        // defaults ⊕ overrides
    },
  });
  
  step(ctx) {
    for (const [sid, p] of this.state.players) {
      const cmd = this.inputs.get(sid).next();   // idle declared: never undefined
      applyInput(p, cmd, ctx.dt);                // gravity keeps integrating
      if (cmd.jump) p.tryJump();                 // idle frame: jump=false, no-op
    }
    this.world.step(ctx.dt);
  }
  ```

- **Hold everything**: return the whole last input as the idle frame, so a held key keeps moving the player through a packet gap. Two guards keep it honest. In the policy, hold only while the client is still connected. In the loop, check `wasIdle` before edge-triggered actions, because a held frame repeats `jump: true` for every tick of the gap:

  ```ts
  inputs = this.defineInput(MoveInput, {
    bufferMaxSize: 64,
    idle: ({ latest, sessionId }) => {
      const client = this.clients.get(sessionId);
      if (client?.state !== ClientState.JOINED) return true;  // dropped: defaults
      return latest ?? true;                     // hold the last input through the gap
    },
  });
  
  step(ctx) {
    for (const [sid, p] of this.state.players) {
      const inp = this.inputs.get(sid);
      const cmd = inp.next();                    // gap: the held key stays down
      applyInput(p, cmd, ctx.dt);
      if (cmd.jump && !inp.wasIdle) p.tryJump(); // held jump must not re-fire
    }
    this.world.step(ctx.dt);
  }
  ```

The policy also covers **absent sessions**. A player who dropped but is still inside their `allowReconnection` window lingers in `state`. The input accessor resolves through a registry that outlives the connection, so your loop keeps synthesizing idle frames for the empty seat. No `if (!cmd) continue` needed.

> **Warning:**
>
> Three things to know about synthesized idle frames. They are **not consumed inputs**: they advance neither the reconcile ack (`lastProcessed`) nor `renderTime`. They are **one reused instance** per client: read within the tick, don't store. And never build overrides by **spreading** a schema instance (`{ ...latest, yaw }`): schema fields are prototype accessors, so the spread copies none of them. Return `latest` itself, or name the fields you want.

Per-call `{ idle }` overrides the room policy for that call; `{ idle: false }` suppresses it.

## `setFixedTimestep(step, tickRate, options?)`

Hand the framework your step function and a rate; it runs the accumulator loop for you. Each `step` advances by the **same** fixed `dt = 1/tickRate`, and that rate is **advertised to clients** through the join handshake so they predict at the matching `dt`.

```ts
this.setFixedTimestep((ctx) => this.step(ctx), 30);    // 30 Hz
```

The `ctx` (a `StepContext`) carries the timing your simulation needs:

| Field | Meaning |
|---|---|
| `ctx.dt` | Fixed step in **seconds** (`1/tickRate`) |
| `ctx.dtMs` | Fixed step in **milliseconds** |
| `ctx.tick` | Monotonic step index |
| `ctx.subSteps` | Physics sub-steps per input tick (≥ 1) |
| `ctx.subDt` | Sub-step in seconds (`dt / subSteps`) |
| `ctx.subDtMs` | Sub-step in milliseconds |

> **Note:**
>
> Don't also pass a `tickRate` to `defineInput()`: `setFixedTimestep` is the single source of the simulation rate.

### Sub-stepping: high-rate physics on a low network rate

By default the input/network rate **is** the physics rate (see [the contract](https://docs.colyseus.io/netcode/determinism.md#the-contract)). Asking for "30 inputs/sec" forces 30 Hz simulation, which can be too coarse for stable physics. **Sub-stepping** is the escape hatch. Declare it once on the server:

```ts
this.setFixedTimestep((ctx) => {
  this.applyInputs(ctx);                                    // ONE input per client per step
  for (let i = 0; i < ctx.subSteps; i++) {
    this.world.step(ctx.subDt);
  }
}, 30, { subSteps: 2 });                                    // 30 inputs/sec, 60 Hz physics
```

One input still drives exactly one fixed step, so the replay invariant is untouched; *inside* that step, the engine integrates `subSteps` sub-steps of `subDt`. The handshake cascades `subSteps` alongside `tickRate`, so the client reconciler's `ctx` carries the **same** values. Your shared `step` function runs the identical loop on both sides.

Two rules keep it correct. Apply the input **once per step**, not once per sub-step (an impulse-like input applied per sub-step would double-fire). Never hand-derive the sub-step count or dt on either side: read `ctx.subSteps` / `ctx.subDt`.

## `setTimestep` (variable step)

For a non-deterministic game loop that just needs wall-clock delta (no prediction), `setTimestep(callback, delay?)` invokes your callback with the measured `deltaTime`:

```ts
this.setTimestep((deltaTime) => this.update(deltaTime));    // default ~16.6ms (60fps)
```

> **Warning:**
>
> `setSimulationInterval()` is the deprecated name for `setTimestep()` and still works (it forwards). For client-predicted games you want `setFixedTimestep()` instead: a variable step can't be replayed deterministically.

## Next

→ [Client Prediction](https://docs.colyseus.io/netcode/client-prediction.md): predict this input on the client and reconcile to the server.

---
Source: https://docs.colyseus.io/netcode/server-input


# Payments

Colyseus supports integration with various payment providers for secure and scalable game monetization.

### Payment Providers

- [Xsolla](https://docs.colyseus.io/payments/xsolla.md)

---
Source: https://docs.colyseus.io/payments


# Xsolla Payments Integration

[Xsolla](https://xsolla.com/?utm_source=colyseus&utm_medium=referral&utm_campaign=colyseus-docs) is a global **merchant of record** that supports a wide range of payment methods and currencies.

> **Note:**
>
> This article focuses on the payments functionality, but Xsolla offers a comprehensive suite of products and services for game developers. These include virtual storefronts, distribution, user account systems, in-game store management, analytics, anti-fraud tools, and more. For the full range of Xsolla's offerings, please consult the [Xsolla solutions page](https://xsolla.com/solutions).

### In this article, we will cover:

- **Payment Token Generation**: We will generate a payment token for Xsolla **Virtual Items** and **Subscriptions**
- **Pay Station UI**: We will use the generated token to open the Xsolla **Pay Station** UI
- **Xsolla Webhooks**: The Colyseus backend will respond to Xsolla **webhooks** for user validation and payment confirmation

- [Full source-code](https://github.com/colyseus/colyseus-xsolla-integration)
- [Xsolla Documentation](https://developers.xsolla.com/)

- [Live demo](https://xsolla.colyseus.cloud/)

## Xsolla Account Setup

### [Register for Xsolla Publisher Account](https://publisher.xsolla.com/signup?target_product=pay_station&utm_source=colyseus&utm_medium=referral&utm_campaign=colyseus-docs)

    By registering from this link, you will be supporting Colyseus

### Create Project

    ![Create Project](https://docs.colyseus.io/tutorial/xsolla/create-project.png)

### Create Virtual Item

    Virtual items are one-time purchases. If you plan to sell virtual items, let's create the first one.

    ![Create Virtual Item](https://docs.colyseus.io/tutorial/xsolla/create-virtual-item.png)

    > **Note:**
>
> See ["Set up virtual item"](https://developers.xsolla.com/doc/shop-builder/features/virtual-items/#shop_builder_virtual_items_set_up_in_pa_create_item) for more information.

### Configure Subscriptions

    Xsolla supports 3 types of subscriptions:

    - **Regular plan**: Allows subscribers to make regular payments to access your content.
    - **Lifetime plan**: One-time payment to access your content for life.
    - **Season pass**: One-time payment to access your content for a limited period of time.

    > **Note:**
>
> See ["Set up subscription plan"](https://developers.xsolla.com/doc/subscriptions/integration-guide/set-up-plan/) for more information.

### Create "All projects" API Key

    To create an "All projects" API Key, go to your company settings, select the "API keys" section, and create a new API key.

    ![Get API Credentials](https://docs.colyseus.io/tutorial/xsolla/api-key.png)

### Environment Variables

You will need to set the following environment variables in your Colyseus server. Make sure to replace the values with your own.

| Variable | How to get it |
|----------|---------------|
| `XSOLLA_MERCHANT_ID` | Found in your Xsolla dashboard under your Account's name |
| `XSOLLA_PROJECT_ID` | Found in your Xsolla project dashboard under your project's name |
| `XSOLLA_API_KEY` | Create an "All projects" API Key in your company settings → "API keys" section |
| `XSOLLA_WEBHOOK_SECRET_KEY` | See [Webhooks](#webhooks) section for instructions on how to get this value |
| `NODE_ENV` | Set to `development` for testing, `production` for live environment |

## The Payment Flow

The following diagram shows how the payment flow works.

![How webhooks work](https://docs.colyseus.io/tutorial/xsolla/webhooks-general.svg)

In the next sections, we will cover each step in detail.

---

### Generate the Payment Token

    To initiate a purchase, we first need to generate a **Payment Token**. This step is required to later open the Xsolla **Pay Station** UI.

    Use the following snippets and modify them to fit your needs.

    > **Warning:**
>
> For simplicity's sake, this article only presents the code for direct integration with Xsolla.
>  The snippets from this section should be used as backend HTTP API routes, as shown in [ `src/routes/xsolla.ts`](https://github.com/colyseus/colyseus-xsolla-integration/blob/main/src/routes/xsolla.ts) file from [ Colyseus Xsolla Integration](https://github.com/colyseus/colyseus-xsolla-integration/) repository.

    **Virtual Item(s)**

> **Note:**
>
> See ["Shop Builder API: Create payment token for purchase"](https://developers.xsolla.com/api/shop-builder/operation/admin-create-payment-token/) for more information.

```typescript filename="xsolla.ts"
const userId = "123";
const name = "John Doe";
const email = "john.doe@example.com";
const country = "US";

const items = [
    {
        sku: "my-virtual-item",
        quantity: 1
    }
];

const tokenResponse = await fetch(`https://store.xsolla.com/api/v3/project/${process.env.XSOLLA_PROJECT_ID}/admin/payment/token`, {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Basic ' + Buffer.from(`${process.env.XSOLLA_MERCHANT_ID}:${process.env.XSOLLA_API_KEY}`).toString('base64')
        // 'X-User-Ip': '127.0.0.1' // Optional: if user's country is unknown, providing the user's IP in 'X-User-Ip' header is an alternative option.
    },
    body: JSON.stringify({
        user: {
            id: { value: userId },
            name: { value: name },
            email: { value: email },

            // user.country.value parameter is used to select a currency for the order.
            // If the user's country is unknown, providing the user's IP in the 'X-User-Ip' header is an alternative option.
            country: { value: country, allow_modify: true }
        },
        purchase: { items },
        sandbox: (process.env.NODE_ENV === "development"), // Use "sandbox" mode in development
        settings: {
            language: "en",
            currency: "USD",
            // payment_method: 1380, // Optional: set preferred payment method
            return_url: "http://localhost:2567/",
            ui: {
                /**
                 * - "63295a9a2e47fab76f7708e1": light theme (default)
                 * - "63295aab2e47fab76f7708e3": the dark theme.
                 * - You can also create a custom theme:
                 *   Go to "Your project > Payments (Pay Station) > UI theme", and copy the ID of your custom theme.
                 */
                theme: "63295aab2e47fab76f7708e3"
            }
        },
        // custom_parameters: {
        // }
    })
});
```

**Subscription**

> **Note:**
>
> See ["Subscriptions API: Create token"](https://developers.xsolla.com/api/subscriptions/operation/create-token/) for more information.

```typescript filename="xsolla.ts"
const userId = "123";
const name = "John Doe";
const email = "john.doe@example.com";
const country = "US";

const subscription = {
    plan_id: "72qb7Cu9"
};

const tokenResponse = await fetch(`https://api.xsolla.com/merchant/v2/merchants/${process.env.XSOLLA_MERCHANT_ID}/token`, {
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Authorization': 'Basic ' + Buffer.from(`${process.env.XSOLLA_MERCHANT_ID}:${process.env.XSOLLA_API_KEY}`).toString('base64')
        // 'X-User-Ip': '127.0.0.1'
    },
    body: JSON.stringify({
        user: {
            id: { value: userId, hidden: true },
            name: { value: name, hidden: false },
            email: { value: email },
            // user.country.value parameter is used to select a currency for the order.
            // If the user's country is unknown, providing the user's IP in the 'X-User-Ip' header is an alternative option.
            country: { value: country, allow_modify: true }
        },
        purchase: { subscription },
        settings: {
            project_id: Number(process.env.XSOLLA_PROJECT_ID),
            // external_id: "unique_transaction_id", // OPTIONAL: add your unique transaction ID here
            language: "en",
            mode: (process.env.NODE_ENV === "development") ? "sandbox" : "production",
            currency: "USD",
        },
        // custom_parameters: {
        // }
    })
});
```

### Open Payment UI

    After generating the payment token, you can open the Xsolla **Pay Station** UI from the frontend.

    > **Note:**
>
> See ["Open Payment UI"](https://developers.xsolla.com/doc/subscriptions/integration-guide/open-payment-ui/) for more information.

    **Open in Iframe**

```typescript filename="client.ts"
//
// Open the Pay Station UI in an iframe
//
const client = new Client("http://localhost:2567");
const isSandbox = true; // Set to false in production

// Get the token from the backend. This will trigger the /xsolla/token backend route
client.http.post("/xsolla/token").then((response) => {
    // Create iframe
    var iframe = document.createElement("iframe");
    iframe.src = `https://${(isSandbox) ? "sandbox-" : ""}secure.xsolla.com/paystation4/?token=${response.data.token}`;
    iframe.width = "800";
    iframe.height = "930";
    iframe.allow = "clipboard-read; clipboard-write; payment";
    iframe.className = "xsolla-pay-station-iframe";

    // Add event listener to iframe
    document.body.appendChild(iframe);
});
```

**Open in Embed Widget**

```typescript filename="client.ts"
//
// Include the Xsolla Embed Widget script
//
var s = document.createElement('script');
s.type = "text/javascript";
s.async = true;
s.src = "https://cdn.xsolla.net/payments-bucket-prod/embed/1.5.3/widget.min.js";
var head = document.getElementsByTagName('head')[0];
head.appendChild(s);

//
// (...) With the Xsolla widget script included, you can now open the Pay Station UI
//

const client = new Client("http://localhost:2567");
const isSandbox = true; // Set to false in production

// Get the token from the backend. This will trigger the /xsolla/token backend route
client.http.post("/xsolla/token").then((response) => {
    // Initialize the Xsolla widget
    XPayStationWidget.init({
        access_token: response.data.token,
        sandbox: isSandbox
    });
    // Open the Pay Station UI
    XPayStationWidget.open();
});
```

**Open in New Window**

```typescript filename="client.ts"
//
// Open the Pay Station UI in a new window
//
const client = new Client("http://localhost:2567");
const isSandbox = true; // Set to false in production

// Get the token from the backend. This will trigger the /xsolla/token backend route
client.http.post("/xsolla/token").then((response) => {
    // Open new window
    window.open(`https://${(isSandbox) ? "sandbox-" : ""}secure.xsolla.com/paystation4/?token=${response.data.token}`, "_blank");
});
```

        **Listening to events from the Pay Station UI**

        ---

        The Pay Station UI triggers many events which you can listen to via post-message from the frontend.

```typescript filename="client.ts"
const postMessageListener = (event) => {
    if (!event.origin.endsWith(".xsolla.com")) {
        /* Skip messages from other origins except Xsolla */
        return;
    }

    const eventData = JSON.parse(event.data);
    switch (eventData.command) {
        case 'open-status-success':
            console.log('Success payment status page opened', eventData.data);
            break;

        case 'open-status-error':
            console.log('Error payment status page opened', eventData.data);
            break;

        case 'close':
            console.log('Payment UI closed', eventData.data);
            window.removeEventListener('message', postMessageListener);
            break;

        default:
            console.log('Unhandled event', eventData.command, eventData.data);
            break;
    }
};

/**
 * Listen to events from the Pay Station UI
 */
window.addEventListener('message', postMessageListener);
```

    **Example: Purchasing a single virtual item with the Pay Station UI**

    ![Pay Station UI](https://docs.colyseus.io/tutorial/xsolla/payment-ui.png)

### Webhooks

From your Xsolla project, navigate to **"Payments → Webhooks"**, paste the URL of your publicly accessible Colyseus server and click to **"Enable webhooks"**.

![Enable webhooks](https://docs.colyseus.io/tutorial/xsolla/webhooks-enable.png)

**Testing webhooks from a **local server****

---

You can test webhooks from a local server by tunneling it through Cloudflared.

1. Install Cloudflared:

```bash
npm install -g cloudflared
```

2. Start Cloudflared:

```bash
npx cloudflared tunnel --url http://localhost:2567
```

3. Copy the public URL:

```
https://[random-string].trycloudflare.com
```

4. Paste the public URL in the Xsolla Webhook server field and enable webhooks.

> **Warning:**
>
> Whenever you change the **Webhook server URL**, make sure to copy the updated **"Secret key"** value and paste it in the `XSOLLA_WEBHOOK_SECRET_KEY` environment variable.

> **Note:**
>
> See ["Set up webhooks in Publisher Account"](https://developers.xsolla.com/webhooks/overview/#section/Set-up-webhooks-in-Publisher-Account) for more information.

##### Required webhooks

For the full operation of the in-game store and payment management, it is necessary to implement the processing of the main webhooks:

| Webhook's `notification_type` | Action to perform |
|-------------------------------|-------------|
| `user_validation` | Validate user data against your database |
| `order_paid` | Grant items/access to user |
| `order_canceled` | Revoke items/access from user |
| `create_subscription` | Grant subscription access |
| `update_subscription` | Update user's subscription status |
| `cancel_subscription` | Revoke subscription access |

> **Note:**
>
> See [Xsolla Webhooks](https://developers.xsolla.com/webhooks/overview/) for more information.

##### Implementation example:

Use the following implementation as a reference to handle the webhooks in your Colyseus server.

You will need to bring your own implementation for the `handleUserValidation()`, `handleOrderPaid()`, `handleOrderCanceled()`, `handleCreateSubscription()`, `handleUpdateSubscription()`, `handleCancelSubscription()`, and `handleRefund()` methods.

```typescript filename="src/app.config.ts"
import { defineServer } from "colyseus";
import { type Request, type Response } from "express";
import crypto from "crypto";

const server = defineServer({
    // ...your rooms, routes, etc.

    express: (app) => {
        app.post('/webhook', (req: Request, res: Response) => {
            // Read raw body for signature verification
            let rawBody = '';
            req.on('data', chunk => rawBody += chunk);
            req.on('end', () => {
                try {
                    // Verify the webhook signature
                    if (!verifySignature(req, rawBody)) {
                        console.error('Invalid webhook signature');
                        res.status(401).json({ error: { code: "INVALID_SIGNATURE" } });
                        return;
                    }

                    // Process the webhook
                    processWebhook(JSON.parse(rawBody), res);
                } catch (err: any) {
                    console.error('Error processing Xsolla webhook:', err);
                    res.status(500).json({ error: { code: "INTERNAL_SERVER_ERROR", message: err.message } });
                }
            });
        });
    },
});

/**
 * Verify the webhook signature
 */
function verifySignature(req: Request, rawBody: string): boolean {
    const signature = req.headers.authorization;
    if (!signature) { return false; }

    // Create expected signature
    const expectedSignature = "Signature " + crypto
        .createHash("sha1")
        .update(rawBody + process.env.XSOLLA_WEBHOOK_SECRET_KEY)
        .digest("hex");

    // Constant-time comparison: a plain === leaks timing information
    const received = Buffer.from(signature);
    const expected = Buffer.from(expectedSignature);
    return received.length === expected.length && crypto.timingSafeEqual(received, expected);
}

/**
 * Process the webhook based on notification type
 */
function processWebhook(data: any, res: Response): void {
    console.log('Received Xsolla webhook:', data.notification_type);

    switch (data.notification_type) {
        case "user_validation": {
            // TODO: Implement user validation logic
            const isValid = handleUserValidation(data);
            console.log("User Validation:", { isValid });
            if (!isValid) {
                res.status(400).json({ error: { code: "INVALID_USER" } });
                return;
            }
            break;
        }
        case "order_paid": {
            // TODO: Implement order paid logic
            handleOrderPaid(data);
            break;
        }
        case "order_canceled": {
            // TODO: Implement order canceled logic
            handleOrderCanceled(data);
            break;
        }
        case "create_subscription": {
            // TODO: Implement create subscription logic
            handleCreateSubscription(data);
            break;
        }
        case "update_subscription": {
            // TODO: Implement update subscription logic
            handleUpdateSubscription(data);
            break;
        }
        case "cancel_subscription": {
            // TODO: Implement cancel subscription logic
            handleCancelSubscription(data);
            break;
        }
        case "refund": {
            // TODO: Implement refund logic
            handleRefund(data);
            break;
        }
        default: {
            console.log(`Unhandled notification type: ${data.notification_type}`, data);
            break;
        }
    }

    // Always respond with 204 No Content for successful webhook processing
    res.status(204).send();
}
```

## Recommendations

- Use the [ Authentication → HTTP Middleware](https://docs.colyseus.io/auth/http.md) to authenticate the user's request before generating the payment token.
- Use one of the [ Database](https://docs.colyseus.io/database.md) recommended solutions for storing, retrieving and validating the user's data.
- Disallow receiving webhooks from IPs that are not Xsolla IPs. (See [Xsolla IP ranges](https://developers.xsolla.com/webhooks/overview/#section/Webhook-listener))

---
Source: https://docs.colyseus.io/payments/xsolla


# Recipes & Guides

Recipes and guides for common tasks with Colyseus.

> **Warning:**
>
> Contributions are welcome! If you have a recipe or guide you'd like to share, please [open an issue](https://github.com/colyseus/docs/issues/new?title=Feedback%20for%20%E2%80%9CRecipes%E2%80%9D&labels=feedback) or submit a pull request.

- [The Command Pattern](https://docs.colyseus.io/recipes/command-pattern.md)
- [Custom Room ID](https://docs.colyseus.io/recipes/custom-room-id.md)
- [Deny a Player Joining a Room](https://docs.colyseus.io/recipes/deny-player-join-a-room.md)
- [Password Protect Room](https://docs.colyseus.io/recipes/password-protect-room.md)
- [Setup Server from Scratch with TypeScript](https://docs.colyseus.io/recipes/setup-server-from-scratch-typescript.md)

## Best Practices

General recommendations to keep your codebase healthy and readable for your team. They are all optional, but if followed can improve code readability and cleanliness.

- Keep your room classes as small as possible, delegating game-specific functionality to other composable structures.
- Keep your synchronizeable data structures as small as possible
    - Ideally, each class extending `Schema` should only have field definitions.
    - Do not implement _heavy_ game logic inside `Schema` structures. _Some_ logic is fine, specially if they're self-contained within the scope of the structure itself, mutating only its own properties.
- Rooms should have as little code as possible, and forward actions to other structures
- Your game logic may be handled by specialized structures, such as external functions, the [Command Pattern →](https://docs.colyseus.io/recipes/command-pattern.md), or an [Entity-Component System →](https://docs.colyseus.io/3rd-party-packages.md#entity-component-system-ecs).

- [3rd Party Packages](https://docs.colyseus.io/3rd-party-packages.md)
- [Unit Testing](https://docs.colyseus.io/tools/unit-testing.md)
- [Optimizing State](https://docs.colyseus.io/state/optimization.md)

---
Source: https://docs.colyseus.io/recipes


# The Command Pattern

Colyseus has an optional package called `@colyseus/command` that implements the Command Pattern. This pattern is useful when you need to decouple the classes that invoke the operation from the object that knows how to execute it.

The command pattern has several advantages, such as:

- It decouples the classes that invoke the operation from the object that knows how to execute the operation.
- You can create a sequence of commands by providing a queue system.
- Implementing extensions to add a new command is easy and can be done without changing the existing code.
- Have strict control over how and when commands are invoked.
- Improves code readability and the possibility of unit testing.

## Usage

Installation

```sh npm2yarn
npm install --save @colyseus/command
```

Initialize the `dispatcher` in your room implementation:

**TypeScript**

```ts filename="MyRoom.ts"
import { Room } from "colyseus";
import { Dispatcher } from "@colyseus/command";

import { OnJoinCommand } from "./OnJoinCommand";

class MyRoom extends Room {
  dispatcher = new Dispatcher(this);
  state = new YourState();

  onJoin(client, options) {
    this.dispatcher.dispatch(new OnJoinCommand(), {
        sessionId: client.sessionId
    });
  }

  onDispose() {
    this.dispatcher.stop();
  }
}
```

**JavaScript**

```js filename="MyRoom.js"
import { Room } from "colyseus";
import { Dispatcher } from "@colyseus/command";

import { OnJoinCommand } from "./OnJoinCommand";

class MyRoom extends Room {
  dispatcher = new Dispatcher(this);
  state = new YourState();

  onJoin(client, options) {
    this.dispatcher.dispatch(new OnJoinCommand(), {
        sessionId: client.sessionId
    });
  }

  onDispose() {
    this.dispatcher.stop();
  }
}
```

How a command implementation looks like:

**TypeScript**

```ts filename="OnJoinCommand.ts"
import { Command } from "@colyseus/command";

export class OnJoinCommand extends Command<MyRoom, {
    sessionId: string
}> {

  execute({ sessionId }) {
    this.state.players.set(sessionId, new Player());
  }

}
```

**JavaScript**

```js filename="OnJoinCommand.js"
import { Command } from "@colyseus/command";

export class OnJoinCommand extends Command {

  execute({ sessionId }) {
    this.state.players.set(sessionId, new Player());
  }

}
```

## See more

- See [command definitions](https://github.com/colyseus/command/blob/master/test/scenarios/CardGameScenario.ts)
- See [usage](https://github.com/colyseus/command/blob/master/test/Command.test.ts)
- See [implementation](https://github.com/colyseus/command/blob/master/src/index.ts)

---
Source: https://docs.colyseus.io/recipes/command-pattern


# Custom Room ID

You can override how you set the room ID for a new room.

To ensure we don't accidentally use the same room ID twice, we use the presence API, like this:

1. Get room ID already registered with the Presence API.
2. Generate room IDs until you generate one that is not already used.
3. Register the new room ID with the Presence API.

Step 2 here will most likely take only a single iteration, even with millions of rooms, with a 4 letter room ID. Using the Presence API this way also moves you closer to running your server on multiple machines: just switch to the [RedisPresence](https://docs.colyseus.io/server/presence.md#redis-presence).

See the code below:

```typescript
const LETTERS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";

export class MyRoom extends Room {
    // The channel where we register the room IDs.
    // This can be anything you want, it doesn't have to be `$mylobby`.
    LOBBY_CHANNEL = "$mylobby"

    // Generate a single 4 capital letter room ID.
    generateRoomIdSingle(): string {
        let result = '';
        for (var i = 0; i < 4; i++) {
            result += LETTERS.charAt(Math.floor(Math.random() * LETTERS.length));
        }
        return result;
    }

    // 1. Get room IDs already registered with the Presence API.
    // 2. Generate room IDs until you generate one that is not already used.
    // 3. Register the new room ID with the Presence API.
    async generateRoomId(): Promise<string> {
        const currentIds = await this.presence.smembers(this.LOBBY_CHANNEL);
        let id;
        do {
            id = this.generateRoomIdSingle();
        } while (currentIds.includes(id));

        await this.presence.sadd(this.LOBBY_CHANNEL, id);
        return id;
    }

    // Set `this.roomId` to the newly generated and registered room ID.
    async onCreate(options: any) {
        this.roomId = await this.generateRoomId();
    }

    // Free up the roomId that this room used.
    async onDispose() {
        this.presence.srem(this.LOBBY_CHANNEL, this.roomId);
    }
}
```

> **Warning:**
>
> There is a small race in this code where two onCreate calls could randomly generate the same code before either of them register it. This collision would give two rooms the same ID. This race is extremely unlikely however (with 1 million active rooms and true randomness, it'd still be 1 in 15 trillion).

---
Source: https://docs.colyseus.io/recipes/custom-room-id


# Deny a Player Joining a Room

You can deny a player connection by throwing a `ServerError` during the `onAuth()` or `onJoin()` methods.

When to deny a player connection will depend on your use-case.

Below you can see an example validating the client's auth token, and retrieving a `Hero` record linked with the user id. The check lives in the **static** `onAuth`. For token-bearing clients, the instance `onAuth` is skipped entirely (see [Room Authentication](https://docs.colyseus.io/auth/room.md)).

```ts filename="BattleRoom.ts"
import { Room, ServerError } from "colyseus";
import { JWT } from "@colyseus/auth";
import { Hero } from "../models/Hero"; // your own database model

const LEVEL_REQUIRED = 10;

export class BattleRoom extends Room {

  static async onAuth(token, options, context) {
    const userId = (await JWT.verify(token))._id;
    const hero = await Hero.findOne({ userId });

    if (!hero) {
      throw new ServerError(400, "'Hero' not found in the database!");

    } else if (hero.level < LEVEL_REQUIRED) {
      throw new ServerError(400, "Player does not have the level required for this room.");
    }

    // becomes `client.auth` / the 3rd argument of onJoin()
    return hero;
  }

}
```

The client sends its token and receives the error when trying to join the room:

```js filename="client.js"
client.auth.token = "YOUR AUTH TOKEN";

client.joinOrCreate("battle", {}).then(room => {
  // ...
}).catch(e => {
  console.log(e.message) // "'Hero' not found in the database!"
})
```

> **Note:**
>
> A room-specific gate that needs the room instance (the current phase, connected clients) belongs in `onJoin()` instead. Throwing a `ServerError` there rejects the join as well. See [Room Authentication](https://docs.colyseus.io/auth/room.md) for the full `onAuth` semantics.

---
Source: https://docs.colyseus.io/recipes/deny-player-join-a-room


# Password Protect Room

Colyseus has no built-in password concept. You compose one from three primitives. `filterBy()` groups same-password players into the same room, and `unlisted` hides the room from your room browser. An `onAuth()` check rejects wrong passwords on every join path (including joins by room ID).

> **Note:**
>
> Not sure what `unlisted` and `private` mean? See [Matchmaking Properties](https://docs.colyseus.io/matchmaker/visibility.md#matchmaking-properties).

## Allow the matchmaker to identify the `"password"` field

Define the `"password"` field inside the `filterBy()` method. `joinOrCreate()` then only matches rooms created with the same password:

```ts {5}
import { defineServer, defineRoom } from "colyseus";

const server = defineServer({
  rooms: {
    battle: defineRoom(BattleRoom).filterBy(['password']),
  }
});
```

> **Warning:**
>
> A filter field only constrains matchmaking when the client **provides** it. A client that omits `password` entirely can match any room. Always send the field, even when empty (`password: ""`), and keep the `onAuth()` check from step 3 as the safety net.

## Store the password and unlist the room

Keep passworded rooms out of lobby/listing queries with `unlisted`:

```ts filename="BattleRoom.ts"
export class BattleRoom extends Room {
  password: string | undefined;

  onCreate(options) {
    if (options.password) {
      this.password = options.password;
      this.setMatchmaking({ unlisted: true });
    }
  }
}
```

> **Warning:**
>
> Don't use `setPrivate()` here. A `private` room is excluded from `joinOrCreate()` matching, which defeats step 1: players sending the correct password would silently create a **new** room instead of joining the existing one. `unlisted` hides the room from listings while keeping it matchmade.

## Reject wrong passwords in `onAuth()`

`joinById()` ignores `filterBy()`, so anyone holding the room ID could walk in without a password. The room's `onAuth()` runs before every join, on every join path, so it closes that hole:

```ts filename="BattleRoom.ts"
import { Room, ServerError } from "colyseus";

export class BattleRoom extends Room {
  // ...

  onAuth(client, options) {
    if (this.password && options.password !== this.password) {
      throw new ServerError(400, "wrong password");
    }
    return true;
  }
}
```

---
Source: https://docs.colyseus.io/recipes/password-protect-room


# Setup Server from Scratch with TypeScript

A step-by-step guide for creating a Colyseus server with TypeScript, without the project template. Prefer `npm create colyseus-app@latest` unless you need full control over every file.

## Requirements

- [ Download and Install Node.js](https://nodejs.org/)

### Setup

Create a new empty directory.

```sh filename="Terminal"
mkdir colyseusServer
```

Go into the directory.

```sh filename="Terminal"
cd colyseusServer
```

Initialise npm with default options

```sh npm2yarn
npm init
```

Change the `"main"` and `"scripts"` property of the `package.json`.

```json filename="package.json"
{
  "main": "dist/main.js",
  "scripts": {
    "build": "tsc",
    "start": "tsx watch src/main.ts",
    "start:prod": "node dist/main.js"
  }
}
```

Install Dependencies

```sh npm2yarn
npm i colyseus
```

Install Dev Dependencies

```sh npm2yarn
npm i --save-dev typescript tsx
```

Create a new file called `tsconfig.json` in the root of the project

```json filename="tsconfig.json"
{
    "compilerOptions": {
        "outDir": "./dist",
        "target": "ESNext",
        "module": "CommonJS",
        "moduleResolution": "node",
        "strict": true,
        "allowJs": true,
        "strictNullChecks": false,
        "esModuleInterop": true,
        "experimentalDecorators": true,
        "skipLibCheck": true,
        "forceConsistentCasingInFileNames": true,
        "useDefineForClassFields": false
    },
    "include": [
      "src"
    ]
}
```

Create a new `src/rooms` directory

```sh filename="Terminal"
mkdir -p src/rooms
```

### State and Room

Define the synchronized state for your room.

**Schema Builder**

```ts filename="src/rooms/MyState.ts"
import { schema, t } from "@colyseus/schema";

export const Player = schema({
    x: t.number().default(0),
    y: t.number().default(0),
}, "Player");

export const MyState = schema({
    players: t.map(Player),
}, "MyState");
```

**Decorators**

```ts filename="src/rooms/MyState.ts"
import { Schema, MapSchema, type } from "@colyseus/schema";

export class Player extends Schema {
    @type("number") x: number = 0;
    @type("number") y: number = 0;
}

export class MyState extends Schema {
    @type({ map: Player }) players = new MapSchema<Player>();
}
```

Create a room class that uses the state.

```ts filename="src/rooms/MyRoom.ts"
import { Room, Client } from "colyseus";
import { MyState, Player } from "./MyState";

export class MyRoom extends Room {
    state = new MyState();

    onJoin(client: Client) {
        this.state.players.set(client.sessionId, new Player());
    }

    onLeave(client: Client) {
        this.state.players.delete(client.sessionId);
    }
}
```

### Entrypoint

Create a new file called `main.ts` in the `src` directory. It registers the room type and starts listening.

```ts filename="src/main.ts"
import { defineServer, defineRoom } from "colyseus";
import { MyRoom } from "./rooms/MyRoom";

const port = parseInt(process.env.PORT, 10) || 2567;

const server = defineServer({
    rooms: {
        my_room: defineRoom(MyRoom),
    },
});

server.listen(port);
```

Congrats, you finished the setup for a Colyseus server. Clients can now join it via `client.joinOrCreate("my_room")`. See [Joining Rooms](https://docs.colyseus.io/sdk.md#joining-rooms).

## Commands

Start the server in development with:

```sh npm2yarn
npm start
```

`tsx watch` automatically restarts the server when you change a file.

For production you first create a build.

```sh npm2yarn
npm run build
```

After that you can start the server with the `start:prod` command. This command uses the files which are created from the `build` command in the `dist` folder.

```sh npm2yarn
npm run start:prod
```

---
Source: https://docs.colyseus.io/recipes/setup-server-from-scratch-typescript


# Colyseus v1.0 Roadmap

Colyseus is an independent open-source project that has been around since 2015. The project has been used in production by several indies and companies and has been battle-tested in many different scenarios. The project is currently stable, but there are still many features and improvements that we'd like to add.

Issue-level tracking lives in the [1.0 milestone](https://github.com/colyseus/colyseus/milestone/4) on GitHub.

> **Note:**
>
> If you'd like to support the project, please consider [sponsoring](https://github.com/sponsors/endel) my work.

- **Netcode:**
    - Stabilize the [input and prediction](https://docs.colyseus.io/netcode.md) tools that 0.18 introduced. Settle the public API, and replace the runtime warnings that guard today's contracts with designs that resist misuse.
    - Close the SDK gap. The native C core and Flutter are complete. The Godot bindings read fields by struct offset, and GameMaker has no documented input API.
- **State Sync:**
    - **`@colyseus/schema` - Bidirectional schema instances:**
        - Allow to send schema instance updates from client to server. 0.18 covers flat primitive fields through [`defineInput()`](https://docs.colyseus.io/netcode/server-input.md). Nested schemas and collections are not supported yet.
        - Wild idea: support RPC calls via schema instances (?)
    - **Decouple `@colyseus/schema` from the core:**
        - Allow to use other serialization methods for the state. The serializer seam exists, but the core still depends on `@colyseus/schema` for message framing, [state views](https://docs.colyseus.io/state/view.md), rewind and dev mode.
- **WebTransport:**
    - Improve and stabilize [WebTransport](https://docs.colyseus.io/server/transport/webtransport.md) support. The transport carries no authentication headers on the socket connection, and latency simulation is not implemented.
- **Matchmaking:**
    - Improve filtering and sorting options. Every driver compares [filters](https://docs.colyseus.io/matchmaker.md#filter-by-filterby) by strict equality. There are no range or set operators.
- **General improvements:**
    - Introduce the concept of "low priority" and "high priority" messages. Drop "low priority" messages if clients are under backpressure.
    - Introduce "version check" to allow native SDKs to communicate with newer versions of the server
    - Graduate the beta and experimental packages to stable: [`@colyseus/admin`](https://docs.colyseus.io/admin.md), [`@colyseus/auth`](https://docs.colyseus.io/auth/module.md), the [Native SDK](https://docs.colyseus.io/getting-started/native-sdk.md), the [Drizzle driver](https://docs.colyseus.io/server/driver.md#drizzle-driver-postgresql), the [Bun transport](https://docs.colyseus.io/server/transport/bun-websockets.md), [WebTransport](https://docs.colyseus.io/server/transport/webtransport.md), and [streaming collections](https://docs.colyseus.io/state/streaming.md).

## Shipped in v0.18 (Aug 2026)

- **Database-first features:**
    - ~Since Colyseus doesn't currently have an official database recommendation tool, we can't provide built-in database-first features. Features that depend on a database tool are: player identity, leaderboards, configs, etc.~
        - Added the official [`@colyseus/database`](https://docs.colyseus.io/database.md) package: player identity, cloud saves, leaderboards, and live configs.
        - Added [`@colyseus/admin`](https://docs.colyseus.io/admin.md), the operations console built on top of it.
- **Native SDK:**
    - ~Shared native cross-platform SDK aimed to be used on Godot, Game Maker, Unreal, etc.~
        - Released the [Native SDK](https://docs.colyseus.io/getting-started/native-sdk.md), with dedicated [Godot](https://docs.colyseus.io/getting-started/godot.md), [GameMaker](https://docs.colyseus.io/getting-started/gamemaker.md), [Flutter](https://docs.colyseus.io/getting-started/flutter.md) and [Swift](https://docs.colyseus.io/getting-started/swift.md) integrations.
- **State Sync:**
    - ~**Client-side prediction:** Allow to specify client-side prediction techniques on the frontend~
        - Added first-class client-side prediction and lag compensation via `defineInput()` / `setFixedTimestep()` / `allowRewindState()` (server) and `room.input()` / `Predict` / `room.clock` (client). See [Netcode](https://docs.colyseus.io/netcode.md).
    - ~Yjs (CRDT) [connection provider](https://docs.yjs.dev/ecosystem/connection-provider) via Colyseus Rooms.~
        - Added `@colyseus/yjs`: a room plugin, a ready-made room, and a client provider that mirrors `y-websocket`.
    - Released [`@colyseus/schema` 5.0](https://docs.colyseus.io/state/schema.md), the foundation of this release: a faster encoder, the decorator-free `schema()` builder API, [delivery modifiers](https://docs.colyseus.io/state/schema.md#delivery-modifiers), [quantized floats](https://docs.colyseus.io/state/schema.md#quantized-floats-tquantized--tangle), and [streaming collections](https://docs.colyseus.io/state/streaming.md).
- **General improvements:**
    - ~Add request/response model to rooms ([#331](https://github.com/colyseus/colyseus/issues/331))~
        - Added a request/response model to room [messages](https://docs.colyseus.io/room.md#responding-to-a-message-requestresponse): the client awaits a reply with `room.request(type, payload)` or `room.send(type, payload, callback)`. The server answers by returning a value from its matching `onMessage(type, ...)` handler.
    - Added a framework-owned [fixed timestep](https://docs.colyseus.io/netcode/determinism.md): `setFixedTimestep()` runs the simulation at a constant step, and `setSimulationInterval()` was renamed to `setTimestep()`.

## Shipped in v0.17 (January 2026)

- **Matchmaking:**
    - ~SQL Driver - Provide a SQL driver as alternative to `@colyseus/redis-driver` _(should support SQLite / PostgreSQL, possibly on top of Kysely)_~
        - Added [PostgreSQL Driver](https://docs.colyseus.io/server/driver.md#drizzle-driver-postgresql)
    - ~**New "queue" matchmaking type:**~
        - ~A queue would keep more clients than needed before starting a match~
        - ~User specifies logic that combines clients into a new room~
        - ~Reserve seats for selected clients and redirect them to the newly created room~
        - Added [Queue matchmaking type](https://docs.colyseus.io/matchmaker/queue.md)
- **Full-stack + TypeScript Improvements:**
    - ~Allow to specify `client.auth` and `client.userData` types on the backend only once~
    - ~Allow to infer types for room message and payload definitions from frontend _(`room.send()`)_~
    - ~Allow to infer http routes and request/response body types from frontend _(`client.http.*`)_~

---
Source: https://docs.colyseus.io/roadmap


# Rooms

The `Room` class is the core building block of Colyseus. Each room instance holds one group of clients, who interact through shared state and messages.

## Why Rooms?

- **Isolation** - Players in Room A don't see or interact with players in Room B
- **Encapsulation** - Each room contains its own state, logic, and connected clients
- **Scalability** - Rooms are created on demand and _(optionally)_ disposed when empty
- **Flexibility** - One room class can spawn many instances (e.g., multiple matches of the same game type)

## Defining a Room

You can define a Room using a class that extends `Room`.

**Simple**

```ts filename="MyRoom.ts"
import { Room, Client } from "colyseus";
import { MyState } from "./MyState";

export class MyRoom extends Room {
    state = new MyState();

    onJoin(client: Client, options: any) {
        client.send("welcome", "Welcome to the room!");
    }
}
```

**With Full Type Safety**

You may specify the `metadata`, `state`, and `client` types for full type safety.

```ts filename="MyRoom.ts"
import { Room, type Client as MyClient } from "colyseus";
import { MyState } from "./MyState";

interface MyMetadata {
    difficulty: string;
    rating: number;
}

type Client = MyClient<{
    // specify the shape of outgoing messages to the client
    // so client.send() is type-checked
    // room.onMessage() on the frontend also becomes type-checked
    messages: {
        welcome: string;
    }
}>;

export class MyRoom extends Room<{
    state: MyState,
    metadata: MyMetadata,
    client: Client
}> {
    state = new MyState();

    onCreate(options: MyMetadata) {
        this.metadata = { difficulty: options.difficulty, rating: options.rating };
    }

    onJoin(client: Client, options: any) {
        client.send("welcome", "Welcome to the room!");
    }
}
```

## Room State

Set the synchronizable room state. See [State Synchronization](https://docs.colyseus.io/state.md) and [Schema](https://docs.colyseus.io/state/schema.md) for more details.

```typescript
import { Room } from "colyseus";
import { MyState } from "./MyState";

export class MyRoom extends Room {
    state = new MyState();
}
```

> **Warning:**
>
> The room's `state` is **mutable**. You should not reassign the `state` object, but rather mutate it directly when updating the state.

---

## Message Handling

Rooms have these methods available.

### On Messages

Register handlers to process messages sent by the frontend.

- The `type` argument can be either `string` or `number`.
- You can only define a single handler per message type.

#### Handler for specific type of message

```ts filename="MyRoom.ts"
messages = {
    "action": (client, payload) => {
        console.log(client.sessionId, "sent 'action' message: ", payload);
    }
}
```

> **Note:**
>
> Use `room.send(type, payload)` from the client SDK to send messages to the server.

#### Fallback for all messages

You can register a single handler as a fallback to handle **other** types of messages.

```ts filename="MyRoom.ts"
messages = {
    "action": (client, payload) => {
        //
        // Triggers when 'action' message is sent.
        //
    },

    "*": (client, type, payload) => {
        //
        // Triggers when any other type of message is sent,
        // excluding "action", which has its own specific handler defined above.
        //
        console.log(client.sessionId, "sent", type, payload);
    }
}
```

#### Registering handlers at runtime

The declarative `messages` map covers most cases. You may also register a handler imperatively with `this.onMessage()`. It returns a function that removes the handler when called.

```ts filename="MyRoom.ts"
onCreate() {
    const unbind = this.onMessage("action", (client, payload) => {
        // ...
    });

    // stop handling "action" messages
    unbind();
}
```

Use `this.onMessageBytes()` to receive raw `Uint8Array` messages sent via [`room.sendBytes()`](https://docs.colyseus.io/sdk.md) from the client SDK, skipping the default MsgPack decoding.

```ts filename="MyRoom.ts"
onCreate() {
    this.onMessageBytes("raw-input", (client, bytes) => {
        // bytes is a Uint8Array: decode it yourself
    });
}
```

#### Message input validation

You may provide a validation schema using the `validate()` helper with a Zod schema. If validation fails, the client is disconnected with close code `4002` (`WITH_ERROR`). For a request, the request settles as an error instead.

The validated and typed data will be passed as `payload` on the message handler.

```ts filename="MyRoom.ts"
import { Room, validate } from "colyseus";
import { z } from "zod";

// ...

messages = {
    "action": validate(z.object({
        x: z.number(),
        y: z.number()
    }), (client, payload) => {
        //
        // payload.x and payload.y are guaranteed to be numbers here.
        //
        console.log({ x: payload.x, y: payload.y });
    })
}
```

#### Responding to a message (request/response)

A message handler can **return a value** to answer a client that's waiting for a reply via [`room.request()` or `room.send(type, payload, callback)`](https://docs.colyseus.io/sdk.md#requestresponse). The same handlers serve both plain (fire-and-forget) sends and requests. The return value is sent back only when the client awaited a reply, and ignored otherwise.

```ts filename="MyRoom.ts"
messages = {
    // Return a value (sync or async): it becomes the client's response.
    "get-profile": async (client, { userId }) => {
        return await db.profiles.findById(userId);
    },

    // Throwing (or rejecting) settles the client's request as an error.
    "buy-item": (client, { itemId }) => {
        if (!this.canAfford(client, itemId)) {
            throw new Error("not enough coins");
        }
        return { ok: true };
    },

    // The 3rd argument (ctx) allows deliberate rejections with a typed reason.
    "join-team": (client, { team }, ctx) => {
        if (this.isTeamFull(team)) {
            return ctx.reject({ code: "TEAM_FULL", team });
        }
        return { ok: true };
    },
}
```

- The handler's return value is **awaited** before being sent, so returning a `Promise` works.
- If the handler throws or its `Promise` rejects, the client's request rejects with that error instead of timing out.
- Every handler also receives a third `ctx` argument. Call `ctx.reject(reason)` to settle the request as **rejected**: a deliberate business-logic "no", distinct from an error. On the client, the rejection arrives as an `Error` with `name: "rejected"` and the raw `reason` on its `.reason` property. See [Request/Response on the SDK](https://docs.colyseus.io/sdk.md#requestresponse).
- `ctx.resolve(value)` answers the request explicitly. Use it when the handler must keep working after replying. A plain `return` is equivalent otherwise.
- Only the handler registered for the message's specific type can answer a request. The [`"*"` fallback](#fallback-for-all-messages) is **not** eligible, and a request for a type with no handler rejects with a `no_handler` error.

---

## Lifecycle Events

Rooms expose a hook for every stage a client passes through: `onCreate`,
`onAuth`, `onJoin`, `onDrop`, `onReconnect`, `onLeave`, and `onDispose`, plus
the `devMode` and graceful-shutdown hooks. See
**[Room Lifecycle Events](https://docs.colyseus.io/room/lifecycle.md)** for the full reference.

---

## Room Configuration

### Game Loop

_Optional:_ Set a game loop that can change the state of the game. Default interval: 16.6ms (60fps).

Use **`setTimestep(callback, delay?)`** for a variable-step loop. The callback receives the measured wall-clock `deltaTime`:

```ts filename="MyRoom.ts"
onCreate () {
    this.setTimestep((deltaTime) => this.update(deltaTime));
}

update (deltaTime) {
    // implement your physics or world updates here!
    // this is a good place to update the room state
}
```

> **Note:**
>
> `setSimulationInterval()` is the previous name for `setTimestep()` and still works (it forwards). For **client-predicted** games, use the fixed-step loop **`setFixedTimestep(step, tickRate)`** instead. It advances by a constant `dt` and advertises the rate to predicting clients, which a variable step can't do deterministically. See [Server Input & Fixed Timestep](https://docs.colyseus.io/netcode/server-input.md).

---

### Visibility & Access

Three flags (`locked`, `private`, and `unlisted`) control who can find and
join a room, alongside `lock()`, `unlock()`, and `setMatchmaking()`. See
**[Room Visibility & Access](https://docs.colyseus.io/matchmaker/visibility.md)** for the full reference.

---

### Configuration Properties

| Property | Default | Description |
|----------|---------|-------------|
| `maxClients` | `Infinity` | Maximum number of clients allowed. Room is auto-locked when full. |
| `patchRate` | `50` | Frequency to send state updates to clients, in milliseconds (20fps). |
| `autoDispose` | `true` | Automatically dispose the room when last client disconnects. |
| `maxMessagesPerSecond` | `Infinity` | Maximum messages a client can send per second. Exceeding disconnects the client. |
| `seatReservationTimeout` | `15` | Seconds to wait for a client to effectively join after reserving a seat. |
| `locked` | _(read-only)_ | Whether the room is currently locked (via `maxClients` or `lock()`). |

---

## Communication

### Broadcast Message

Send a message to all connected clients.

Available options are:

- **`except`**: a [`Client`](https://docs.colyseus.io/room.md#client-instance), or array of `Client` instances not to send the message to
- **`afterNextPatch`**: waits until next patch to broadcast the message

**Broadcast to all**

Broadcasting a message to all clients:

```ts filename="MyRoom.ts"
messages = {
    "action": (client, payload) => {
        // broadcast a message to all clients
        this.broadcast("action-taken", "an action has been taken!");
    }
}
```

**Broadcast except for sender**

Broadcasting a message to all clients, except the sender.

```ts filename="MyRoom.ts"
messages = {
    "fire": (client, payload) => {
        // sends "fire" event to every client, except the one who triggered it.
        this.broadcast("fire", payload, { except: client });
    }
}
```

**Broadcast after state patch**

Broadcasting a message to all clients, only after a change in the state has been applied:

```ts filename="MyRoom.ts"
messages = {
    "destroy": (client, payload) => {
        // perform changes in your state!
        this.state.destroySomething();

        // this message will arrive only after new state has been applied
        this.broadcast("destroy", "something has been destroyed", { afterNextPatch: true });
    }
}
```

> **Note:**
>
> The client will receive the message in the [`onMessage()`](https://docs.colyseus.io/sdk.md#receiving-messages) callback.

---

### Broadcast Message (in bytes)

Send a raw byte array to all connected clients, skipping the default MsgPack encoding. The counterpart of [`client.sendBytes()`](#send-message-in-bytes) for broadcasts.

```ts filename="MyRoom.ts"
this.broadcastBytes("raw-update", new Uint8Array([ 1, 2, 3 ]), { except: client });
```

---

### Has Reached Max Clients

Returns whether the sum of connected clients and reserved seats exceeds the maximum number of clients.

```ts filename="MyRoom.ts"
onCreate(options) {
    if (this.hasReachedMaxClients()) {
        console.log("Room is full!");
    }
}
```

---

### Has Reserved Seat

Returns whether a seat reservation exists for the given `sessionId`: reserved but not yet consumed, or held for a [reconnection](https://docs.colyseus.io/room/reconnection.md). Pass the client's `reconnectionToken` as the second argument to check a reconnection reservation specifically.

```ts filename="MyRoom.ts"
if (this.hasReservedSeat(sessionId)) {
    // a client with this sessionId is expected to join
}
```

---

### Disconnect

Disconnect all clients, then dispose of the room. Returns a `Promise` that resolves when every client has been disconnected.

The optional `closeCode` is delivered to each client's [`onLeave` listener](https://docs.colyseus.io/sdk/connection.md#leaving-a-room). The default is `CONSENTED` (`4000`); custom application codes use `4011`–`4999`. See the [close-code table](#table-of-websocket-close-codes).

```ts filename="MyRoom.ts"
// disconnect all clients, then dispose of the room
await this.disconnect();

// same, with a custom close code
await this.disconnect(4020);
```

---

### Broadcast Patch

> **Warning:**
>
> **You may not need this!** - This method is called automatically by the framework.

This method will check whether mutations have occurred in the `state`, and broadcast them to all connected clients.

If you'd like to have control over when to broadcast patches, you can do this by disabling the default patch interval:

```ts filename="MyRoom.ts"
// disable automatic patches
patchRate = null;

onCreate() {
    this.clock.setInterval(() => {
        // only broadcast patches if your custom conditions are met.
        if (yourCondition) {
            this.broadcastPatch();
        }
    }, 2000);
}
```

---

## Reconnection

`allowReconnection()` lets a dropped client return to the room within a time
window, or under manual control. See **[Reconnection](https://docs.colyseus.io/room/reconnection.md)** for
the full server-side and client-side reference.

---

## Room Properties

### `roomId`

The unique identifier of the room. By default, a random 9-character-long string is assigned as the Room ID.

> **Note:**
>
> You may customize the Room ID during `onCreate()` by setting the `this.roomId` property. See [Recipes &raquo; Customize Room ID](https://docs.colyseus.io/recipes/custom-room-id.md)

---

### `roomName`

The name of the room you provided in the `rooms` configuration of [`defineServer()`](https://docs.colyseus.io/server.md#define-room-type).

---

### `state`

The synchronized state of the room.

> **Note:**
>
> See [State Synchronization](https://docs.colyseus.io/state.md).

---

### `metadata`

The room's matchmaking metadata. This data is used to filter rooms during matchmaking queries.

```ts filename="MyRoom.ts"
// Get metadata
console.log(this.metadata.difficulty);

// Set metadata during onCreate() only
onCreate(options) {
    this.metadata = { difficulty: "hard", rating: 1500 };
}
```

> **Warning:**
>
> The `metadata` setter can only be used during `onCreate()`. To update metadata after the room is created, use [`setMetadata()`](https://docs.colyseus.io/matchmaker/visibility.md#matchmaking-properties) or [`setMatchmaking()`](https://docs.colyseus.io/matchmaker/visibility.md#matchmaking-properties) instead.

---

### `clients`

The array of connected clients. See [Client Instance](#client-instance).

#### Sending a message to a specific client

```ts filename="MyRoom.ts"
// ...
this.clients.forEach((client) => {
    if (client.userData.team === "red") {
        client.send("hello", "world");
    }
});
// ...
```

#### Getting a client by `sessionId`.

```ts filename="MyRoom.ts"
// ...
const client = this.clients.get("UEsBFUBhK");
// ...
```

---

### `clock`

The `clock` provides timing controls that automatically clean up when the room is disposed, preventing memory leaks. Use it instead of `setTimeout` and `setInterval`.

```ts filename="MyRoom.ts"
// ...
onCreate() {
    this.clock.setTimeout(() => {
        console.log("This message will be printed after 5 seconds");
    }, 5000);

    this.clock.setInterval(() => {
        console.log("Current time:", this.clock.currentTime);
    }, 1000);
}
// ...
```

> **Note:**
>
> See [Timing Events](https://docs.colyseus.io/room/timing-events.md).

---

### `presence`

The `presence` is used as a shared in-memory database for your cluster, and for pub/sub operations between rooms.

```ts filename="MyRoom.ts"
// ...
onCreate() {
    // publish an event to all rooms listening to "event-from-another-room"
    this.presence.publish("event-name-from-another-room", { hello: "world" });

    // subscribe to events from another room
    this.presence.subscribe("event-name-from-another-room", (payload) => {
        console.log("Received event from another room!", payload);
    });

    // set arbitrary value to the presence
    this.presence.set("arbitrary-key", "value");
}
// ...
```

> **Note:**
>
> See [Presence API](https://docs.colyseus.io/server/presence.md).

---

## Client Instance

The `client` instance from the backend is responsible for the **transport** layer between the server and the client. Do not confuse it with the [`Client` from the frontend SDK](https://docs.colyseus.io/sdk.md), as they have completely different purposes.

You operate on `client` instances from [`this.clients`](#clients), [`Room#onJoin()`](https://docs.colyseus.io/room/lifecycle.md#on-join), [`Room#onLeave()`](https://docs.colyseus.io/room/lifecycle.md#on-leave) and [`Room#onMessage()`](#on-messages).

### Properties

#### `sessionId`

Unique identifier of the client connection.

```ts filename="MyRoom.ts"
// ...
onJoin(client, options) {
    console.log(client.sessionId);
}
// ...
```

> **Note:**
>
> In the frontend, you can find the [`sessionId` in the `room` instance](https://docs.colyseus.io/sdk.md#room-reference).

---

#### `userData`

The `client.userData` can be used to store player-specific data easily accessible via the `client` instance. This property is meant for convenience.

```ts filename="MyRoom.ts"
// ...
onJoin(client, options) {
  client.userData = { team: (this.clients.length % 2 === 0) ? "red" : "blue" };
}
onLeave(client)  {
  console.log(client.userData.team);
}
// ...
```

---

#### `auth`

The `client.auth` property holds the data returned by the [`onAuth()`](https://docs.colyseus.io/room/lifecycle.md#on-auth) method.

```ts filename="MyRoom.ts"
onAuth(client, options, context) {
    return { userId: "123" };
}

onJoin(client, options) {
    console.log(client.auth.userId);
}
```

> **Note:**
>
> See [Authentication](https://docs.colyseus.io/auth.md) for more details.

---

#### `view`

The `client.view` property is used for state filtering - allowing you to control which parts of the state a client can see.

```ts filename="MyRoom.ts"
import { StateView } from "@colyseus/schema";

onJoin(client, options) {
    // Set the client's view to filter portions of the state they receive
    client.view = new StateView();
}
```

> **Note:**
>
> See [ State Synchronization → State View](https://docs.colyseus.io/state/view.md) for more details.

---

#### `reconnectionToken`

The unique token used for reconnection. This token is regenerated each time the client connects.

```ts filename="MyRoom.ts"
onJoin(client, options) {
    console.log(client.reconnectionToken);
}
```

---

### Methods

#### Send Message

Send a type of message to the client. Messages are encoded with MsgPack and can hold any JSON-serializable data structure.

The `type` can be either a `string` or a `number`.

```ts filename="MyRoom.ts"
//
// sending message of string type ("powerup")
//
client.send("powerup", { kind: "ammo" });

//
// sending message of number type (1)
//
client.send(1, { kind: "ammo"});
```

> **Note:**
>
> [See how to handle `onMessage` from the frontend SDK](https://docs.colyseus.io/sdk.md#receiving-messages)

---

#### Send Message (in bytes)

Send a raw byte array message to the client.

The `type` can be either a `string` or a `number`.

This method is useful if you'd like to manually encode a message, rather than the default encoding (MsgPack).

```ts filename="MyRoom.ts"
//
// sending message of string type ("powerup")
//
client.sendBytes("powerup", new Uint8Array([ 172, 72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100, 33 ]));

//
// sending message of number type (1)
//
client.sendBytes(1, new Uint8Array([ 172, 72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100, 33 ]));
```

---

#### Leave Room

Force disconnection of the `client` with the room. You may send a custom `code` when closing the connection, with values between `4011` and `4999`. Codes `4000`–`4010` are reserved by the framework. See the [table of WebSocket close codes](#table-of-websocket-close-codes) below.

```ts filename="MyRoom.ts"
// disconnect this client with the default code (4000, CONSENTED)
client.leave();

// disconnect this client with a custom code
client.leave(4020);
```

> **Note:**
>
> This call will trigger the [`room.onLeave`](https://docs.colyseus.io/sdk/connection.md#leaving-a-room) event on the frontend.

#### Table of WebSocket close codes

| Close code (uint16) | Codename               | Internal | Customizable | Description |
|---------------------|------------------------|----------|--------------|-------------|
| `0` - `999`             |                        | Yes      | No           | Unused |
| `1000`                | `NORMAL_CLOSURE`         | No       | No           | Successful operation / regular socket shutdown |
| `1001`                | `GOING_AWAY`     | No       | No           | Client is leaving (browser tab closing) |
| `1002`                | *Protocol error* | Yes      | No           | Endpoint received a malformed frame |
| `1003`                | *Unsupported frame*    | Yes      | No           | Endpoint received an unsupported frame (e.g. binary-only endpoint received text frame) |
| `1004`                |                        | Yes      | No           | Reserved |
| `1005`                | `NO_STATUS_RECEIVED`     | Yes      | No           | Expected close status, received none |
| `1006`                | `ABNORMAL_CLOSURE`       | Yes      | No           | No close code frame has been received |
| `1007`                | *Unsupported payload*  | Yes      | No           | Endpoint received inconsistent message (e.g. malformed UTF-8) |
| `1008`                | *Policy violation*     | No       | No           | Generic code used for situations other than 1003 and 1009 |
| `1009`                | *Frame too large*      | No       | No           | Endpoint won't process large frame |
| `1010`                | *Mandatory extension*  | No       | No           | Client wanted an extension which server did not negotiate |
| `1011`                | *Server error*         | No       | No           | Internal server error while operating |
| `1012`                | *Service restart*      | No       | No           | Server/service is restarting |
| `1013`                | *Try again later*      | No       | No           | Temporary server condition forced blocking client's request |
| `1014`                | *Bad gateway*          | No       | No           | Server acting as gateway received an invalid response |
| `1015`                | *TLS handshake fail*   | Yes      | No           | Transport Layer Security handshake failure |
| `1016` - `1999`         |                        | Yes      | No           | Reserved for future use by the WebSocket standard. |
| `2000` - `2999`         |                        | Yes      | Yes          | Reserved for use by WebSocket extensions |
| `3000` - `3999`         |                        | No       | Yes          | 	Available for use by libraries and frameworks. May not be used by applications. Available for registration at the IANA via first-come, first-serve. |
| `4000`                | `CONSENTED`            | No       | No           | Client left intentionally (`room.leave()`) |
| `4001`                | `SERVER_SHUTDOWN`      | No       | No           | Server graceful shutdown (production) |
| `4002`                | `WITH_ERROR`           | No       | No           | Closed due to an error |
| `4003`                | `FAILED_TO_RECONNECT`  | No       | No           | All reconnection attempts failed, or the server denied/failed the reconnection |
| `4010`                | `MAY_TRY_RECONNECT`   | No       | No           | Server shutdown in dev mode (allows reconnect) |
| `4011` - `4999` |              | No       | Yes          | Available for applications |

---

## Built-in Rooms

Colyseus ships pre-built room types you can use directly or extend. Lobby and
Queue are documented under Matchmaking, since that's the job they do:

- [Lobby Room](https://docs.colyseus.io/matchmaker/lobby.md): A live listing of available rooms, the backend for a room browser UI.
- [Queue Room](https://docs.colyseus.io/matchmaker/queue.md): A matchmaking queue that groups players over time and spawns a match room when a group is ready.
- [Relay Room](https://docs.colyseus.io/room/relay.md): A lightweight relay that broadcasts client messages to everyone else, with no authoritative state.

## Next Steps

- [State Synchronization](https://docs.colyseus.io/state.md) - Learn how to define and synchronize room state
- [Server Configuration](https://docs.colyseus.io/server.md) - Configure your Colyseus server
- [Timing Events](https://docs.colyseus.io/room/timing-events.md) - Schedule delayed and recurring events

---
Source: https://docs.colyseus.io/room


# Exception Handling in Rooms

> **Note:**
>
> This feature is available since `@colyseus/core` version `0.15.55`.

By default, if an uncaught exception occurs inside a room, the server is shut down ungracefully. This shutdown disconnects all clients, and the server will restart or stop running (depending on how it's configured).

You can now handle uncaught exceptions by implementing the `onUncaughtException()` method in your room class. With this method, all user-facing callbacks will be wrapped in try/catch blocks, and any exceptions will be forwarded to `onUncaughtException()`.

```ts filename="MyRoom.ts"
import { Room } from "colyseus";

class MyRoom extends Room {
    // ...
    onUncaughtException (err: Error, methodName: string) {
        console.error("An error ocurred in", methodName, ":", err);
        err.cause // original unhandled error
        err.message // original error message
    }
    // ...
}
```

Methods that can throw exceptions are:

- `onCreate()`
- `onAuth()`
- `onJoin()`
- `onDrop()`
- `onReconnect()`
- `onLeave()`
- `onDispose()`
- `onMessage()`
- `setTimestep()` / `setFixedTimestep()` (and the deprecated `setSimulationInterval()` alias)
- `clock.setTimeout()`
- `clock.setInterval()`

> **Warning:**
>
> **Exceptions in `onAuth` and `onJoin`**
>
> Any uncaught exception thrown during `onAuth` or `onJoin` will still result in a failure to join the room, even if caught by `onUncaughtException`. If needed, you may have your own try/catch block in `onAuth` or `onJoin` to ensure clients can join even in case of an exception.

---

## Exception Types

The following exceptions are thrown by the server and can be caught by `onUncaughtException`:

Each exception type has context information that can be accessed through its properties.

### OnCreateException

When the exception is thrown inside the `onCreate` method.

**Properties:**

- `options` - the options passed to the room's `onCreate` method.

```ts filename="MyRoom.ts"
import { OnCreateException } from "colyseus";
// ...
    onUncaughtException (err: Error, methodName: string) {
        if (err instanceof OnCreateException) {
            err.options; // the options passed to the room's `onCreate` method.
            err.cause; // original unhandled error
            err.message; // original error message
        }
    }
// ...
```

### OnAuthException

When the exception is thrown inside the `onAuth` method.

**Properties:**

- `client` - the client that is trying to authenticate.
- `options` - the options passed to the room's `onAuth` method.

```ts filename="MyRoom.ts"
import { OnAuthException } from "colyseus";
// ...
    onUncaughtException (err: Error, methodName: string) {
        if (err instanceof OnAuthException) {
            err.client; // the client that is trying to authenticate.
            err.options; // the options passed to the room's `onAuth` method.
            err.cause; // original unhandled error
            err.message; // original error message
        }
    }
```

### OnJoinException

When the exception is thrown inside the `onJoin` method.

**Properties:**

- `client` - the client that is trying to join the room.
- `options` - the options passed to the room's `onJoin` method.

```ts filename="MyRoom.ts"
import { OnJoinException } from "colyseus";
// ...
    onUncaughtException (err: Error, methodName: string) {
        if (err instanceof OnJoinException) {
            err.client; // the client that is trying to join the room.
            err.options; // the options passed to the room's `onJoin` method.
            err.cause; // original unhandled error
            err.message; // original error message
        }
    }
```

### OnLeaveException

When the exception is thrown inside the `onLeave` method.

**Properties:**

- `client` - the client that is leaving the room.
- `consented` - the close code associated with the client leaving the room.

```ts filename="MyRoom.ts"
import { OnLeaveException } from "colyseus";
// ...
    onUncaughtException (err: Error, methodName: string) {
        if (err instanceof OnLeaveException) {
            err.client; // the client that is leaving the room.
            err.consented; // the close code associated with the client leaving the room.
            err.cause; // original unhandled error
            err.message; // original error message
        }
    }
```

---

### OnDropException / OnReconnectException

When the exception is thrown inside `onDrop` (properties: `client`, `code`) or `onReconnect` (property: `client`).

> **Warning:**
>
> In 0.18.1 these two classes are raised internally but not yet exported from the `colyseus` package, so an `instanceof` check isn't possible. Inspect the `methodName` argument (`"onDrop"` / `"onReconnect"`) instead.

### OnMessageException

When the exception is thrown inside the `onMessage` method.

**Properties:**

- `client` - the client that sent the message.
- `payload` - the message payload sent by the client.
- `type` - the message type sent by the client.

```ts filename="MyRoom.ts"
import { OnMessageException } from "colyseus";
// ...
    onUncaughtException (err: Error, methodName: string) {
        if (err instanceof OnMessageException) {
            err.client; // the client that sent the message.
            err.payload; // the message payload sent by the client.
            err.type; // the message type sent by the client.
            err.cause; // original unhandled error
            err.message; // original error message
        }
    }
```

### OnDisposeException

When the exception is thrown inside the `onDispose` method.

```ts filename="MyRoom.ts"
import { OnDisposeException } from "colyseus";
// ...
    onUncaughtException (err: Error, methodName: string) {
        if (err instanceof OnDisposeException) {
            err.cause; // original unhandled error
            err.message; // original error message
        }
    }
```

### TimestepException

When the exception is thrown inside the `setTimestep` or `setFixedTimestep` callback (`methodName` is `"setTimestep"` / `"setFixedTimestep"`). `SimulationIntervalException` remains as a deprecated alias.

```ts filename="MyRoom.ts"
import { TimestepException } from "colyseus";
// ...
    onUncaughtException (err: Error, methodName: string) {
        if (err instanceof TimestepException) {
            err.cause; // original unhandled error
            err.message; // original error message
        }
    }
```

### TimedEventException

When the exception is thrown inside the `clock.setTimeout` or `clock.setInterval` methods.

**Properties:**

- `args` - optional arguments passed to the timeout or interval.

```ts filename="MyRoom.ts"
import { TimedEventException } from "colyseus";
// ...
    onUncaughtException (err: Error, methodName: string) {
        if (err instanceof TimedEventException) {
            err.args; // optional arguments passed to the timeout or interval.
            err.cause; // original unhandled error
            err.message; // original error message
        }
    }
```

---
Source: https://docs.colyseus.io/room/exception-handling


# Room Lifecycle Events

These hooks are called automatically, in the order a client moves through the
room: created, authenticated, joined, dropped, reconnected, left, disposed.
[`async`/`await`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function)
is supported in all of them.

The room's lifecycle events are called automatically. [`async`/`await`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/async_function) is supported in all of them.

**TypeScript**

```ts filename="MyRoom.ts"
import { Room, Client, AuthContext } from "colyseus";

export class MyRoom extends Room {
    // (optional) Validate client auth token before joining/creating the room
    onAuth (client: Client, options: any, context: AuthContext) { }

    // When room is initialized
    onCreate (options: any) { }

    // When the client successfully joins the room
    onJoin (client: Client, options: any, auth: any) { }

    // When a client disconnects unexpectedly (use allowReconnection here)
    onDrop (client: Client, code?: number) { }

    // When a client successfully reconnects
    onReconnect (client: Client) { }

    // When a client effectively leaves the room
    onLeave (client: Client, code?: number) { }

    // Cleanup callback, called after there are no more clients in the room. (see `autoDispose`)
    onDispose () { }
}
```

**JavaScript**

```js filename="MyRoom.js"
import { Room } from "colyseus";

export class MyRoom extends Room {
    // (optional) Validate client auth token before joining/creating the room
    onAuth (client, options, context) { }

    // When room is initialized
    onCreate (options) { }

    // When the client successfully joins the room
    onJoin (client, options, auth) { }

    // When a client disconnects unexpectedly (use allowReconnection here)
    onDrop (client, code) { }

    // When a client successfully reconnects
    onReconnect (client) { }

    // When a client effectively leaves the room
    onLeave (client, code) { }

    // Cleanup callback, called after there are no more clients in the room. (see `autoDispose`)
    onDispose () { }
}
```

## On Create

Called once, when the room is created by the matchmaker. `options` is the merged values specified on [`defineRoom()`](https://docs.colyseus.io/server.md#define-room-type) with the options provided from the SDK at [`.joinOrCreate()`](https://docs.colyseus.io/sdk.md#join-or-create-recommended) or [`.join()`](https://docs.colyseus.io/sdk.md#other-join-methods).

```ts filename="MyRoom.ts"
onCreate (options) {
    /**
     * This is a good place to initialize your room state.
     */
}
```

The server may overwrite options in [`defineRoom()`](https://docs.colyseus.io/server.md#define-room-type) for authority over client-provided options:

**Backend**

```ts filename="app.config.ts"
// (backend)
const server = defineServer({
  rooms: {
    my_room: defineRoom(MyRoom, { map: "cs_assault" })
  }
})
```

**Frontend**

The `options` argument is provided by the client upon room creation:

```js filename="client.js"
// (frontend - using the javascript sdk)
// ...
client.joinOrCreate("my_room", {
    name: "Jake",
    map: "de_dust2"
})
```

On this example, the `map` option is `"cs_assault"` during `onCreate()`, and `"de_dust2"` during `onJoin()`.

---

## On Auth

The `onAuth` method is called before `onJoin`, and it is responsible for validating the client's request to join a room.

**Instance onAuth**

```ts filename="MyRoom.ts"
async onAuth (client, options, context) {
    /**
     * This is a good place to validate the client's auth token.
     */
}
```
    **Arguments**
    - `client`: A reference to the client that is trying to join the room.
    - `options`: Options provided by the frontend SDK.
    - `context`: The request context, containing:
        - `.token` - the authentication token sent by the client.
        - `.headers` - the headers sent by the client.
        - `.ip` - the IP address of the client.

**Static onAuth**

```ts filename="MyRoom.ts"
static async onAuth (token, options, context) {
    /**
     * This is a good place to validate the client's auth token.
     */
}
```
    **Arguments**
    - `token`: The authentication token sent by the client.
    - `options`: Options provided by the frontend SDK.
    - `context`: The request context, containing:
        - `.token` - the authentication token sent by the client.
        - `.headers` - the headers sent by the client.
        - `.ip` - the IP address of the client.

> **Note:**
>
> See [Authentication](https://docs.colyseus.io/auth/room.md) for more details.

---

## On Join

Triggered when a client successfully joins the room, after a successful `onAuth`.

**Parameters:**

- `client`: A reference to the client that joined the room.
- `options`: Options provided by the Client SDK. _(Merged with default values provided by [Server#define()](https://docs.colyseus.io/server.md#define-room-type))_
- `auth`: _(optional)_ auth data returned by [`onAuth`](#on-auth) method.

```ts filename="MyRoom.ts"
async onJoin (client, options, auth?) {
    /**
     * This is a good place to add the client to the state.
     */
}
```

> **Note:**
>
> See Client SDK on [`.joinOrCreate()`](https://docs.colyseus.io/sdk.md#join-or-create-recommended) and [`.join()`](https://docs.colyseus.io/sdk.md#other-join-methods).

---

## On Drop

> **Note:**
>
> New in 0.17. See [Automatic Reconnection](https://docs.colyseus.io/room/reconnection.md) for more details.

Triggered when a client disconnects unexpectedly (without consent). This hook is the recommended place to use `allowReconnection()`.

**Parameters:**

- `client`: The client that was dropped from the room.
- `code`: _(optional)_ The close code of the leave event.

```ts filename="MyRoom.ts"
async onDrop (client, code) {
    await this.allowReconnection(client, 20);
}
```

> **Note:**
>
> If `onDrop` is not defined, `onLeave` will be called for both consented and non-consented disconnections.

---

## On Reconnect

> **Note:**
>
> New in 0.17. See [Automatic Reconnection](https://docs.colyseus.io/room/reconnection.md) for more details.

Triggered when a client successfully reconnects to the room after calling `allowReconnection()`.

**Parameters:**

- `client`: The client that reconnected to the room.

```ts filename="MyRoom.ts"
onReconnect (client) {
    /**
     * Client has reconnected successfully.
     */
    console.log(client.sessionId, "reconnected!");
}
```

---

## On Leave

Triggered when a client effectively leaves the room.

- If `onDrop` is defined: `onLeave` is called for consented disconnections (client called `.leave()`), and also after a drop once reconnection fails, times out, or was not allowed.
- If `onDrop` is not defined: `onLeave` is called for both consented and non-consented disconnections.

**Parameters:**

- `client`: The client that left the room.
- `code`: _(optional)_ The close code of the leave event.

```ts filename="MyRoom.ts"
async onLeave (client, code) {
    /**
     * This is a good place to remove the client from the state.
     */
}
```

You may define this function as `async`:

**Synchronous**

``` typescript
onLeave(client, code) {
    if (this.state.players.has(client.sessionId)) {
        this.state.players.delete(client.sessionId);
    }
}
```

**Asynchronous**

``` typescript
async onLeave(client, code) {
    const player = this.state.players.get(client.sessionId);
    await persistUserOnDatabase(player);
}
```

> **Note:**
>
> At [Graceful Shutdown](https://docs.colyseus.io/server/graceful-shutdown.md), `onLeave` is called with `code = CloseCode.SERVER_SHUTDOWN` for all clients.

---

## On Dispose

The `onDispose()` method is called before the room is destroyed, which happens when:

- there are no more clients left in the room, and `autoDispose` is set to `true` (default)
- you manually call [`.disconnect()`](https://docs.colyseus.io/room.md#disconnect).

```ts filename="MyRoom.ts"
async onDispose() {
    /**
     * This is a good place to perform cleanup tasks.
     */
}
```

You may define `async onDispose()` an asynchronous method in order to persist some data in the database. In fact, this is a great place to persist player's data in the database after a game match ends.

> **Note:**
>
> At [Graceful Shutdown](https://docs.colyseus.io/server/graceful-shutdown.md), `onDispose` is called for all rooms.

---

## On Unhandled Exception

Opt-in to catch unhandled exceptions in your room. This method is called when an unhandled exception occurs in any of the lifecycle methods.

```ts filename="MyRoom.ts"
onUncaughtException (err: Error, methodName: string) {
    console.error("An error occurred in", methodName, ":", err);
    err.cause // original unhandled error
    err.message // original error message
}
```

> **Note:**
>
> See [Exception Handling](https://docs.colyseus.io/room/exception-handling.md) for more details.

---

## On Before Patch

The `onBeforePatch` lifecycle hook is triggered before state synchronization, at patch rate frequency. (see [`patchRate`](https://docs.colyseus.io/room.md#configuration-properties))

```ts filename="MyRoom.ts"
onBeforePatch(state) {
    /*
     * Here you can mutate something in the state just before it is encoded &
     * synchronized with all clients
     */
}
```

---

## On Cache Room (`devMode`)

An optional hook to cache external data when [`devMode`](https://docs.colyseus.io/server/devmode.md) is enabled.
(See [restoring data outside the room's state](https://docs.colyseus.io/server/devmode.md#restoring-external-data))

```ts filename="MyRoom.ts"
export class MyRoom extends Room {
  // ...

  onCacheRoom() {
    return { foo: "bar" };
  }
}
```

---

## On Restore Room (`devMode`)

An optional hook to reprocess/restore data which was returned and stored from the previous hook [`onCacheRoom`](#on-cache-room-devmode) when [Development Mode](https://docs.colyseus.io/server/devmode.md) is enabled.

```ts filename="MyRoom.ts"
export class MyRoom extends Room {
  // ...

  onRestoreRoom(cachedData: any): void {
    console.log("ROOM HAS BEEN RESTORED!", cachedData);

    this.state.players.forEach(player => {
      player.method(cachedData["foo"]);
    });
  }
}
```

> **Note:**
>
> See [Restoring data outside the room's `state`](https://docs.colyseus.io/server/devmode.md#restoring-external-data)

---

## On Before Shutdown

The `onBeforeShutdown` lifecycle hook is called as part of the [Graceful Shutdown](https://docs.colyseus.io/server/graceful-shutdown.md) process. The process will only truly shutdown after all rooms have been disposed.

By default, the room will disconnect all clients and dispose itself immediately.

You may customize how the room should behave during the shutdown process:

```ts filename="MyRoom.ts"
onBeforeShutdown() {
    //
    // Notify users that process is shutting down, they may need to save their progress and join a new room
    //
    this.broadcast("going-down", "Server is shutting down. Please save your progress and join a new room.");

    //
    // Disconnect all clients after 5 minutes
    //
    this.clock.setTimeout(() => this.disconnect(), 5 * 60 * 1000);
}
```

> **Note:**
>
> See [graceful shutdown](https://docs.colyseus.io/server/graceful-shutdown.md) for more details.

---
Source: https://docs.colyseus.io/room/lifecycle


# Message Composability

The `Messages<R>` type allows you to define reusable, type-safe message handlers that can be composed and spread into your Room's `messages` property. This pattern is useful for:

- **Code reuse**: Share common message handlers across multiple rooms
- **Modularity**: Organize handlers into separate files or modules
- **Third-party libraries**: Create and distribute reusable message handler packages

> **Note:**
>
> This pattern requires TypeScript for full type-safety.

## Defining Reusable Message Handlers

Use the `Messages<R>` generic type to define a set of message handlers outside of your Room class. The generic parameter `R` should be your Room class to ensure proper typing for `this` context.

```typescript filename="thirdPartyMessages.ts"
import { Room, validate, type Client, type Messages } from "colyseus";
import { z } from "zod";
import { MyRoom } from "./MyRoom";

// Define a custom client type if needed
type MyClient = Client<{ userData: { name: string } }>;

export const thirdPartyMessages: Messages<MyRoom> = {
  // Handler with validation
  chat: validate(
    z.object({
      text: z.string().max(500),
    }),
    function (client: MyClient, message) {
      // message.text is guaranteed to be a string (max 500 chars)
      this.broadcast("chat", {
        sender: client.sessionId,
        text: message.text,
      });
    }
  ),
};
```

> **Warning:**
>
> When using `validate()` with the `Messages<R>` type, an arrow function won't give you access to `this` (the Room instance). Use a regular `function` expression instead.

## Composing Messages in Your Room

Use the spread operator to compose multiple message handler objects into your Room's `messages` property:

```typescript filename="MyRoom.ts"
import { Room, Client, validate } from "colyseus";
import { z } from "zod";
import { thirdPartyMessages } from "./thirdPartyMessages";
import { MyRoomState } from "./MyRoomState";

type MyClient = Client<{ userData: { name: string } }>;

export class MyRoom extends Room<{ client: MyClient }> {
  state = new MyRoomState();

  messages = {
    // Spread reusable handlers from external modules
    ...thirdPartyMessages,

    // Define room-specific handlers with validation
    move: validate(
      z.object({
        x: z.number(),
        y: z.number(),
        z: z.number().optional(),
      }),
      (client, message) => {
        const player = this.state.players.get(client.sessionId)!;
        player.x = message.x;
        player.y = message.y;
      }
    ),

    // Simple handler defined inline
    notify_something: (client: MyClient, message: any) => {
      this.broadcast("notify", { sessionId: client.sessionId, message: "I'm a notification!" });
    },
  };
}
```

## Overriding Composed Handlers

When spreading multiple handler objects, handlers defined later will override earlier ones with the same name:

```typescript filename="MyRoom.ts"
messages = {
  ...thirdPartyMessages,  // Contains "chat" handler
  
  // This overrides the "chat" handler from thirdPartyMessages
  chat: validate(
    z.object({ text: z.string() }),
    (client, message) => {
      // Custom chat implementation
    }
  ),
};
```

## See Also

- [Room - Message Handling](https://docs.colyseus.io/room.md#message-handling) - Basic message handler syntax
- [Room - Message Input Validation](https://docs.colyseus.io/room.md#message-input-validation) - Using `validate()` with Zod schemas

---
Source: https://docs.colyseus.io/room/messages


# Room Plugins

Cross-cutting room behavior (AFK kicks, session limits, geo lookups) tends to get copy-pasted between room classes. A **Room Plugin** packages that behavior once, as a composable extension to a `Room`. Each plugin can contribute any subset of:

- **Message handlers**: merged into the room's `messages` map.
- **Lifecycle hooks**: `onCreate`, `onAuth`, `onJoin`, `onLeave`, `onDispose`, composed with the room's own hooks (with configurable before/after ordering).
- **Public methods**: callable from the room as `this.plugins.<key>.someMethod()`.

Each room gets its own plugin instances, and the framework wires `this.room` once the room is fully constructed. The merge itself is computed once per `Room` subclass and cached on the class, so there's no per-instance setup cost.

## Available plugins

| Plugin | What it does |
|--------|--------------|
| [IdleKickPlugin](https://docs.colyseus.io/room/plugins/idle-kick.md) | Auto-disconnects clients that haven't sent a message within a configurable timeout. Zero per-message overhead. |
| [GeoIPPlugin](https://docs.colyseus.io/room/plugins/geoip.md) | Resolves a client's country from their IP at auth time and exposes it as `client.geoip` before `onJoin` runs. |
| [WebRTCPlugin](https://docs.colyseus.io/room/plugins/webrtc.md) | WebRTC peer-to-peer signaling (peer list, SDP offer/answer, ICE candidate relay) for audio/video/data channels. |
| [UniqueSessionPlugin](https://docs.colyseus.io/room/plugins/unique-session.md) | Enforces a max number of concurrent sessions of this room type per user (default: one). |
| [TrackUserSessionsPlugin](https://docs.colyseus.io/room/plugins/track-user-sessions.md) | Maintains a per-user reverse index in Presence. Powers admin by-user inspection and session-revocation. |

All plugins above ship with the `colyseus` package, with no extra dependency to install. The exception is `GeoIPPlugin`, which lives in its own package ([`@colyseus/geoip`](https://docs.colyseus.io/room/plugins/geoip.md)) because it pulls in the MMDB reader and database files.

## Attaching plugins to a Room

Use `definePlugins` inside your `Room` subclass. The **array form** is recommended. Each plugin declares its own canonical key via `readonly pluginName = '...' as const`, and the framework turns the array into a typed record:

```ts filename="MyRoom.ts"
import { Room, definePlugins } from "colyseus";
import { IdleKickPlugin } from "colyseus/plugins/idle-kick";

export class MyRoom extends Room {
  plugins = definePlugins([
    new IdleKickPlugin({ timeoutMs: 60_000 }),
  ]);

  onCreate() {
    // your own setup, runs alongside the plugin hooks
    this.plugins.idleKick;  // ← typed, autocompletes
  }
}
```

The key (`idleKick` here) comes from the plugin's `pluginName` field, with no per-room renaming.

### Multiple instances of the same plugin

`definePlugins` also accepts a keyed record. Use it when you want to pick the key yourself per-room, or when you need two instances of the same plugin class with different keys:

```ts filename="MyRoom.ts"
plugins = definePlugins({
  adminChat:  new ChatPlugin({ channel: "admin" }),
  playerChat: new ChatPlugin({ channel: "public" }),
});
```

Both forms produce the same runtime shape (`Record<string, RoomPlugin>`). Prefer the array form; reach for the record form when you want to pick the keys yourself.

A plugin can also accept its `pluginName` as a constructor argument, which lets the array form host two instances too. Unless the plugin threads that name's literal type through a generic, though, `this.plugins.<key>` loses its typing. The record form is the simpler road.

## Writing your own plugin

Subclass `RoomPlugin` and override any subset of lifecycle hooks. `this.room` is wired automatically after the host room is fully constructed. Don't access it from the plugin's constructor.

```ts filename="ChatPlugin.ts"
import { RoomPlugin, type Client } from "@colyseus/core";

export class ChatPlugin extends RoomPlugin {
  readonly pluginName = "chat" as const;

  private history: string[] = [];
  private historyLimit: number;

  constructor(opts: { historyLimit: number }) {
    super();
    this.historyLimit = opts.historyLimit;
  }

  protected messages = {
    chat: (client: Client, msg: { text: string }) => {
      this.history.push(msg.text);
      if (this.history.length > this.historyLimit) { this.history.shift(); }
      this.room.broadcast("chat", { from: client.sessionId, text: msg.text });
    },
  };

  // Public: callable as `this.plugins.chat.getHistory()` from the room
  getHistory(): readonly string[] {
    return this.history;
  }
}
```

> **Warning:**
>
> **Always declare lifecycle hooks (`onCreate` / `onAuth` / `onJoin` / `onLeave` / `onDispose`), `messages`, and `order` as `protected`.** They're protected on the base `RoomPlugin` class. If you omit the modifier on a subclass override, TypeScript silently widens it to `public`, which leaks those framework slots into `this.plugins.<key>.<member>` autocomplete. The `pluginName` field stays `public` so type inference can read its literal.

Use it like any other plugin:

```ts filename="MyRoom.ts"
import { Room, definePlugins } from "colyseus";
import { ChatPlugin } from "./ChatPlugin";

export class MyRoom extends Room {
  plugins = definePlugins([
    new ChatPlugin({ historyLimit: 100 }),
  ]);

  onDispose() {
    console.log("final chat history:", this.plugins.chat.getHistory());
  }
}
```

## Declaring plugin dependencies

A plugin can declare other plugin classes it needs alongside it via a `static dependencies` field. The framework auto-instantiates any missing ones at room construction time. Your app code only mentions the plugin you actually care about:

```ts filename="UniqueSessionPlugin.ts"
import { RoomPlugin, type PluginDependencies } from "@colyseus/core";
import { TrackUserSessionsPlugin } from "colyseus/plugins/track-user-sessions";

export class UniqueSessionPlugin extends RoomPlugin {
  readonly pluginName = "uniqueSession" as const;

  // Pulls `TrackUserSessionsPlugin` in automatically: no need to
  // list it in the user's `definePlugins([...])`.
  static dependencies: PluginDependencies = [TrackUserSessionsPlugin];
}
```

Rules:

- **Zero-arg constructor.** Dependency classes must construct with no arguments. Plugins that need options can't be auto-included. Register them explicitly.
- **Transitive resolution.** Dep chains are walked recursively. Cycles throw at class-init time with the cycle path named.
- **Dedup by class.** If the user already registered the dependency themselves (`definePlugins([new TrackUserSessionsPlugin(), new UniqueSessionPlugin()])`), the auto-include is a no-op: their instance wins.
- **Hidden from `this.plugins`.** Auto-deps don't appear under a user-visible key in `this.plugins`. They run their lifecycle hooks normally; if you need to interact with one, register it explicitly.

## Lifecycle hook order

By default, plugins run **before** the room's hook for setup-style events and **after** for teardown-style events. Each plugin can override this per-hook via the `order` field.

| Hook        | Default order vs the room's own hook | Rationale                                  |
|-------------|--------------------------------------|--------------------------------------------|
| `onCreate`  | Plugins run **before**               | Plugins set up guards/state the room reads |
| `onAuth`    | Plugins run **before**               | Plugins vet/decorate the client before the room's auth logic |
| `onJoin`    | Plugins run **before**               | Plugins can validate/decorate the client   |
| `onLeave`   | Plugins run **after**                | Capture the final state the room left      |
| `onDispose` | Plugins run **after**                | Run cleanup after the room's teardown      |

A plugin's `onAuth(client, options, context)` differs from the room's in one way: it returns nothing. It exists to vet or decorate the client: throw to reject the join, or attach data for downstream hooks. That's how [`GeoIPPlugin`](https://docs.colyseus.io/room/plugins/geoip.md) makes `client.geoip` available before your own `onAuth` runs; producing `client.auth` data remains the room's job.

To override the default for a specific hook:

```ts filename="MyPlugin.ts"
import { RoomPlugin } from "@colyseus/core";

export class MyPlugin extends RoomPlugin {
  readonly pluginName = "my" as const;

  protected order = {
    onJoin: "after",   // run AFTER the room's onJoin instead of before
  } as const;

  protected onJoin(client) {
    // ...
  }
}
```

## Message handler rules

- A plugin's `messages` are merged into the room's `messages`.
- If the **room** defines the same message key as a plugin, the room wins: the plugin's handler is silently dropped. This behavior is the documented escape hatch for _"use the plugin but override one message"_.
- If **two plugins** define the same key, the framework throws at class-init time naming both plugin keys. Resolve by giving one a different key or by overriding on the room's own `messages`.

At runtime the plugin's message handlers are fully merged into the room. For **client-side typing**, though, a `protected messages` map (the visibility this page recommends) does not surface through the SDK's `room.send(...)` / `room.onMessage(...)` type extraction. That's because TypeScript's structural checks skip protected members. If typed client access to a plugin's messages matters more than autocomplete hygiene, declare that plugin's `messages` as `public`.

## Typed access to room state

Plugins that need typed access to the host room's state expose a generic parameter on their class:

```ts filename="LeaderboardsPlugin.ts"
import { RoomPlugin, type Client, type Room } from "@colyseus/core";

export class LeaderboardsPlugin<R extends Room = Room> extends RoomPlugin<R> {
  readonly pluginName = "leaderboards" as const;

  protected onLeave(client: Client) {
    // `this.room` is typed as `R`, the room shape the user passed.
    this.room.state.players.delete(client.sessionId);
  }
}
```

The generic argument must come from **outside** the room class. Declare a type alias for the room shape next to it:

```ts filename="MyRoom.ts"
type MyRoomShape = Room<{ state: MyState }>;

export class MyRoom extends Room<{ state: MyState }> {
  plugins = definePlugins([
    new LeaderboardsPlugin<MyRoomShape>(),
  ]);
}
```

> **Warning:**
>
> **Prefer a type alias over `<this>` inside the `plugins =` initializer.** `new LeaderboardsPlugin<this>()` makes the field's type depend on the class being defined. That dependency has historically tripped TypeScript's cycle detection (`'plugins' implicitly has type 'any'`) on some compiler versions. The type-alias pattern above sidesteps the question entirely (the alias resolves before the class does) and is the canonical way to thread the room shape.

## Testing a plugin in isolation

Use `attachToTestRoom` to inject a stub room and exercise the plugin's hooks without spinning up a full Colyseus server. Because lifecycle hooks and `messages` are `protected`, reach into them via bracket-notation (TS skips visibility checks on indexed access):

```ts filename="MyPlugin.test.ts"
import assert from "assert";
import { attachToTestRoom } from "@colyseus/core";
import { ChatPlugin } from "./ChatPlugin";

const plugin = new ChatPlugin({ historyLimit: 5 });
const broadcasts: any[] = [];
attachToTestRoom(plugin, {
  broadcast: (type, payload) => broadcasts.push([type, payload]),
});

// Bracket access: bypasses TS's `protected` visibility check.
plugin["messages"]!["chat"]({ sessionId: "alice" } as any, { text: "hi" });

assert.deepEqual(broadcasts, [["chat", { from: "alice", text: "hi" }]]);
assert.deepEqual(plugin.getHistory(), ["hi"]);
```

The second argument to `attachToTestRoom` is shallow-merged onto the stub, so tests only declare the room properties they actually exercise.

---
Source: https://docs.colyseus.io/room/plugins


# GeoIPPlugin

Looks up the client's IP at auth time and exposes the resolved country
as `client.geoip` before `onJoin` runs. Useful for region-locked
matchmaking, GDPR-aware routing, locale defaults, geo-blocking, and
country-of-origin analytics.

**Footprint:** one MMDB file loaded into memory per process (~6 MB for
MaxMind GeoLite2-Country, ~8 MB for DB-IP Lite). Lookups are
synchronous and complete in microseconds, with no async cost on the
join path. Across N rooms in one process, a single reader is shared via a
module-level cache.

## Installation

`@colyseus/geoip` ships as a separate package because it pulls in the
[`maxmind`](https://github.com/runk/node-maxmind) library and (optional)
database files:

```sh npm2yarn
npm install @colyseus/geoip
```

```ts filename="MyRoom.ts"
import { Room, definePlugins } from "colyseus";
import { GeoIPPlugin } from "@colyseus/geoip";

export class MyRoom extends Room {
  plugins = definePlugins([
    new GeoIPPlugin({ dbPath: "./GeoLite2-Country.mmdb" }),
  ]);

  async onJoin(client) {
    console.log(client.geoip);
    // { isoCode: "BR", name: "Brazil", continent: "SA", isInEU: false }
  }
}
```

`client.geoip` is typed via TypeScript module augmentation on
`@colyseus/core`'s `Client` interface. No manual type imports are needed.

> **Note:**
>
> `client.geoip` is `undefined` for unresolvable IPs: loopback,
> RFC1918 private ranges, IPv6 link-local, or simply absent from your
> database. Lookup failures never block the join.

## `GeoIPData`

```ts
interface GeoIPData {
  /** ISO 3166-1 alpha-2 country code, e.g. "BR", "US". */
  isoCode: string;
  /** Human-readable English name, e.g. "Brazil". */
  name: string;
  /** ISO 3166-1 continent code: AF, AN, AS, EU, NA, OC, SA. */
  continent?: string;
  /** EU member flag: present in MaxMind country records, useful for GDPR routing. */
  isInEU?: boolean;
}
```

## Database delivery modes

The plugin reads any [MMDB](https://maxmind.github.io/MaxMind-DB/) file,
the binary format shared by MaxMind GeoLite2 and DB-IP Lite. Three ways
to point it at one:

### 1. `dbPath`: bring your own file

```ts
new GeoIPPlugin({ dbPath: "/var/lib/geoip/GeoLite2-Country.mmdb" })
```

Use this with MaxMind's [`geoipupdate`](https://github.com/maxmind/geoipupdate)
cron, a custom build step that fetches DB-IP, or any other workflow you
already have.

| Option   | Type     | Default    | Description                       |
|----------|----------|------------|-----------------------------------|
| `dbPath` | `string` | _required_ | Absolute path to the MMDB file.   |

### 2. `accountId` + `licenseKey`: auto-fetch from MaxMind

```ts
new GeoIPPlugin({
  accountId: process.env.MAXMIND_ACCOUNT_ID,
  licenseKey: process.env.MAXMIND_LICENSE_KEY,
})
```

Downloads `GeoLite2-Country.mmdb` under your MaxMind credentials on the
first boot, caches to disk, and refreshes weekly. Sign up free at
[maxmind.com/en/geolite2/signup](https://www.maxmind.com/en/geolite2/signup)
to get credentials.

| Option              | Type     | Default                              | Description                                                                                |
|---------------------|----------|--------------------------------------|--------------------------------------------------------------------------------------------|
| `accountId`         | `string` | _required_                           | MaxMind account ID.                                                                        |
| `licenseKey`        | `string` | _required_                           | MaxMind license key (issued alongside the account).                                        |
| `cacheDir`          | `string` | `os.tmpdir() + '/colyseus-geoip'`    | Directory where the fetched `.mmdb` is cached on disk.                                     |
| `edition`           | `string` | `'GeoLite2-Country'`                 | Which MaxMind edition to fetch. Stick to a Country edition unless you've extended the reader. |
| `refreshIntervalMs` | `number` | `7 * 24 * 60 * 60 * 1000` (weekly)   | How often to re-fetch the database in the background.                                      |

> **Note:**
>
> Cross-process safety: when multiple processes share the same
> `cacheDir`, each writes to PID-scoped temp paths and rechecks before
> the atomic rename. Concurrent peers never overwrite each other's
> intermediate writes. For larger fleets, point all replicas at a shared
> volume populated by a single `geoipupdate` sidecar.

### 3. DB-IP Lite: no configuration

```ts
new GeoIPPlugin()
```

Downloads DB-IP's Lite Country database from db-ip.com on the first
boot (no account, no credentials) and caches it to disk. DB-IP publishes
a new snapshot on the 1st of each month; the plugin checks daily and
picks it up when it lands, falling back to last month's until it does.

| Option              | Type     | Default                              | Description                                                        |
|---------------------|----------|--------------------------------------|--------------------------------------------------------------------|
| `cacheDir`          | `string` | `os.tmpdir() + '/colyseus-geoip'`    | Directory where the downloaded `.mmdb` is cached on disk.          |
| `refreshIntervalMs` | `number` | `24 * 60 * 60 * 1000` (daily)        | How often to check for a new monthly snapshot. A check that finds nothing new makes no request. |

> **Note:**
>
> The database is fetched rather than shipped inside `@colyseus/geoip`:
> ~4 MB over the wire, 8 MB on disk, and only for the people who use
> this mode. It needs outbound network access on the first boot: in an
> air-gapped deployment, use mode 1 with a file you place yourself.

## Examples

### Region-locked matchmaking

```ts filename="EuropeRoom.ts"
import { Room, definePlugins, ServerError } from "colyseus";
import { GeoIPPlugin } from "@colyseus/geoip";

export class EuropeRoom extends Room {
  plugins = definePlugins([
    new GeoIPPlugin({ dbPath: "./GeoLite2-Country.mmdb" }),
  ]);

  async onAuth(client, options, context) {
    if (client.geoip?.continent !== "EU") {
      throw new ServerError(403, "EU-only room");
    }
    return true;
  }
}
```

> **Note:**
>
> `client.geoip` is populated by the plugin's `onAuth` hook, which
> runs *before* the room's own `onAuth`. You can rely on it being set
> by the time your auth logic runs.

### Locale defaults at join

```ts filename="LobbyRoom.ts"
async onJoin(client) {
  const defaultLocale = pickLocale(client.geoip?.isoCode);
  client.send("locale", defaultLocale);
}
```

### GDPR-aware analytics routing

```ts filename="GameRoom.ts"
async onJoin(client) {
  if (client.geoip?.isInEU) {
    analytics.useEUPipeline(client.sessionId);
  } else {
    analytics.useGlobalPipeline(client.sessionId);
  }
}
```

### Manual lookup from room code

The plugin exposes its reader as `this.plugins.geoip.lookup(ip)`,
useful when you need a geo result outside the auth path. Typical cases
include re-resolving on reconnect, annotating analytics events, and
anti-fraud checks against an unrelated IP:

```ts filename="GameRoom.ts"
async onReconnect(client) {
  // If you tracked the client's current IP separately, re-resolve it
  // here. `client.geoip` itself is not refreshed on reconnect.
  const ip = this.state.players.get(client.sessionId)?.lastIp;
  const freshGeo = ip && this.plugins.geoip.lookup(ip);
  if (freshGeo && freshGeo.isoCode !== client.geoip?.isoCode) {
    console.warn("country changed during reconnect", {
      sessionId: client.sessionId,
      from: client.geoip?.isoCode,
      to: freshGeo.isoCode,
    });
  }
}
```

`lookup()` returns `undefined` for unresolvable, malformed, or
not-in-database IPs, the same semantics as the `client.geoip` field. It
never throws.

## Licensing and attribution

This plugin reads two independently-licensed databases. **What you owe
depends on which mode you use.**

### MaxMind GeoLite2 (modes 1 & 2)

GeoLite2 data is provided under the
[GeoLite2 EULA](https://www.maxmind.com/en/geolite2/eula). Key terms:

- Free for use under your MaxMind account, including commercial use.
- **Cannot be redistributed**: each user must download under their
  own credentials. The plugin does **not** bundle MaxMind data.
- Cannot be used for FCRA-regulated decisions (credit, insurance,
  employment, government benefits).
- Attribution required if you expose the data: *"This product includes
  GeoLite2 data created by MaxMind, available from
  [maxmind.com](https://www.maxmind.com)."*

### DB-IP Lite (mode 3)

DB-IP's Lite databases are licensed under
[Creative Commons Attribution 4.0](https://creativecommons.org/licenses/by/4.0/).
`@colyseus/geoip` does **not** redistribute them: mode 3 downloads the
file from db-ip.com onto your machine, so the attribution obligation is
yours as the operator.

DB-IP asks that web applications displaying results from the database
link back to db-ip.com. If your game surfaces country information to
players, use their suggested credit:

```html
<a href="https://db-ip.com">IP Geolocation by DB-IP</a>
```

## Privacy

The plugin derives country from the client's IP. The IP is already
visible to your server. The resolved country is the same class of
personal data and should be treated as such under GDPR/CCPA/etc. If you
persist `client.geoip` beyond the session, disclose it in your privacy
policy.

## Caveats

- **`x-forwarded-for` chains:** the plugin uses the left-most entry on
  the assumption your reverse proxy populates that position with the
  originating client. If your proxy reverses or appends entries
  differently, your geo data will be wrong. Verify the chain shape
  before trusting `client.geoip` for production routing.
- **Reconnections:** `client.geoip` is set during the initial join's
  `onAuth`. A reconnecting client whose IP has changed in the meantime
  will still carry the original geo data through the reconnect path. If
  you need fresh-on-reconnect semantics, re-resolve manually with the
  public lookup method (see [Manual lookup from room code](#manual-lookup-from-room-code)).
- **Country granularity only:** the plugin's reader maps a
  small subset of MMDB fields. City, ASN, accuracy radius, and other
  richer GeoIP2-City fields are intentionally not exposed. Point the
  reader at a city DB and extend `MMDBReader` if you need them.

## See Also

- [Room Plugins](https://docs.colyseus.io/room/plugins.md): overview of the plugin system
- [`onAuth`](https://docs.colyseus.io/auth/room.md): pre-join hook the plugin attaches to

---
Source: https://docs.colyseus.io/room/plugins/geoip


# IdleKickPlugin

Auto-disconnects clients that haven't sent a message in `timeoutMs`. Useful for kicking AFK players from competitive rooms, freeing seats in matchmaking lobbies, or shedding zombie connections that the WebSocket layer still considers alive.

**Footprint:** one `clock.setInterval` per room, **zero** per-message work, **zero** per-client state. Activity is read from `client._lastMessageTime`, which the room stamps on every inbound frame.

## Installation

The plugin ships with the `colyseus` package: no extra dependency to install.

```ts filename="MyRoom.ts"
import { Room, definePlugins } from "colyseus";
import { IdleKickPlugin } from "colyseus/plugins/idle-kick";

export class MyRoom extends Room {
  plugins = definePlugins([
    new IdleKickPlugin({ timeoutMs: 60_000 }),
  ]);
}
```

## Options

| Option           | Type                                       | Default                          | Description                                                                                  |
|------------------|--------------------------------------------|----------------------------------|----------------------------------------------------------------------------------------------|
| `timeoutMs`      | `number`                                   | _required_                       | Milliseconds of inactivity after which a client is kicked.                                   |
| `scanIntervalMs` | `number`                                   | `min(timeoutMs / 4, 5000)`       | Milliseconds between scans. Smaller values kick sooner past the deadline.                    |
| `closeCode`      | `number`                                   | `1000`                           | WebSocket close code sent to the kicked client.                                              |
| `reason`         | `string`                                   | `'kicked'`                       | WebSocket close reason forwarded to the SDK's `onLeave`.                                     |
| `isExempt`       | `(client: Client) => boolean`              | —                                | Optional predicate to exempt a client (e.g., admins, spectators). Return `true` to keep the client immune. |
| `onKick`         | `(client: Client, idleMs: number) => void` | —                                | Called just before a client is kicked. Use to log, broadcast a notice, or persist analytics. |

## Handling the kick on the client

By default the plugin closes with WS code `1000` ("normal closure") and reason `'kicked'`. The SDK treats `1000` as a final leave (no auto-reconnect attempt) and forwards the reason string to `room.onLeave`:

```ts filename="client.ts"
room.onLeave((code, reason) => {
  if (code === 1000 && reason === "kicked") {
    showAfkScreen();
  }
});
```

## Examples

### Exempt admins

```ts filename="MyRoom.ts"
plugins = definePlugins([
  new IdleKickPlugin({
    timeoutMs: 30_000,
    isExempt: (client) => client.auth?.role === "admin",
  }),
]);
```

### Broadcast a notice before kicking

```ts filename="MyRoom.ts"
plugins = definePlugins([
  new IdleKickPlugin({
    timeoutMs: 60_000,
    onKick: (client, idleMs) => {
      this.broadcast("player-afk", {
        sessionId: client.sessionId,
        idleMs,
      });
    },
  }),
]);
```

> **Note:**
>
> The arrow function above works because class-field initializers bind `this` lexically: inside the arrow, `this` is the **room**. A plain `function () {}` callback would instead get the plugin instance as `this`, and `this.broadcast` would fail. Stick to arrows here.

### Custom close code

If you'd rather signal a domain-specific reason (e.g., to differentiate from a generic 1000 disconnect), use a custom code in the range `4011`–`4999`. Colyseus reserves `4000`–`4010`. `4010` in particular triggers the SDK's auto-reconnect, the opposite of a kick:

```ts filename="MyRoom.ts"
plugins = definePlugins([
  new IdleKickPlugin({
    timeoutMs: 60_000,
    closeCode: 4040,
    reason: "afk",
  }),
]);
```

## Caveats

- **Any inbound frame refreshes activity**: including SDK keepalive PINGs. This behavior is by design: an idle client whose socket is still healthy is preferable to a zombie connection that gets force-closed. If you need stricter "user-payload-only" semantics, manage your own timestamps from your message handlers.
- **Kicks land on the scan tick**, not on the deadline: a client is disconnected up to `scanIntervalMs` after it goes idle.

## See Also

- [Room Plugins](https://docs.colyseus.io/room/plugins.md): overview of the plugin system
- [Reconnection Handling](https://docs.colyseus.io/room/reconnection.md): `onDrop` / `allowReconnection` flow for unintentional disconnects

---
Source: https://docs.colyseus.io/room/plugins/idle-kick


# TrackUserSessionsPlugin

Maintains a **per-user reverse index** in Presence, a hash keyed by user id whose entries are the user's currently-active `{ roomId, roomName, joinedAt }` sessions. This index powers any tooling that needs to answer "what rooms is user X in right now?":

- The admin panel's **by-user inspector** (live sessions tab).
- The admin's **Ban** / **Revoke sessions** workflow (close all of a user's open WS connections).
- The [`UniqueSessionPlugin`](https://docs.colyseus.io/room/plugins/unique-session.md)'s duplicate-session check.

## Installation

The plugin ships with the `colyseus` package:

```ts filename="GameRoom.ts"
import { Room, definePlugins } from "colyseus";
import { TrackUserSessionsPlugin } from "colyseus/plugins/track-user-sessions";

export class GameRoom extends Room {
  plugins = definePlugins([
    new TrackUserSessionsPlugin(),
  ]);
}
```

You'll want to install this plugin directly when:

- You're running [`@colyseus/admin`](https://docs.colyseus.io/admin.md) and want the **Users → Active rooms** tab + the **Ban** / **Revoke sessions** workflows to surface what room a user is currently in. Without this plugin, those tabs stay empty.
- You're building tooling that asks "which rooms is user X in right now?" via the Presence reverse index.

The plugin is also **auto-included** by every plugin that reads the index (currently [`UniqueSessionPlugin`](https://docs.colyseus.io/room/plugins/unique-session.md)) via `static dependencies`. If your room already uses one of those, the tracker is wired in for free and you don't need to register it again.

## How it works

- **`onJoin`** (after the room's own `onJoin`): writes `{ roomId, roomName, joinedAt }` to the user's hash at `userRoomsKey(userId)`. Skips anonymous clients (no resolvable user id).
- **`onLeave`**: removes the entry.
- **`onDispose`**: sweeps any straggler entries that point at this room.

Identity is resolved via `client.userId ?? client.auth?.id`. The standard `@colyseus/auth` JWT shape supplies both for authenticated sessions and for anonymously-registered ones.

## Options

The plugin is **zero-config**.

## Reading the index

For your own tooling, the plugin exposes a static `listUserSessions(userId, options?)` that reads the cluster-wide reverse index:

```ts
import { TrackUserSessionsPlugin } from "colyseus/plugins/track-user-sessions";

const sessions = await TrackUserSessionsPlugin.listUserSessions("user-123");
// [
//   { sessionId: "s-abc", roomId: "r-aaa", roomName: "battle", joinedAt: 1716300000000 },
//   { sessionId: "s-def", roomId: "r-bbb", roomName: "lobby",  joinedAt: 1716300010000 },
// ]
```

Returned entries have the `UserSessionInfo` shape:

| Field        | Type        | Notes                                                                                          |
|--------------|-------------|------------------------------------------------------------------------------------------------|
| `sessionId`  | `string`    | The client session id from when the user joined that room.                                     |
| `roomId`     | `string`    | The id of the room the user is in.                                                             |
| `roomName`   | `string`    | The room definition name (matchmaking name).                                                   |
| `joinedAt`   | `number`    | Unix timestamp (ms) when the join was recorded.                                                |
| `processId`  | `string?`   | Process hosting the room, populated only with `reconcile: true` (see below).                  |

### Options

| Option         | Type      | Default  | Description                                                                                                                                                                              |
|----------------|-----------|----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `reconcile`    | `boolean` | `false`  | Cross-check each entry against the matchmaker and drop entries whose room is no longer live. When `true`, surviving entries also carry `processId` from the live room record.            |
| `removeStale`  | `boolean` | `false`  | Fire-and-forget `hdel` the dropped entries (corrupt JSON + entries dropped by `reconcile`) so the index self-heals on read. No-op when `reconcile` is `false`.                            |

```ts
// Display surface: drop dead-room entries, sweep them from Presence, get processId.
const live = await TrackUserSessionsPlugin.listUserSessions(userId, {
  reconcile: true,
  removeStale: true,
});

// Imperative path (kick everything): raw read; dead roomIds just fail the kick harmlessly.
const all = await TrackUserSessionsPlugin.listUserSessions(userId);
```

The raw read (default) is one wire op (`HGETALL` on the user's hash). With `reconcile: true`, the cost is bounded at **two** wire ops regardless of cluster size or the user's session count. The matchmaker lookup uses a single batch call (`matchMaker.findRoomsByIds`), not a cluster scan.

## Caveats

- **Anonymous clients are skipped.** No stable identity, nothing to index.
- **Process crashes can leave stragglers.** The index may briefly contain entries for rooms that no longer exist. Reads that pass `reconcile: true` drop them from the response; `removeStale: true` additionally `hdel`s them from Presence so the index self-heals.
- **Storage cost is one Presence write per join + one per leave per tracked user.** Negligible for most games. If you have a high-volume relay room where every microsecond counts, just don't include this plugin. The features that depend on it stay disabled for that room type.

---
Source: https://docs.colyseus.io/room/plugins/track-user-sessions


# UniqueSessionPlugin

Enforces a max number of **concurrent sessions of this room type per user**. Default `max: 1` (strict singleton). A second join from the same user while the first is still active is either **rejected** or **replaces** the older session, depending on configuration.

Typical uses:

- Prevent a player from opening two tabs of the same game mode.
- Block re-queueing while an old matchmaking session is still tracked.
- Refresh-style UX where opening a new tab kicks the older one out.

## Installation

The plugin ships with the `colyseus` package:

```ts filename="GameRoom.ts"
import { Room, definePlugins } from "colyseus";
import { UniqueSessionPlugin } from "colyseus/plugins/unique-session";

export class GameRoom extends Room {
  plugins = definePlugins([
    new UniqueSessionPlugin({ max: 1 }),
  ]);
}
```

> **Note:**
>
> **Auto-includes `TrackUserSessionsPlugin`.** The plugin reads the per-user reverse index that `TrackUserSessionsPlugin` maintains in Presence. You don't have to register the tracker yourself: `static dependencies` pulls it in.

## How it works

When a client joins, the plugin:

1. Resolves the user's stable id (default: `client.auth.id`, then `client.auth.userId`).
2. Reads the per-user reverse index from Presence to see what other rooms-of-this-type they're in.
3. Reconciles entries against live rooms (drops stragglers from crashed processes; cross-checks same-room entries against `this.room.clients` so a fast-disconnect ghost doesn't block reconnects).
4. If the active count would exceed `max`, either rejects the join or kicks the oldest existing session.

Anonymous clients (no resolvable userId) are **never** rejected, because there's no stable identity to enforce against.

## Performance

Per-join cost is bounded at **two backend round trips, independent of cluster size**:

1. `HGETALL` the user's reverse-index hash (always).
2. One batch room lookup (`matchMaker.findRoomsByIds`) for any cross-room candidates, skipped entirely when the user has none. Entries pointing at *this* room are resolved against the room's local client list, with no backend call.

So a typical first-join (no prior entries) is **one** wire op. A duplicate check against an existing same-room session is also **one** (the verification is local). Cross-room reconciliation adds **one** more batch call. The plugin's cost scales with the user's own session count (`K`), not the cluster's total room count (`N`). The plugin is safe to enable on large multi-process deployments.

## Options

| Option           | Type                                            | Default              | Description                                                                                                                                                                       |
|------------------|-------------------------------------------------|----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `max`            | `number`                                        | `1`                  | Max concurrent sessions of this room type per user.                                                                                                                               |
| `onDuplicate`    | `'reject' \| 'replace'`                         | `'reject'`           | Behavior when the limit is exceeded. `'replace'` kicks the **oldest** existing session(s) so the new join proceeds, useful for refresh-style UX.                                  |
| `rejectCode`     | `number`                                        | `4400`               | `ServerError` code sent to the client when `onDuplicate: 'reject'`. The SDK surfaces it as `MatchMakeError.code`.                                                                  |
| `rejectMessage`  | `string`                                        | `'already_in_room'`  | `ServerError` message sent to the client. The SDK exposes it as `e.message`.                                                                                                       |
| `conflictsWith`  | `(existing, currentRoom) => boolean`            | —                    | Per-existing-session filter that runs after the plugin's same-`roomName` matching + stale-entry reconcile. Return `true` to count the existing session as a conflict, `false` to skip it. See [`conflictsWith` in detail](#scope-by-conflictswith) below. |
| `resolveUserId`  | `(client) => string \| undefined`               | reads `auth.id`/`auth.userId` | Custom identity extractor. Override for non-standard auth shapes (e.g. raw OIDC's `auth.profile.sub`).                                                                            |

## Handling the rejection on the client

The plugin throws a `ServerError(4400, "already_in_room")`. On the client:

```ts filename="client.ts"
try {
  await client.joinOrCreate("game");
} catch (err) {
  if (err.code === 4400) {
    showAlreadyInGameDialog();
  }
}
```

For custom codes, configure `rejectCode` / `rejectMessage`.

## Examples

### Allow up to two concurrent tabs

```ts filename="GameRoom.ts"
plugins = definePlugins([
  new UniqueSessionPlugin({ max: 2 }),
]);
```

A third join from the same user is rejected.

### Replace the older session on duplicate

```ts filename="GameRoom.ts"
plugins = definePlugins([
  new UniqueSessionPlugin({
    max: 1,
    onDuplicate: "replace",
  }),
]);
```

The oldest existing session is kicked with WS code `1000` and reason `'replaced'`. The new join proceeds.

### Scope by `conflictsWith`

The `conflictsWith` callback is your hook to override "what counts as a duplicate." The plugin has already filtered out entries with a different `roomName` and reconciled stale entries. Whatever reaches the predicate is a real, live session of the same room type. Return `true` to count it against `max`, `false` to ignore.

The predicate receives:

- `existing`: the candidate session being evaluated:
  - `sessionId: string`: the existing session's id.
  - `joinedAt: number`: Unix ms timestamp from when the existing session was recorded.
  - `room?: IRoomCache`: matchmaker's cached record for the existing session's room (`metadata`, `clients`, `maxClients`, `locked`, `processId`, etc.). **Undefined** when the existing session is in the *same `Room` instance* as the joining client. Use `currentRoom` for that case. No extra round trip is made: this is the same lookup the plugin already runs for cross-room candidates.
- `currentRoom`: the live `Room` instance the join is targeting (same as `this.room` inside the plugin). Optional to declare; ignore it if you don't need it.

#### Scope by game mode metadata

```ts filename="GameRoom.ts"
plugins = definePlugins([
  new UniqueSessionPlugin({
    max: 1,
    // Only count sessions in rooms of the same game mode. Casual
    // and ranked rooms share a roomName but should run side-by-side.
    conflictsWith: (existing, currentRoom) => {
      const otherMode = existing.room?.metadata?.mode ?? currentRoom.metadata?.mode;
      return otherMode === currentRoom.metadata?.mode;
    },
  }),
]);
```

#### Per-process exemption (multi-region)

```ts filename="GameRoom.ts"
import { matchMaker } from "@colyseus/core";

plugins = definePlugins([
  new UniqueSessionPlugin({
    max: 1,
    // Allow one session per Node process, useful if you run the
    // game in multiple regions and want a user to be able to play
    // in EU and US at the same time.
    // same-room conflicts have no `existing.room`: always same-process
    conflictsWith: (existing) =>
      !existing.room || existing.room.processId === matchMaker.processId,
  }),
]);
```

#### Don't count rooms that are already full

```ts filename="GameRoom.ts"
plugins = definePlugins([
  new UniqueSessionPlugin({
    max: 1,
    // If the other room is full, the user can't actually still be
    // playing meaningfully, so let them re-queue elsewhere.
    conflictsWith: (existing) =>
      !existing.room || existing.room.clients < existing.room.maxClients,
  }),
]);
```

### Custom auth shape

```ts filename="GameRoom.ts"
plugins = definePlugins([
  new UniqueSessionPlugin({
    resolveUserId: (client) => (client as any).auth?.profile?.sub,
  }),
]);
```

## Caveats

- **Race window.** Two near-simultaneous joins from the same user can both pass the check before either has written to the Presence index, so both succeed. Acceptable for the "no two tabs" UX. If your game needs strict serialization (e.g. competitive matchmaking that can't double-book), layer your own atomic reservation on top.
- **`TrackUserSessionsPlugin` is required.** Auto-included via `static dependencies`. If your app's `Room` somehow opts out of plugin tracking, the index stays empty and this plugin no-ops.
- **Stale entries are best-effort cleaned up.** Reconciliation drops entries pointing at rooms the matchmaker no longer knows. Same-room entries are cross-checked against `this.room.clients` so reconnects after a missed `onLeave` aren't false-rejected.

---
Source: https://docs.colyseus.io/room/plugins/unique-session


# WebRTCPlugin

Adds WebRTC peer-to-peer signaling to a room. Wires the four standard signaling messages (peer list + SDP offer/answer + ICE candidate relay) and broadcasts `peer-left` when a connected peer disconnects.

**This plugin is signaling only:** it handles the SDP/ICE exchange needed to establish WebRTC connections. The actual audio/video/data streams flow directly between peers. Colyseus state synchronization continues to work through the server as usual.

## Installation

The server-side plugin ships with the `colyseus` package: no extra install needed.

```ts filename="VideoRoom.ts"
import { Room, definePlugins } from "colyseus";
import { WebRTCPlugin } from "colyseus/plugins/webrtc";

export class VideoRoom extends Room {
  plugins = definePlugins([
    new WebRTCPlugin(),
  ]);
}
```

The client-side helper ships in a separate browser-only package:

```bash
npm install @colyseus/webrtc
```

> **Warning:**
>
> WebRTC SDP payloads can exceed the default `maxPayload` of 4KB. Increase it on your transport when adding the plugin:
>
> ```ts filename="server.ts"
> import { WebSocketTransport } from "@colyseus/ws-transport";
> 
> const server = defineServer({
>   transport: new WebSocketTransport({ maxPayload: 16 * 1024 }),
>   // ...
> });
> ```

## Signaling messages

The plugin contributes the following messages to your room. You can listen to them or send them yourself if you need to extend the signaling flow.

| Message               | Direction                  | Description                                                                                  |
|-----------------------|----------------------------|----------------------------------------------------------------------------------------------|
| `webrtc:join`         | client &rarr; server       | Client opts into the mesh. Server replies with the current peer list and broadcasts to others. |
| `webrtc:offer`        | client &rarr; server &rarr; client | Relay SDP offer to the target peer.                                                          |
| `webrtc:answer`       | client &rarr; server &rarr; client | Relay SDP answer to the target peer.                                                         |
| `webrtc:ice-candidate`| client &rarr; server &rarr; client | Relay ICE candidate to the target peer.                                                      |
| `webrtc:peers`        | server &rarr; client       | List of existing peer session IDs (sent on join).                                            |
| `webrtc:peer-joined`  | server &rarr; client       | A new peer has joined the mesh.                                                              |
| `webrtc:peer-left`    | server &rarr; client       | A peer has left the mesh. Only emitted for clients that opted in via `webrtc:join`.          |

The plugin tracks which clients have explicitly opted into the mesh. Spectators and other non-WebRTC clients in the same room therefore don't appear in peer events.

## Client-side usage

Use `WebRTCClient` from `@colyseus/webrtc/client` to consume the signaling and manage `RTCPeerConnection` instances.

> **Note:**
>
> The source is a single ~170-line file you can read or fork. See the [reference implementation on GitHub](https://github.com/colyseus/webrtc/blob/main/src/client.ts).

```ts filename="client.ts"
import { Client } from "@colyseus/sdk";
import { WebRTCClient } from "@colyseus/webrtc/client";

const client = new Client("ws://localhost:2567");
const room = await client.joinOrCreate("video");

const webrtc = new WebRTCClient(room);

webrtc.onLocalStream = (stream) => {
  // Attach to a <video> element for self-preview
  localVideo.srcObject = stream;
};

webrtc.onPeerConnected = (peerId, stream) => {
  // Attach remote stream to a <video> element
};

webrtc.onPeerDisconnected = (peerId) => {
  // Remove the peer's video element
};

// Request camera/mic and start signaling
await webrtc.join({ audio: true, video: true });

// Later, to stop and clean up:
webrtc.leave();
room.leave();
```

### `WebRTCClient` API

#### Constructor

```ts
new WebRTCClient(room, options?)
```

- **`room`**: A Colyseus `Room` instance (or any object exposing `send(type, message)` and `onMessage(type, callback)`).
- **`options.iceServers`**: Custom ICE servers. Defaults to Google's public STUN servers.

#### Methods

| Method                | Description                                                                                                                                            |
|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|
| `join(constraints?)`  | Request user media with the given [`MediaStreamConstraints`](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamConstraints) and start signaling. Defaults to `{ audio: true, video: true }`. |
| `leave()`             | Close all peer connections, stop local tracks, and unbind signaling listeners.                                                                         |

#### Callbacks

| Callback             | Signature                                          | Description                                              |
|----------------------|----------------------------------------------------|----------------------------------------------------------|
| `onLocalStream`      | `(stream: MediaStream) => void`                    | Fired after `getUserMedia` succeeds.                     |
| `onPeerConnected`    | `(peerId: string, stream: MediaStream) => void`    | Fired when a remote peer's media stream is received.     |
| `onPeerDisconnected` | `(peerId: string) => void`                         | Fired when a peer connection closes.                     |

#### Properties

| Property      | Type                              | Description                                       |
|---------------|-----------------------------------|---------------------------------------------------|
| `localStream` | `MediaStream \| null`             | The local media stream.                           |
| `peers`       | `Map<string, RTCPeerConnection>`  | Active peer connections keyed by session ID.      |
| `streams`     | `Map<string, MediaStream>`        | Remote media streams keyed by session ID.         |

## Combining with your own messages

The plugin's messages are merged into the room's `messages` map. You can define your own alongside without any conflict:

```ts filename="VideoRoom.ts"
import { Room, Client, definePlugins } from "colyseus";
import { WebRTCPlugin } from "colyseus/plugins/webrtc";

export class VideoRoom extends Room {
  plugins = definePlugins([
    new WebRTCPlugin(),
  ]);

  messages = {
    chat: (client: Client, message: string) => {
      this.broadcast("chat", `${client.sessionId}: ${message}`);
    },
  };
}
```

See [Room Plugins &rarr; Message handler rules](https://docs.colyseus.io/room/plugins.md#message-handler-rules) for the conflict resolution semantics.

## How it works

```
Client A                     Server                      Client B
   |                            |                            |
   |---- webrtc:join ---------->|                            |
   |<--- webrtc:peers (B) ------|                            |
   |                            |---- webrtc:peer-joined --->|
   |---- webrtc:offer (B) ----->|---- webrtc:offer (A) ----->|
   |<--- webrtc:answer (B) -----|<--- webrtc:answer (A) -----|
   |---- webrtc:ice-candidate ->|---- webrtc:ice-candidate ->|
   |                            |                            |
   |<======================= RTCPeerConnection =============>|
                          (direct, P2P)
```

Once signaling completes, audio/video/data flows directly between the browsers via `RTCPeerConnection`. It doesn't go through your Colyseus server.

## See Also

- [Room Plugins](https://docs.colyseus.io/room/plugins.md): overview of the plugin system
- [`@colyseus/webrtc` on GitHub](https://github.com/colyseus/webrtc): original standalone package and example app

---
Source: https://docs.colyseus.io/room/plugins/webrtc


# Reconnection

Colyseus supports two complementary reconnection flows. Both require the server to hold the client's seat via [`allowReconnection()`](#allowreconnectionclient-seconds):

- **[Automatic reconnection](#automatic-reconnection)**: the SDK detects the drop and retries with exponential backoff. The same `room` instance survives, so your listeners stay attached. Introduced in version 0.17.
- **[Manual reconnection](#manual-reconnection)**: the client rejoins later by calling `client.reconnect()` with a stored `reconnectionToken`. Use it when the app itself restarts (a page reload, an app switch on mobile) or after automatic retries give up. Available in all versions.

## Overview

When a client loses connection unexpectedly (e.g., network switch, temporary connectivity loss), the automatic flow works as follows:

1. **Client detects disconnection** → `onDrop()` is triggered on the client
2. **Server detects disconnection** → `onDrop()` is triggered on the server (if defined)
3. **Server allows reconnection** → Call `allowReconnection()` inside `onDrop()`
4. **Client attempts to reconnect** → Automatic retry with exponential backoff
5. **Reconnection succeeds** → `onReconnect()` is triggered on both client and server
6. **If reconnection fails/times out** → `onLeave()` is triggered on both sides

```mermaid
flowchart TD
    lost(["❌ Connection lost<br/>(any non-consented close)"])
    drop["<b>onDrop</b> fires on both sides<br/>client: show reconnecting UI<br/>server: allowReconnection(client, 30)"]
    retry{"SDK auto-retries with<br/>exponential backoff"}
    ok["<b>onReconnect</b> fires on both sides<br/>state reconciles, queued messages flush"]
    gone["<b>onLeave</b> fires on both sides<br/>client receives FAILED_TO_RECONNECT (4003)"]

    lost --> drop
    drop --> retry
    retry -->|"reconnected in time"| ok
    retry -->|"fails or times out"| gone

    classDef good stroke:#22c55e,stroke-width:2px
    classDef bad stroke:#ef4444,stroke-width:2px
    class ok good
    class gone bad
```

The automatic flow only covers drops the running client can recover from. A page reload or app restart destroys the client-side `room` object, so the SDK cannot retry by itself. In that case the client calls [`client.reconnect()`](#manual-reconnection) with a stored token instead. The server-side flow is identical.

---

## Server-Side

The backend handles both flows identically.

### `onDrop(client, code)`

Called when a client disconnects **without consent** (abnormal closure, network issues, etc.). This hook is where you should call `allowReconnection()` to allow the client to reconnect.

> **Note:**
>
> `onDrop()` is **optional**, but recommended for code clarity. You may implement the same functionality directly inside `onLeave()` by checking if the close code is `CloseCode.CONSENTED`. See [the alternative pattern](#alternative-handling-reconnection-in-onleave).

```typescript
import { Room, Client, CloseCode } from "colyseus";

class MyRoom extends Room {
  onDrop(client: Client, code: number) {
    // Allow the client to reconnect within 30 seconds
    this.allowReconnection(client, 30);

    // Optionally mark the player as disconnected in your state
    const player = this.state.players.get(client.sessionId);
    if (player) {
      player.connected = false;
    }
  }
}
```

**When `onDrop()` is called:** every non-consented disconnection. Abnormal closures (1006), browser/tab closed (1001), no close status (1005), dev-mode restarts (4010), server errors (4002), and custom close codes all qualify.

**When `onDrop()` is NOT called (goes directly to `onLeave()`):**
- `CloseCode.CONSENTED` (4000): Client called `room.leave()` with consent
- A reconnection already in progress was denied or failed

### `allowReconnection(client, seconds)`

Call this method inside `onDrop()` to hold the client's seat. The reservation covers both the SDK's automatic retries and a later manual `client.reconnect()`.

```typescript
// Allow reconnection for 30 seconds
this.allowReconnection(client, 30);

// Allow reconnection indefinitely (manual mode)
const reconnection = this.allowReconnection(client, "manual");

// Later, you can reject the reconnection manually
reconnection.reject();
```

**Returns:** A `Deferred<Client>` promise that resolves when the client reconnects or rejects if the timeout expires. Calling it without `await` is safe. The framework handles the timeout internally and routes the outcome to `onReconnect()` or `onLeave()`. Only `await` it inside a `try`/`catch`, as in [the `onLeave()` pattern below](#alternative-handling-reconnection-in-onleave).

**Choosing the window:** with a number of `seconds`, the seat expires by itself. With `"manual"`, the seat is held until your code calls `.reject()`. Manual mode suits players returning after a page reload or a long app switch. Pair it with your own give-up logic:

```typescript
onDrop(client: Client, code: number) {
  const reconnection = this.allowReconnection(client, "manual");
  const currentRound = this.state.currentRound;

  // In a real project, store `reconnection` on your Player instance and
  // perform this check from your game loop instead.
  client.userData.reconnectionInterval = this.clock.setInterval(() => {
    const missedRounds = this.state.currentRound - currentRound;
    if (missedRounds > 2) {
      reconnection.reject();
      client.userData.reconnectionInterval.clear();
    }
  }, 1000);
}

onReconnect(client: Client) {
  // clear the interval to avoid a dangling timer
  client.userData.reconnectionInterval?.clear();
  delete client.userData.reconnectionInterval;
}
```

### `onReconnect(client)`

Called when a client successfully reconnects after `allowReconnection()` held its seat, whether the SDK retried automatically or the client called `client.reconnect()`.

```typescript
class MyRoom extends Room {
  onReconnect(client: Client) {
    console.log(`Client ${client.sessionId} reconnected!`);

    // Restore the player's connected status
    const player = this.state.players.get(client.sessionId);
    if (player) {
      player.connected = true;
    }
  }
}
```

**Important:** The `client` object in `onReconnect()` has the same `sessionId` and preserves:
- `client.auth`: Authentication data
- `client.userData`: Custom user data
- `client.view`: View state (for filtered state)

The `client.reconnectionToken` will be different (new token generated for each connection).

### `onLeave(client, code)`

Called when a client **permanently** leaves the room. A permanent leave happens when:
- Client calls `room.leave()` with consent
- Reconnection times out or fails
- Server explicitly disconnects the client

```typescript
class MyRoom extends Room {
  onLeave(client: Client, code: number) {
    console.log(`Client ${client.sessionId} left with code ${code}`);

    // Clean up player data
    this.state.players.delete(client.sessionId);
  }
}
```

---

## Complete Server Example

```typescript
import { Room, Client, CloseCode } from "colyseus";
import { MyState, Player } from "./MyState";

class GameRoom extends Room<{ state: MyState }> {
  state = new MyState();

  onJoin(client: Client, options: any) {
    const player = new Player();
    player.connected = true;
    this.state.players.set(client.sessionId, player);
  }

  onDrop(client: Client, code: number) {
    console.log(`Client ${client.sessionId} dropped (code: ${code})`);

    // Allow reconnection for 30 seconds
    this.allowReconnection(client, 30);

    // Mark player as disconnected (but don't remove them)
    const player = this.state.players.get(client.sessionId);
    if (player) {
      player.connected = false;
    }
  }

  onReconnect(client: Client) {
    console.log(`Client ${client.sessionId} reconnected!`);

    // Restore player connection status
    const player = this.state.players.get(client.sessionId);
    if (player) {
      player.connected = true;
    }
  }

  onLeave(client: Client, code: number) {
    console.log(`Client ${client.sessionId} left permanently (code: ${code})`);

    // Now it's safe to remove the player
    this.state.players.delete(client.sessionId);
  }
}
```

### Alternative: Handling Reconnection in `onLeave()`

Instead of using `onDrop()`, you can handle reconnection directly inside `onLeave()` by checking the close code. This approach consolidates all disconnection logic in a single method:

```typescript
class MyRoom extends Room {
  async onLeave(client: Client, code: CloseCode) {
    if (code !== CloseCode.CONSENTED) {
      try {
        // Wait for reconnection
        await this.allowReconnection(client, 30);
        console.log("Client reconnected!");
        return; // Don't clean up, client is back
      } catch (e) {
        // Reconnection failed or timed out
      }
    }

    // Clean up player
    this.state.players.delete(client.sessionId);
  }
}
```

Using separate `onDrop()` and `onReconnect()` methods is recommended for cleaner code separation, but both approaches are fully supported.

---

## Client-Side

### Automatic Reconnection

The SDK detects the drop, retries with exponential backoff, and fires three events. This snippet is the whole client-side integration:

```typescript
import { Client, CloseCode } from "@colyseus/sdk";

const client = new Client("http://localhost:2567");
const room = await client.joinOrCreate("game_room");

room.onDrop((code, reason) => {
  // connection lost: the SDK is already retrying
  showReconnectingUI();
});

room.onReconnect(() => {
  hideReconnectingUI();
});

room.onLeave((code, reason) => {
  if (code === CloseCode.FAILED_TO_RECONNECT) {
    showError("Failed to reconnect. Please try again.");
  }
  cleanupGame();
});
```

Everything tunable here (retry and backoff options, disabling auto-reconnection, message buffering while offline) is documented in **[Connection Lifecycle & Reconnection](https://docs.colyseus.io/sdk/connection.md#automatic-reconnection)**.

### Manual Reconnection

Automatic retries only help while the `room` object is still alive in memory. When the page reloads or the app restarts, resume the session with `client.reconnect(reconnectionToken)` instead:

- **Persist `room.reconnectionToken`** while connected. The token is refreshed on every successful connection, so store it after joining *and* after each `onReconnect()`.
- **`client.reconnect()` returns a new `Room` instance**: reattach all listeners to it; the old references are gone.
- **The seat must still be held**: the call succeeds only within the server's `allowReconnection()` window (or indefinitely in `"manual"` mode).

```typescript
import { Client, Room } from "@colyseus/sdk";

const client = new Client("http://localhost:2567");

async function joinOrRejoin(): Promise<Room> {
  const token = sessionStorage.getItem("reconnectionToken");

  if (token) {
    try {
      // Try to resume the previous session first
      return onRoomJoined(await client.reconnect(token));
    } catch (e) {
      // Seat expired or reconnection was rejected: start fresh
      sessionStorage.removeItem("reconnectionToken");
    }
  }

  return onRoomJoined(await client.joinOrCreate("game_room"));
}

function onRoomJoined(room: Room): Room {
  sessionStorage.setItem("reconnectionToken", room.reconnectionToken);

  room.onReconnect(() => {
    // the token is refreshed on every successful connection
    sessionStorage.setItem("reconnectionToken", room.reconnectionToken);
  });

  // ...attach your onMessage / state callbacks here...

  return room;
}
```

Manual reconnection is also the fallback after automatic retries give up: on `FAILED_TO_RECONNECT` (4003), offer the player a "Rejoin" button that calls `client.reconnect()` with the stored token.

> **Note:**
>
> Samples for the other SDK languages are in **[Connection Lifecycle & Reconnection → Manual Reconnection](https://docs.colyseus.io/sdk/connection.md#manual-reconnection)**.

---

## State After Reconnection

On a successful reconnection the server sends a **full state snapshot**. The SDK **reconciles** it into the state tree you already hold (it does not rebuild the tree from scratch):

- Entities that changed while you were offline are **updated in place**. Your references into the tree and any state callbacks you attached stay valid. There is nothing to re-subscribe.
- Entities **added** while you were offline arrive as ordinary additions: `onAdd` fires.
- Entities **deleted** (or hidden from your view) while you were offline are **pruned**: `onRemove` fires for each, exactly as if the removal had arrived live.

In other words, after `onReconnect()` the state is guaranteed to match the server again. Your existing callbacks and UI bindings observe the offline gap as a normal sequence of changes. Prediction controllers follow automatically too. The SDK resets the input handle on reconnect and observing reconcilers pick it up; see [Client Prediction](https://docs.colyseus.io/netcode/client-prediction.md).

> **Note:**
>
> After a **manual** `client.reconnect()`, there is no previous tree to reconcile into. The new `Room` instance receives the snapshot as its initial state, and your freshly attached callbacks fire from scratch.

---

## Close Codes Reference

| Code | Name | Description |
|------|------|-------------|
| 1000 | `NORMAL_CLOSURE` | Normal WebSocket closure |
| 1001 | `GOING_AWAY` | Browser/tab closing |
| 1005 | `NO_STATUS_RECEIVED` | No status in close frame |
| 1006 | `ABNORMAL_CLOSURE` | Connection closed unexpectedly |
| 4000 | `CONSENTED` | Client left with consent (`room.leave()`) |
| 4001 | `SERVER_SHUTDOWN` | Server graceful shutdown (production) |
| 4002 | `WITH_ERROR` | Closed due to an error |
| 4003 | `FAILED_TO_RECONNECT` | All reconnection attempts failed |
| 4010 | `MAY_TRY_RECONNECT` | Server shutdown in dev mode (allows reconnect) |

See the [full table of WebSocket close codes](https://docs.colyseus.io/room.md#table-of-websocket-close-codes) for the complete range breakdown.

---

## Best Practices

1. **Always call `allowReconnection()` in `onDrop()`** if you want to support reconnection
2. **Don't remove player data in `onDrop()`**: wait for `onLeave()` to clean up
3. **Mark players as "disconnected" in state** so other clients can show appropriate UI
4. **Set reasonable reconnection timeouts** based on your game type (e.g., 30s for fast-paced games, 5min for turn-based)
5. **Persist `room.reconnectionToken`** (e.g., in `sessionStorage`) after joining and after each reconnection, so a page reload can resume via `client.reconnect()`
6. **Handle `FAILED_TO_RECONNECT` on the client** to show appropriate error messages, and offer a manual "Rejoin"
7. **Buffer important actions**: messages sent during disconnection are [queued automatically](https://docs.colyseus.io/sdk/connection.md#automatic-reconnection)

---
Source: https://docs.colyseus.io/room/reconnection


# Relay Room

The built-in `RelayRoom` provides a lightweight relay for simple multiplayer use cases where you only need to track connected clients.

**Features:**
- Broadcasts client messages to everyone else.
- Minimal backend state (no authoritative validation).
- Ideal for quick prototypes or frontend-driven validation.

> **Note:**
>
> The source-code for `RelayRoom` is available [here](https://github.com/colyseus/colyseus/blob/master/packages/core/src/rooms/RelayRoom.ts). Consider implementing your own version with backend validations when needed.

## Server

```ts filename="server.ts"
import { defineServer, defineRoom, RelayRoom } from "colyseus";

//
// Expose your relayed room.
//
const server = defineServer({
  rooms: {
    your_relayed_room: defineRoom(RelayRoom, {
      maxClients: 4,
      allowReconnectionTime: 40 // seconds (values above 40 are clamped to 40)
    })
  }
})
```

## Client

See how to register callbacks for players joining, leaving, sending and receiving messages from the relayed room.

### Connecting into the room

```ts filename="client.ts"
import { Client } from "@colyseus/sdk";

const client = new Client("http://localhost:2567");

//
// Join the relayed room.
//
const relay = await client.joinOrCreate("your_relayed_room", {
  name: "This is my name!"
});
```

### Registering callbacks when players join and leave

```ts filename="client.ts"
import { Callbacks } from "@colyseus/sdk";

const callbacks = Callbacks.get(relay);

//
// Detect when a player joined the room.
//
callbacks.onAdd("players", (player, sessionId) => {
  if (relay.sessionId === sessionId) {
    console.log("It's me!", player.name);

  } else {
    console.log("It's an opponent", player.name, sessionId);
  }
})

//
// Detect when a player left the room.
//
callbacks.onRemove("players", (player, sessionId) => {
  console.log("Opponent left!", player, sessionId);
})

//
// Detect when the connectivity of a player has changed.
// (only relevant if you provided `allowReconnectionTime` in the backend)
//
callbacks.onAdd("players", (player, sessionId) => {
  callbacks.listen(player, "connected", (connected) => {
    if (connected) {
      console.log("Opponent has reconnected!", player, sessionId);

    } else {
      console.log("Opponent has disconnected!", player, sessionId);
    }
  });
})
```

### Sending and receiving messages

```ts filename="client.ts"
//
// By sending a message, all other clients will receive it under the same name.
// Messages are only sent to other connected clients, never the current one.
//
relay.send("fire", {
  x: 100,
  y: 200
});

//
// Register a callback for messages you're interested in from other clients.
//
relay.onMessage("fire", ([sessionId, message]) => {

  //
  // The `sessionId` from who sent the message
  //
  console.log(sessionId, "sent a message!");

  //
  // The actual message sent by the other client
  //
  console.log("fire at", message);
});
```

---
Source: https://docs.colyseus.io/room/relay


# Timing Events

For [timing events](https://www.w3.org/TR/2011/WD-html5-20110525/timers.html),
it's recommended to use the [`this.clock`](https://docs.colyseus.io/room.md#clock) methods,
from your `Room` instance.

> **Note:**
>
> All intervals and timeouts registered on [`this.clock`](https://docs.colyseus.io/room.md#clock) are cleared automatically when the `Room` is disposed.

> **Warning:**
>
> The built-in [`setTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout) and [`setInterval`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setInterval) methods are affected by CPU load. Under load they can fire much later than requested.

## Clock

The clock is provided as a useful mechanism to time events outside of a stateful simulation. An example use case could be: when a player collects an item you might `clock.setTimeout(...)` to create a new collectible. One advantage of `this.clock` is that you do not have to track room updates and deltas. You can instead time your events independently of the room state.

### Clock Methods

*Note: `time` parameters are in milliseconds*

#### `clock.setInterval(callback, time, ...args): Delayed`

The `setInterval()` method repeatedly calls a function or executes a code
snippet, with a fixed time delay between each call. It returns
[`Delayed`](#delayed) instance which identifies the interval, so you can
manipulate it later.

#### `clock.setTimeout(callback, time, ...args): Delayed`

The `setTimeout()` method sets a timer which executes a function or specified
piece of code once after the timer expires. It returns [`Delayed`](#delayed)
instance which identifies the interval, so you can manipulate it later.

**Example**

The example below shows a Room with `setInterval()`, `setTimeout`, and clearing a previously stored instance of type `Delayed`. The example also reads `currentTime` from the Room's clock instance.

After 1 second 'Time now ' + `this.clock.currentTime` is `console.log`'d, and then after 10 seconds we clear the interval via `this.delayedInterval.clear()`

```ts filename="MyRoom.ts"
// Import Delayed
import { Room, Client, Delayed } from "colyseus";

export class MyRoom extends Room {
    // For this example
    public delayedInterval!: Delayed;

    // When room is initialized
    onCreate(options: any) {
        // start the clock ticking
        this.clock.start();

        // Set an interval and store a reference to it
        // so that we may clear it later
        this.delayedInterval = this.clock.setInterval(() => {
            console.log("Time now " + this.clock.currentTime);
        }, 1000);

        // After 10 seconds clear the timeout;
        // this will *stop and destroy* the timeout completely
        this.clock.setTimeout(() => {
            this.delayedInterval.clear();
        }, 10000);
    }
}
```

#### `clock.clear()`

Clear all intervals and timeouts registered with `clock.setInterval()` and `clock.setTimeout()`.

#### `clock.start()`

Start counting time.

#### `clock.stop()`

Stop counting time.

#### `clock.tick()`

This method is called automatically at every timestep. All
`Delayed` instances are checked during `tick`.

> **Note:**
>
> See [Room#setTimestep()](https://docs.colyseus.io/room.md#game-loop) for more details.

### Clock Properties

#### `clock.elapsedTime`

Elapsed time in milliseconds since [`clock.start()`](#clockstart) method was called. Read only.

#### `clock.currentTime`

Current time in milliseconds. Read only.

#### `clock.deltaTime`

The difference in milliseconds between the last and current `clock.tick()` call. Read only.

## Delayed

Delayed instances are created from
[`clock.setInterval()`](#clocksetintervalcallback-time-args-delayed) or
[`clock.setTimeout()`](#clocksettimeoutcallback-time-args-delayed) methods.

### Public methods

#### `delayed.pause()`

Pause the time of a particular `Delayed` instance. (`elapsedTime` is not going to increase until `.resume()` is called.)

#### `delayed.resume()`

Resumes the time of a particular `Delayed` instance. (`elapsedTime` is going to continue to increase normally)

#### `delayed.clear()`

Clears the timeout or interval.

#### `delayed.reset()`

Reset the elapsed time.

### Public properties

#### `delayed.elapsedTime: number`

Elapsed time of the `Delayed` instance, in milliseconds since started.

#### `delayed.active: boolean`

Returns `true` if timer is still running.

#### `delayed.paused: boolean`

Returns `true` if timer has been paused via `.pause()`.

---
Source: https://docs.colyseus.io/room/timing-events


# Scalability

> **Warning:**
>
> If you find configuring scalability overwhelming, consider using [Colyseus Cloud](https://cloud.colyseus.io/) to easily deploy and scale your Colyseus servers.
>
> You do not need to specify `driver`, `presence`, or `publicAddress` when using Colyseus Cloud.

## How does Colyseus achieve scalability?

- Increasing the number of processes will increase the amount of rooms that can be created.
- Rooms are equally distributed across the available processes.
- Each Room belongs to a single Colyseus process.
- Each process **has a maximum amount of players** it can handle. _(The exact amount depends on many factors. [See our FAQ](https://docs.colyseus.io/faq.md#how-many-ccu-can-a-colyseus-server-handle).)_
- Client connections are directly associated with the process that created the room.

> **Note:**
>
> [Redis](https://redis.io/topics/quickstart) is required for scaling.

**Check out the diagram of how matchmaking works with scaling infrastructure and multiple processes.**

---

![Scalability diagram](https://docs.colyseus.io/diagrams/scalability.webp)

## Use a shared `Presence` and `Driver`

```ts {7-8} filename="server.ts"
import { defineServer } from "colyseus";
import { RedisPresence } from "@colyseus/redis-presence";
import { RedisDriver } from "@colyseus/redis-driver";

const server = defineServer({
  // ...
  presence: new RedisPresence(),
  driver: new RedisDriver(),
});
```

The process to join a Room consists of two requests:
- **Reserve a seat in the Room**: Any of the Colyseus processes can handle this request. By using a shared `presence` and `driver`, the framework is able to communicate internally via pub/sub to reserve a seat, or create a new room if necessary.
- **Establish a WebSocket connection with the Room**: The client will use the seat reservation information to connect directly to the process that created the room.

> **Note:**
>
> See [Presence API](https://docs.colyseus.io/server/presence.md) and [Driver](https://docs.colyseus.io/server/driver.md).

## Make each Colyseus process publicly accessible

Configure each Colyseus process to use its very own public address, so clients can connect directly to it.

```ts {6-9} filename="src/app.config.ts"
    import { defineServer } from "colyseus";
    // ...
    const server = defineServer({
        driver: new RedisDriver(),
        presence: new RedisPresence(),

        // use a unique public address for each process
        publicAddress: `backend.yourdomain.com/${(Number(process.env.PORT) + Number(process.env.NODE_APP_INSTANCE))}`,
        // ...
    });
    ```

You may have a regular load balancer sitting behind all the Colyseus processes in order to distribute the incoming connections. The load balancer must be the initial entrypoint.

## Spawn multiple Colyseus processes

To run multiple Colyseus instances in the same server, you need each one of them to listen on a different port number. It's recommended to use ports `2567`, `2568`, `2569`, `2570`, and so on.

The [PM2 Process Manager](http://pm2.keymetrics.io/) is recommended for managing multiple Node.js app instances, but not required.

```sh npm2yarn
npm install -g pm2
```

Use the following `ecosystem.config.js` configuration:

```js filename="ecosystem.config.js"
const os = require('os');
module.exports = {
    apps: [{
        port        : 2567,
        name        : "colyseus",
        script      : "build/index.js", // your compiled entrypoint file
        time        : true,
        watch       : false,
        instances   : os.cpus().length, // or manually set the amount of instances
        exec_mode   : 'fork',           // IMPORTANT: DO NOT use 'cluster' mode.
        wait_ready  : true,
    }]
}
```

Colyseus automatically adds PM2's `NODE_APP_INSTANCE` to the port number. If you specified `2567` as port number, the first instance will listen on port `2567`, the second instance on port `2568`, and so on.

---

Now you're ready to start multiple Colyseus processes.

```sh filename="Terminal"
pm2 start ecosystem.config.js
```

> **Warning:**
>
> **TypeScript Users** - It is recommended compile your TypeScript files before running `pm2 start`, via `npx tsc`. Alternatively, you can [install the TypeScript interpreter for PM2](http://pm2.keymetrics.io/docs/tutorials/using-transpilers-with-pm2) (`pm2 install typescript`) and set the `exec_interpreter: "ts-node"`.

## Use NGINX as a reverse proxy

Install [nginx](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/) and configure it to proxy requests to your Colyseus processes.

> **Note:**
>
> Prefer Traefik? The [Traefik Load Balancer](https://docs.colyseus.io/scalability/traefik.md) guide covers the same role with automatic service discovery and Let's Encrypt certificates.

The following NGINX config file will:
- Proxy requests to `backend.yourgame.com` to the Colyseus processes running on ports `2567`, `2568`, `2569`, `2570`, and so on.
- Dynamically use the port number from the URL, e.g. `backend.yourgame.com/2567/` will proxy to the Colyseus process running on port `2567`.

```sh {3-8,14,20-21,35-36} filename="/etc/nginx/sites-enabled/backend.yourgame.com"
error_page 502 /error.html;

upstream colyseus_servers {
    server 127.0.0.1:2567;
    server 127.0.0.1:2568;
    server 127.0.0.1:2569;
    server 127.0.0.1:2570;
}

server {
    listen 80 default_server;
    listen 443 ssl;

    server_name backend.yourgame.com;

    ssl_certificate /root/certs/fullchain.pem;
    ssl_certificate_key /root/certs/privkey.pem;

    # Proxy to the colyseus_servers upstream
    location / {
        proxy_pass http://colyseus_servers/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
        proxy_buffering off;
        proxy_next_upstream error timeout http_502;
        include proxy_params;
    }

    # Dynamically use the port number from the URL
    location ~ "^/(?<PORT>2[0-9]{3})/(.*)" {
        proxy_pass http://127.0.0.1:$PORT;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_read_timeout 86400s;
        proxy_send_timeout 86400s;
        proxy_buffering off;
        proxy_next_upstream error timeout http_502;
        include proxy_params;
    }

    location /error.html {
        root /var/www/html;
        internal;
    }
}
```

## SSL Certificate Setup

It is recommended to use SSL certificates to secure the communication between the client and the server. Replace the `ssl_certificate` and `ssl_certificate_key` paths in the NGINX configuration file with your own SSL certificates.

## Next Steps

- [Deployment](https://docs.colyseus.io/deployment.md) - The production checklist: PM2, HTTPS, health checks
- [Graceful Shutdown](https://docs.colyseus.io/server/graceful-shutdown.md) - How deploys drain rooms and notify clients
- [FAQ: How many CCU can a Colyseus server handle?](https://docs.colyseus.io/faq.md#how-many-ccu-can-a-colyseus-server-handle) - Capacity planning per process

---
Source: https://docs.colyseus.io/scalability


# Traefik Load Balancer

> **Note:**
>
> This module is experimental. Please report any issues you may find.

The `@colyseus/traefik` module allows you to dynamically expose Colyseus servers to [Traefik](https://traefik.io/) as a load balancer.

It automatically registers and de-registers Colyseus server instances with Traefik, enabling dynamic scaling and routing without manual configuration changes.

### Features

- **Dynamic registration**: Automatically registers server instances with Traefik on startup.
- **Auto cleanup**: Automatically de-registers on graceful shutdown.
- **Sticky sessions**: Routes clients to specific server instances via subdomain-based routing.
- **Load balancing**: Maintains an "all-servers" service for distributing new connections.
- **Health checks**: Built-in health check configuration support.
- **Config Providers**: Supports both Redis and HTTP Traefik providers.

### Requirements

- **Redis/Valkey** with Keyspace Notifications enabled (for Redis provider).
- [RedisPresence](https://docs.colyseus.io/server/presence.md#redis-presence) for presence management.
- **Traefik v2+** configured with Redis or HTTP provider.

## Installation

```sh npm2yarn
npm install @colyseus/traefik
```

## Usage

```typescript
import { defineServer, matchMaker, RedisPresence } from "colyseus";
import { exposeServerToTraefik } from "@colyseus/traefik";

const server = defineServer({
  presence: new RedisPresence(),
  publicAddress: "node-1.yourgamedomain.com", // Unique address for this server instance
});

await server.listen(2567);

// Expose this server to Traefik
await exposeServerToTraefik({
  server,
  mainAddress: "backend.yourgamedomain.com", // Main load balancer address
});
```

## API

### `exposeServerToTraefik(options: TraefikOptions)`

Registers the Colyseus server with Traefik for load balancing.

#### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `server` | `Server` | **required** | The Colyseus server instance to expose |
| `mainAddress` | `string` | **required** | The main Traefik load balancer address (e.g., `"backend.yourgamedomain.com"`) |
| `provider` | `"http"` \| `"redis"` | `"redis"` | The Traefik provider to use |
| `internalAddress` | `string` | auto-detected | Internal IP/hostname for the server. Port is auto-detected if not provided (e.g., `"192.168.1.100"` or `"192.168.1.100:2567"`) |
| `redisRootKey` | `string` | `"traefik"` | The root key for Traefik configuration in Redis |
| `healthCheckOptions` | `object` | see below | Health check configuration |

#### Default Health Check Options

```typescript
{
  path: "/__healthcheck",
  interval: "10s",
  timeout: "3s"
}
```

## Traefik Configuration

**Redis Provider (Recommended)**

The Redis provider allows Traefik to read configuration directly from Redis, providing real-time updates when servers join or leave.

```yaml {2-5} filename="traefik.yml"
providers:
  redis:
    rootKey: "traefik"
    endpoints:
      - "127.0.0.1:6379"

entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"
```

```typescript {3} filename="app.config.ts"
await exposeServerToTraefik({
    server,
    provider: "redis",
    mainAddress: "backend.yourgamedomain.com",
});
```

**HTTP Provider**

The HTTP provider exposes a `/__traefik` endpoint on your Colyseus server that Traefik polls for configuration updates.

```yaml {2-4} filename="traefik.yml"
providers:
  http:
    endpoint: "http://127.0.0.1:2567/__traefik"
    pollInterval: "5s"

entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"
```

```typescript {3} filename="app.config.ts"
await exposeServerToTraefik({
    server,
    provider: "http",
    mainAddress: "backend.yourgamedomain.com",
});
```

## How It Works

### Routing Architecture

This module creates two types of routes in Traefik:

1. **Main load balancer route** (`mainAddress`)
   - Routes to an "all-servers" service
   - Distributes new connections across all available server instances
   - Example: `backend.yourgamedomain.com`

2. **Per-server routes** (derived from `publicAddress`)
   - Each server gets its own subdomain-based route
   - Enables sticky sessions by routing clients to specific servers
   - Example: `node-1.yourgamedomain.com`, `node-2.yourgamedomain.com`

### Redis Key Structure

When using the Redis provider, the module creates keys in the following structure:

```
traefik/http/routers/{routerName}/rule
traefik/http/routers/{routerName}/service
traefik/http/services/{serviceName}/loadbalancer/servers/{serverId}/url
traefik/http/services/{serviceName}/loadbalancer/healthcheck/path
traefik/http/services/{serviceName}/loadbalancer/healthcheck/interval
traefik/http/services/{serviceName}/loadbalancer/healthcheck/timeout
```

### Lifecycle

1. **On startup**: Server registers itself with Traefik via Redis keys
2. **During operation**: Traefik routes traffic based on the registered configuration
3. **On shutdown**: Server removes its keys from Redis, automatically deregistering from Traefik

## Example: Multi-Server Setup

```typescript
// Server 1 (node-1.yourgamedomain.com)
const server1 = defineServer({
  presence: new RedisPresence(),
  publicAddress: "node-1.yourgamedomain.com",
});

await server1.listen(2567);
await exposeServerToTraefik({
  server: server1,
  mainAddress: "backend.yourgamedomain.com",
  internalAddress: "192.168.1.101:2567",
});

// Server 2 (node-2.yourgamedomain.com)
const server2 = defineServer({
  presence: new RedisPresence(),
  publicAddress: "node-2.yourgamedomain.com",
});

await server2.listen(2568);
await exposeServerToTraefik({
  server: server2,
  mainAddress: "backend.yourgamedomain.com",
  internalAddress: "192.168.1.102:2568",
});
```

With this setup:
- New clients connecting to `backend.yourgamedomain.com` are load-balanced across both servers
- Clients can connect directly to `node-1.yourgamedomain.com` or `node-2.yourgamedomain.com` for sticky sessions
- When reconnecting to a specific room, the SDK uses the server's `publicAddress` to route directly to the correct instance

---
Source: https://docs.colyseus.io/scalability/traefik


# Client SDK

- [Getting Started](https://docs.colyseus.io/getting-started.md)
- [State Sync Callbacks](https://docs.colyseus.io/state/callbacks.md)

The Client SDK provides everything you need to connect to a Colyseus server from your game or application.

---

## Client Setup

The `Client` instance is your entry point to connect to the server.

**TypeScript**

```ts filename="client.ts"
import { Client } from "@colyseus/sdk";
const client = new Client("http://localhost:2567");

// ... with full-stack type safety (optional)
import type { server } from "../../server/src/app.config.ts";
const client = new Client<typeof server>("http://localhost:2567");
```

**C#**

```cs filename="Client.cs"
using Colyseus;

Client client = new Client("http://localhost:2567");
```

**Lua**

```lua filename="client.lua"
local Colyseus = require("colyseus.sdk")

local client = Colyseus.Client("http://localhost:2567");
```

**Haxe**

```haxe filename="client.hx"
import io.colyseus.Client;

var client = new Client("http://localhost:2567");
```

**GDScript**

```gdscript filename="client.gd"
var client = Colyseus.Client.new("ws://localhost:2567")
```

**Dart**

```dart filename="client.dart"
import 'package:colyseus/colyseus.dart';

final client = ColyseusClient('ws://localhost:2567');
```

**GML**

```js filename="client.gml"
// Create event
client = colyseus_client_create("http://localhost:2567");

// Step event
colyseus_process(); // once per Step: delivers every queued event and callback
```

---

## Joining Rooms

Once you have a client, you can join rooms. Choose the method that best fits your matchmaking needs.

### Join or Create (Recommended)

The most common way to connect. Joins an existing room if available, or creates a new one.

**TypeScript**

```ts filename="client.ts"
try {
  const room = await client.joinOrCreate("battle", {/* options */});
  console.log("joined successfully", room);

} catch (e) {
  console.error("join error", e);
}
```

**C#**

```cs filename="Client.cs"
try {
  Colyseus.Room<YourStateClass> room = await client.JoinOrCreate<YourStateClass>("battle", /* Dictionary of options */);
  Debug.Log("joined successfully");

} catch (ex) {
  Debug.Log("join error");
  Debug.Log(ex.Message);
}
```

**Lua**

```lua filename="client.lua"
client:join_or_create("battle", {--[[options]]}, function(err, room)
  if (err ~= nil) then
    print("join error: " .. err)
    return
  end

  print("joined successfully")
end)
```

**Haxe**

```haxe filename="client.hx"
client.joinOrCreate("battle", [/* options */], YourStateClass, function(err, room) {
  if (err != null) {
    trace("join error: " + err);
    return;
  }

  trace("joined successfully");
});
```

**GDScript**

```gdscript filename="client.gd"
var room: Colyseus.Room = client.join_or_create("battle")

room.joined.connect(func():
    print("joined successfully"))

room.error.connect(func(code: int, message: String):
    printerr("join error: ", message))
```

**Dart**

```dart filename="client.dart"
try {
  final room = await client.joinOrCreate('battle',
      options: {/* options */}, stateType: MyRoomState.new);
  print('joined successfully');

} catch (e) {
  print('join error: $e');
}
```

**GML**

```js filename="client.gml"
// "room" is a GameMaker built-in, so use another name
net_room = colyseus_client_join_or_create(client, "battle", {/* options */});

colyseus_on_join(net_room, function(_room) {
    show_debug_message("joined successfully");
});

colyseus_on_error(net_room, function(_code, _message) {
    show_debug_message("join error: " + _message);
});
```

> **Note:**
>
> Locked or private rooms are ignored by this method.

### Other Join Methods

These methods use the same pattern as `joinOrCreate`. Replace the method name accordingly.

| Method | Signature | Description |
|--------|-----------|-------------|
| `create` | `client.create(roomName, options)` | Always creates a new room, even if others exist. |
| `join` | `client.join(roomName, options)` | Joins an existing room. Fails if none available. Locked/private rooms are ignored. |
| `joinById` | `client.joinById(roomId, options)` | Joins a specific room by its unique ID. **Private rooms can be joined by ID.** Useful for invite links. |
| `consumeSeatReservation` | `client.consumeSeatReservation(reservation)` | Joins with a seat your backend reserved. See [Consuming a Seat Reservation](#consuming-a-seat-reservation). |

> **Note:**
>
> You may disallow the client from creating rooms. See [Matchmaker → Restricting the frontend from creating rooms](https://docs.colyseus.io/matchmaker.md#restricting-the-frontend-from-creating-rooms)

**Example: Creating an invite link with `joinById`**

```ts filename="client.ts"
// Share the room ID with other players
const inviteLink = `https://mygame.com/join?roomId=${room.roomId}`;

// On the receiving end, parse the room ID and join
const params = new URLSearchParams(window.location.search);
const room = await client.joinById(params.get("roomId"));
```

### Consuming a Seat Reservation

Your backend can do the matchmaking itself and hand the client a seat. The server reserves it with a [matchmaker method](https://docs.colyseus.io/matchmaker.md#methods) such as `matchMaker.joinOrCreate()` or `matchMaker.reserveSeatFor()`. The client then joins with `consumeSeatReservation`, which makes no matchmaking request of its own.

```ts filename="app.config.ts"
import { defineServer, createEndpoint, createRouter, matchMaker } from "colyseus";

const findMatch = createEndpoint("/find_match", { method: "POST" }, async (ctx) => {
    // apply your own rules here (party, rank, region), then reserve the seat
    return await matchMaker.joinOrCreate("battle", { mode: "duo" });
});

const server = defineServer({
    routes: createRouter({ findMatch }),
});
```

The client posts to that route and consumes the reservation it returns:

**TypeScript**

```ts filename="client.ts"
const { data: reservation } = await client.http.post("/find_match");
const room = await client.consumeSeatReservation(reservation);
```

**C#**

```cs filename="Client.cs"
var reservation = await client.Http.Post<SeatReservation>("find_match");
var room = await client.ConsumeSeatReservation<YourStateClass>(reservation);
```

**Lua**

```lua filename="client.lua"
client.http:post("/find_match", function(err, reservation)
  if (err ~= nil) then return end

  client:consume_seat_reservation(reservation, function(err, room)
    if (err ~= nil) then
      print("join error: " .. err)
      return
    end
    print("joined " .. room.room_id)
  end)
end)
```

**Haxe**

```haxe filename="client.hx"
client.http.post("find_match", null, function(err, reservation) {
  if (err != null) return;

  client.consumeSeatReservation(reservation, YourStateClass, function(err, room) {
    if (err != null) {
      trace("join error: " + err);
      return;
    }
    trace("joined " + room.roomId);
  });
});
```

**GDScript**

```gdscript filename="client.gd"
client.http.post("/find_match", {}, func(err, reservation):
    if err:
        return
    # a Dictionary, or the same object as a JSON String
    var room: Colyseus.Room = client.consume_seat_reservation(reservation)
    room.joined.connect(func(): print("joined ", room.get_id()))
    room.error.connect(func(code, message): printerr("join error: ", message)))
```

**Dart**

```dart filename="client.dart"
final response = await client.http.post('/find_match');
final room = await client.consumeSeatReservation(
    SeatReservation.fromJson(response.json),
    stateType: MyRoomState.new);
```

**GML**

```js filename="client.gml"
colyseus_http_post(client, "/find_match", {}, function(_err, _reservation) {
    if (_err != undefined) return;

    net_room = colyseus_client_consume_seat_reservation(client, _reservation);
    colyseus_on_join(net_room, function(_room) {
        show_debug_message("joined " + colyseus_room_get_id(_room));
    });
    colyseus_on_error(net_room, function(_code, _message) {
        show_debug_message("join error: " + _message);
    });
});
```

A [queue](https://docs.colyseus.io/matchmaker/queue.md#receiving-a-seat-reservation) or lobby room can send the reservation as a message instead. Pass the message payload the same way. GDScript and GML take it as it arrives (a `Dictionary` and a struct), and Dart reads it with `SeatReservation.fromJson()`.

The [Swift](https://docs.colyseus.io/getting-started/swift.md#quick-example) and [C](https://docs.colyseus.io/getting-started/native-sdk.md#seat-reservations) SDKs expose the same call. Minimum native SDK versions: Godot 0.18.4, Flutter 0.18.5, GameMaker 0.18.5, Swift and C 0.18.9.

> **Note:**
>
> A reservation expires if the client doesn't join within the room's `seatReservationTimeout` (15 seconds by default). When the server sets a [`publicAddress`](https://docs.colyseus.io/server.md#public-address-publicaddress), the reservation carries it, and the client connects to that address directly.

---

## Send and Receive Messages

Once connected to a room, you can send and receive messages in real-time.

### Sending Messages

Send messages to the room. Messages are encoded with MsgPack and can hold any JSON-serializable data.

**TypeScript**

```ts filename="client.ts"
//
// sending message with string type
//
room.send("move", { direction: "left"});

//
// sending message with number type
//
room.send(0, { direction: "left"});
```

**C#**

```cs filename="Client.cs"
//
// sending message with string type
//
await room.Send("move", new { direction = "left" });

//
// sending message with number type
//
await room.Send(0, new { direction = "left" });
```

**Lua**

```lua filename="client.lua"
--
-- sending message with string type
--
room:send("move", { direction = "left" })

--
-- sending message with number type
--
room:send(0, { direction = "left" })
```

**Haxe**

```haxe filename="client.hx"
//
// sending message with string type
//
room.send("move", { direction: "left" });

//
// sending message with number type
//
room.send(0, { direction: "left" });
```

**GDScript**

```gdscript filename="client.gd"
# sending message with string type
room.send_message("move", {"direction": "left"})

# sending message with number type
room.send_message(0, {"direction": "left"})
```

**Dart**

```dart filename="client.dart"
//
// sending message with string type
//
room.send('move', {'direction': 'left'});

//
// sending message with number type
//
room.sendInt(0, {'direction': 'left'});
```

**GML**

```js filename="client.gml"
// sending message with string type
colyseus_send(net_room, "move", { direction: "left" });

// sending message with number type
colyseus_send(net_room, 0, { direction: "left" });
```

> **Note:**
>
> **Backend:** See [Room → Message Handling](https://docs.colyseus.io/room.md#message-handling) for detailed documentation on receiving messages from the client.

### Send Raw Bytes

For custom encoding, send a `Uint8Array` of raw bytes.

```js filename="client.js"
//
// sending message with number type
//
room.sendBytes(0, new Uint8Array([ 172, 72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100, 33 ]));

//
// sending message with string type
//
room.sendBytes("some-bytes", new Uint8Array([ 172, 72, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100, 33 ]));
```

> **Warning:**
>
> The payload must be a `Uint8Array`. A plain `number[]` array silently sends an **empty** message, since the SDK reads `.byteLength` from the payload.

### Receiving Messages

Listen for messages sent from the server.

**TypeScript**

```ts filename="client.ts"
room.onMessage("powerup", (message) => {
  console.log("message received from server");
  console.log(message);
});
```

**C#**

```cs filename="Client.cs"
class PowerUpMessage {
  string kind;
}

room.OnMessage<PowerUpMessage>("powerup", (message) => {
  Debug.Log ("message received from server");
  Debug.Log(message);
});
```

**Lua**

```lua filename="client.lua"
room:on_message("powerup", function(message)
  print("message received from server")
  print(message)
end)
```

**Haxe**

```haxe filename="client.hx"
room.onMessage("powerup", function(message) {
  trace("message received from server");
  trace(Std.string(message));
});
```

**GDScript**

```gdscript filename="client.gd"
room.message_received.connect(_on_message_received)

func _on_message_received(type: Variant, message: Variant):
    print("message received from server")
    print(message)
```

**Dart**

```dart filename="client.dart"
room.onMessage('powerup').listen((message) {
  print('message received from server');
  print(message);
});
```

**GML**

```js filename="client.gml"
// one handler per room receives every message type
colyseus_on_message(net_room, function(_room, _type, _message) {
    if (_type != "powerup") return;

    show_debug_message("message received from server");
    show_debug_message(_message);
});
```

> **Note:**
>
> **Backend:** To send a message from the server to a client, use [client.send()](https://docs.colyseus.io/room.md#send-message) or [room.broadcast()](https://docs.colyseus.io/room.md#broadcast-message).

### Request/Response

Send a message and await the server's reply. The server answers by [returning a value from its matching message handler](https://docs.colyseus.io/room.md#responding-to-a-message-requestresponse).

```ts filename="client.ts"
//
// Promise form: room.request(type, payload)
//
const profile = await room.request("get-profile", { userId: 42 });

//
// Override the default timeout (10s) per request
//
const result = await room.request("slow-task", { id }, { timeout: 30_000 });

//
// Callback form: pass a 3rd argument to room.send()
//
room.send("get-profile", { userId: 42 }, (profile, error) => {
    if (error) { return console.error(error); }
    console.log(profile);
});
```

The promise rejects (or the callback receives an `error`) when the handler throws or no handler is registered for that type. Rejection also happens when the connection closes first, or when no reply arrives within the timeout. The default timeout is `Room.defaultRequestTimeout` (10000 ms), overridable per request via the `timeout` option.

The server may also **deliberately reject** a request via [`ctx.reject(reason)`](https://docs.colyseus.io/room.md#responding-to-a-message-requestresponse): a business-logic "no", distinct from an error. The rejection arrives as an `Error` with `name: "rejected"`, and the server's raw `reason` on its `.reason` property:

```ts filename="client.ts"
try {
    await room.request("join-team", { team: "red" });
} catch (e: any) {
    if (e.name === "rejected") {
        console.log(e.reason); // => { code: "TEAM_FULL", team: "red" }
    }
}
```

Pass `mode: "unreliable"` in the options to send the request over the unreliable channel, when the transport has one. A genuine packet drop is then surfaced by the timeout.

> **Note:**
>
> Request/response is currently available in the **JavaScript/TypeScript** SDK.

---

## Sending Input (Netcode)

For prediction-ready rooms (rooms that call [`defineInput()`](https://docs.colyseus.io/netcode/server-input.md) on the server), `room.input()` returns a typed input channel: stage fields on `input.data`, then `input.send()` once per fixed step.

```ts filename="client.ts"
const input = room.input();   // input schema arrives from the server's defineInput()

input.data.moveX = 1;
input.data.jump = true;
input.send();
```

Inputs are buffered and acknowledged, and power [client-side prediction](https://docs.colyseus.io/netcode/client-prediction.md) and [lag compensation](https://docs.colyseus.io/netcode/lag-compensation.md). See **[`room.input(options)`](https://docs.colyseus.io/netcode/client-prediction.md#roominputoptions)** for the full reference: reliability modes, redundancy, and the `InputHandle` surface.

> **Note:**
>
> The netcode APIs (`room.input()`, `room.clock`, `Predict`) are available in Colyseus 0.18+ **across the official SDKs**. See [Client Prediction](https://docs.colyseus.io/netcode/client-prediction.md).

---

## State Synchronization

The room state is automatically synchronized from the server to all connected clients. The `room.state` property always contains the latest state.

### State Sync Callbacks (Recommended)

Use `Callbacks` to listen for specific property changes with fine-grained control.

**TypeScript**

```ts filename="client.ts"
import { Callbacks } from "@colyseus/sdk";

const callbacks = Callbacks.get(room);

callbacks.listen("currentTurn", (currentValue, previousValue) => {
    console.log("Turn changed:", previousValue, "->", currentValue);
});

callbacks.onAdd("players", (player, sessionId) => {
    console.log("Player joined:", sessionId);

    callbacks.listen(player, "hp", (currentHp, previousHp) => {
        console.log("Player", sessionId, "hp:", currentHp);
    });
});

callbacks.onRemove("players", (player, sessionId) => {
    console.log("Player left:", sessionId);
});
```

**C#**

```cs filename="client.cs"
var callbacks = Colyseus.Schema.Callbacks.Get(room);

callbacks.Listen(state => state.currentTurn, (currentValue, previousValue) => {
    Debug.Log($"Turn changed: {previousValue} -> {currentValue}");
});

callbacks.OnAdd(state => state.players, (sessionId, player) => {
    Debug.Log($"Player joined: {sessionId}");

    callbacks.Listen(player, p => p.hp, (currentHp, previousHp) => {
        Debug.Log($"Player {sessionId} hp: {currentHp}");
    });
});

callbacks.OnRemove(state => state.players, (sessionId, player) => {
    Debug.Log($"Player left: {sessionId}");
});
```

**Lua**

```lua filename="client.lua"
local callbacks = ColyseusSDK.callbacks(room)

callbacks:listen("currentTurn", function(currentValue, previousValue)
    print("Turn changed: " .. tostring(previousValue) .. " -> " .. tostring(currentValue))
end)

callbacks:on_add("players", function(player, sessionId)
    print("Player joined: " .. sessionId)

    callbacks:listen(player, "hp", function(currentHp, previousHp)
        print("Player " .. sessionId .. " hp: " .. tostring(currentHp))
    end)
end)

callbacks:on_remove("players", function(player, sessionId)
    print("Player left: " .. sessionId)
end)
```

**Haxe**

```haxe filename="client.hx"
import io.colyseus.serializer.schema.Callbacks;

var callbacks = Callbacks.get(room);

callbacks.listen("currentTurn", function(currentValue, previousValue) {
    trace("Turn changed: " + previousValue + " -> " + currentValue);
});

callbacks.onAdd("players", function(player, sessionId) {
    trace("Player joined: " + sessionId);

    callbacks.listen(player, "hp", function(currentHp, previousHp) {
        trace("Player " + sessionId + " hp: " + currentHp);
    });
});

callbacks.onRemove("players", function(player, sessionId) {
    trace("Player left: " + sessionId);
});
```

**GDScript**

```gdscript filename="client.gd"
var callbacks = Colyseus.Callbacks.of(room)

callbacks.listen("currentTurn", _on_turn_change)
callbacks.on_add("players", _on_player_add)
callbacks.on_remove("players", _on_player_remove)

func _on_turn_change(current_value, previous_value):
    print("Turn changed: ", previous_value, " -> ", current_value)

func _on_player_add(player: Dictionary, key: String):
    callbacks.listen(player, "hp", func(current_hp, previous_hp):
        print("Player ", key, " hp: ", current_hp))

func _on_player_remove(player: Dictionary, key: String):
    print("Player left: ", key)
```

**Dart**

```dart filename="client.dart"
final callbacks = Callbacks.get(room);
final state = room.state!;   // joined with stateType: MyRoomState.new

callbacks.listen(state, 'currentTurn', (String value, String? previous) {
  print('Turn changed: $previous -> $value');
});

callbacks.onAdd(state.players, (sessionId, player) {
  print('Player joined: $sessionId');

  callbacks.listen(player, 'hp', (double hp, double? previous) {
    print('Player $sessionId hp: $hp');
  });
});

callbacks.onRemove(state.players, (sessionId, player) {
  print('Player left: $sessionId');
});
```

**GML**

```js filename="client.gml"
// the callbacks manager needs the joined room's state
colyseus_on_join(net_room, function(_room) {
    callbacks = colyseus_callbacks_create(_room);

    colyseus_listen(callbacks, "currentTurn", function(_value, _previous) {
        show_debug_message("Turn changed: " + string(_previous) + " -> " + string(_value));
    });

    colyseus_on_add(callbacks, "players", function(_player, _session_id) {
        show_debug_message("Player joined: " + _session_id);

        // nested callbacks can't see outer locals: bind them with method()
        colyseus_listen(callbacks, _player, "hp", method({ session_id: _session_id }, function(_hp, _previous) {
            show_debug_message("Player " + session_id + " hp: " + string(_hp));
        }));
    });

    colyseus_on_remove(callbacks, "players", function(_player, _session_id) {
        show_debug_message("Player left: " + _session_id);
    });
});
```

> **Note:**
>
> See the full [State Sync Callbacks](https://docs.colyseus.io/state/callbacks.md) documentation for all available methods including `listen`, `onAdd`, `onRemove`, and more.

### On State Change

The `onStateChange` event fires whenever the server synchronizes state updates. Use this when you need to know _something_ changed, without tracking individual properties.

```ts
room.onStateChange((state) => {
    console.log("the room state has been updated:", state);
});
```

> **Note:**
>
> Read more about [ State Synchronization](https://docs.colyseus.io/state.md)

---

## Connection Lifecycle

Leaving a room, automatic and manual reconnection, error handling, and
removing listeners. See
**[Connection Lifecycle & Reconnection](https://docs.colyseus.io/sdk/connection.md)** for the full reference.

---

## Latency & Server Selection

Measure network latency and choose optimal servers for your players.

### Measuring Latency

#### Before Joining

Create a temporary connection to measure latency before joining a room.

**Parameters**

- `options.pingCount`: Number of pings to send (default: `1`). Returns the average latency when greater than 1.

**TypeScript**

```ts filename="client.ts"
const latency = await client.getLatency();
console.log("Latency:", latency, "ms");

// With multiple pings for a more accurate average
const avgLatency = await client.getLatency({ pingCount: 5 });
console.log("Average Latency:", avgLatency, "ms");
```

**C#**

```cs filename="Client.cs"
float latency = await client.GetLatency();
Debug.Log("Latency: " + latency + " ms");

// With multiple pings for a more accurate average
float avgLatency = await client.GetLatency(new LatencyOptions { PingCount = 5 });
Debug.Log("Average Latency: " + avgLatency + " ms");
```

**Lua**

```lua filename="client.lua"
client:get_latency(function(err, latency)
  print("Latency: " .. latency .. " ms")
end)

-- With multiple pings for a more accurate average
client:get_latency({ ping_count = 5 }, function(err, avg_latency)
  print("Average Latency: " .. avg_latency .. " ms")
end)
```

**Haxe**

```haxe filename="client.hx"
client.getLatency(function(err, latency) {
  trace("Latency: " + latency + " ms");
});

// With multiple pings for a more accurate average
client.getLatency({ pingCount: 5 }, function(err, avgLatency) {
  trace("Average Latency: " + avgLatency + " ms");
});
```

**GDScript**

```gdscript filename="client.gd"
# Latency measurement API may vary in the Godot SDK
# Check the SDK documentation for available methods
```

**Dart**

```dart filename="client.dart"
// Not available in the Flutter SDK.
// Measure round-trip time on a live connection with room.ping() instead.
```

**GML**

```js filename="client.gml"
colyseus_get_latency(client, "ws://localhost:2567", function(_err, _latency) {
    if (_err != undefined) return;
    show_debug_message("Latency: " + string(_latency) + " ms");
});

// No pingCount option: each call sends one ping.
```

#### During a Room Connection

Measure round-trip time on an existing connection.

**TypeScript**

```ts filename="client.ts"
room.ping((latency) => {
  console.log("Latency:", latency, "ms");
});
```

**C#**

```cs filename="Client.cs"
room.Ping((latency) => {
  Debug.Log("Latency: " + latency + " ms");
});
```

**Lua**

```lua filename="client.lua"
room:ping(function(latency)
  print("Latency: " .. latency .. " ms")
end)
```

**Haxe**

```haxe filename="client.hx"
room.ping(function(latency) {
  trace("Latency: " + latency + " ms");
});
```

**GDScript**

```gdscript filename="client.gd"
# Ping API may vary in the Godot SDK
# Check the SDK documentation for available methods
```

**Dart**

```dart filename="client.dart"
final latency = await room.ping();
print('Latency: $latency ms');
```

**GML**

```js filename="client.gml"
// Not available in the GameMaker SDK.
// Measure latency with colyseus_get_latency() instead.
```

> **Note:**
>
> If the connection is not open, calling `ping()` has no effect.

### Multi-Region Server Selection

Automatically connect to the server with the lowest latency from a list of endpoints.

**Parameters**

- `endpoints`: Array of server endpoints (URLs or endpoint settings objects).
- `options`: Optional client options to pass to each client instance.
- `latencyOptions.pingCount`: Number of pings to send per endpoint (default: `1`).

**TypeScript**

```ts filename="client.ts"
import { Client } from "@colyseus/sdk";

// Select the best server from multiple regions
const client = await Client.selectByLatency([
  "https://us-east.gameserver.com",
  "https://eu-west.gameserver.com",
  "https://asia.gameserver.com",
]);

// Now use the client with the lowest latency
const room = await client.joinOrCreate("game");
```

**C#**

```cs filename="Client.cs"
using Colyseus;

// Select the best server from multiple regions
Colyseus.Client client = await Colyseus.Client.SelectByLatency(new string[] {
    "https://us-east.gameserver.com",
    "https://eu-west.gameserver.com",
    "https://asia.gameserver.com"
});

// Now use the client with the lowest latency
Room<YourStateClass> room = await client.joinOrCreate<YourStateClass>("game");
```

**Lua**

```lua filename="client.lua"
local Colyseus = require("colyseus.sdk")

-- Select the best server from multiple regions
Colyseus.Client.select_by_latency({
  "https://us-east.gameserver.com",
  "https://eu-west.gameserver.com",
  "https://asia.gameserver.com"
}, function(err, client)
  -- Now use the client with the lowest latency
  client:join_or_create("game", {}, function(err, room)
    print("joined successfully")
  end)
end)
```

**Haxe**

```haxe filename="client.hx"
import io.colyseus.Client;

// Select the best server from multiple regions
Client.selectByLatency([
  "https://us-east.gameserver.com",
  "https://eu-west.gameserver.com",
  "https://asia.gameserver.com"
], function(err, client) {
  // Now use the client with the lowest latency
  client.joinOrCreate("game", [], YourStateClass, function(err, room) {
    trace("joined successfully");
  });
});
```

**GDScript**

```gdscript filename="client.gd"
# Multi-region server selection may vary in the Godot SDK
# You can manually test latency to multiple endpoints:
var endpoints = [
    "wss://us-east.gameserver.com",
    "wss://eu-west.gameserver.com",
    "wss://asia.gameserver.com"
]

# Select endpoint with lowest latency and create client
var client = Colyseus.Client.new(endpoints[0])  # Set your preferred endpoint
```

**Dart**

```dart filename="client.dart"
// Multi-region selection is not available in the Flutter SDK.
// Pick an endpoint yourself and create the client for it:
final client = ColyseusClient('wss://us-east.gameserver.com');
```

**GML**

```js filename="client.gml"
// Select the best server from multiple regions
colyseus_select_by_latency(client, [
    "wss://us-east.gameserver.com",
    "wss://eu-west.gameserver.com",
    "wss://asia.gameserver.com"
], function(_err, _best) {
    if (_err != undefined) return;

    // Now use a client for the lowest-latency endpoint
    colyseus_client_free(client);
    client = colyseus_client_create(_best.endpoint);

    net_room = colyseus_client_join_or_create(client, "game", {});
    colyseus_on_join(net_room, function(_room) {
        show_debug_message("joined successfully");
    });
});
```

> **Note:**
>
> The method logs the latency for each endpoint to the console for debugging purposes. If all endpoints fail to respond, an error is thrown.

---

## HTTP Requests

The `client.http` utility performs HTTP requests to your server endpoint. The `client.auth.token` is sent automatically as an `Authorization` header.

```ts
// GET
const response = await client.http.get("/profile");

// POST
const response = await client.http.post("/profile", { body: { name: "Jake" } });

// PUT
const response = await client.http.put("/profile", { body: { name: "Jake" } });

// DELETE
const response = await client.http.delete("/profile");
```

> **Note:**
>
> See [ Server → HTTP Routes](https://docs.colyseus.io/server/http-routes.md) for setting up HTTP endpoints on your server, and [ Authentication → HTTP Middleware](https://docs.colyseus.io/auth/http.md) for securing them.

---

## Room Reference

Quick reference for room properties.

| Property | Type | Description |
|----------|------|-------------|
| `state` | `any` | The synchronized room state from the server |
| `sessionId` | `string` | Unique identifier for the current client connection |
| `roomId` | `string` | Unique room ID (shareable for direct joins) |
| `name` | `string` | Name of the room type (e.g., `"battle"`) |
| `reconnectionToken` | `string` | Token for manual reconnection |
| `reconnection` | `ReconnectionOptions` | Automatic reconnection configuration |
| `clock` | `RoomClock` | Server time & latency estimates (`serverNow()`, `rtt()`). See [`room.clock`](https://docs.colyseus.io/netcode/client-prediction.md#roomclock) |

---

## Next Steps

- [State Sync Callbacks](https://docs.colyseus.io/state/callbacks.md) - Listen for state changes on the client
- [Netcode](https://docs.colyseus.io/netcode.md) - Predict local input and reconcile to server state
- [Room API](https://docs.colyseus.io/room.md) - Server-side room implementation
- [Authentication](https://docs.colyseus.io/auth.md) - Secure your room connections
- [Tutorials](https://docs.colyseus.io/learn/tutorial.md) - Step-by-step game implementations

---
Source: https://docs.colyseus.io/sdk


# Connection Lifecycle & Reconnection

Handle the various states of a room connection.

## Leaving a Room

Disconnect from the room. Use `consented: true` (default) for intentional leaves, or `false` to simulate an unexpected disconnect.

**TypeScript**

```ts filename="client.ts"
// consented leave
room.leave();

// force unconsented leave
room.leave(false);
```

**C#**

```cs filename="Client.cs"
// consented leave
room.Leave();

// unconsented leave
room.Leave(false);
```

**Lua**

```lua filename="client.lua"
-- consented leave
room:leave()

-- unconsented leave
room:leave(false)
```

**Haxe**

```haxe filename="client.hx"
// consented leave
room.leave();

// unconsented leave
room.leave(false);
```

**GDScript**

```gdscript filename="client.gd"
# consented leave
room.leave()
```

**Dart**

```dart filename="client.dart"
// consented leave
await room.leave();
```

> **Note:**
>
> **Backend:** Use [Room → On Leave](https://docs.colyseus.io/room/lifecycle.md#on-leave) to handle client disconnection.

**Listening for the leave event:**

**TypeScript**

```ts filename="client.ts"
room.onLeave((code) => {
  console.log("client left the room");
});
```

**C#**

```cs filename="Client.cs"
room.OnLeave += (code) => {
  Debug.Log ("client left the room");
}
```

**Lua**

```lua filename="client.lua"
room:on("leave", function()
  print("client left the room")
end)
```

**Haxe**

```haxe filename="client.hx"
room.onLeave += function () {
  trace("client left the room");
};
```

**GDScript**

```gdscript filename="client.gd"
room.left.connect(_on_room_left)

func _on_room_left(code: int, reason: String):
    print("client left the room: ", reason)
```

**Dart**

```dart filename="client.dart"
room.onLeave.listen((code) {
  print('client left the room');
});
```

**Possible closing `code`s and their meaning:**

- `1000` - Regular socket shutdown
- Between `1001` and `1015` - Abnormal socket shutdown
- Between `4000` and `4010` - Reserved by the framework (`CONSENTED`, `SERVER_SHUTDOWN`, `FAILED_TO_RECONNECT`, …)
- Between `4011` and `4999` - Custom application close code (See [more details](https://docs.colyseus.io/room.md#table-of-websocket-close-codes))

## Automatic Reconnection

The SDK automatically attempts to reconnect when the connection is unexpectedly dropped.

> **Warning:**
>
> Automatic reconnection only triggers if the room has been connected for at least `minUptime` milliseconds. This threshold prevents reconnection loops for rooms that fail immediately after joining.

### On Drop Event

Triggered when the connection is unexpectedly dropped. The SDK will automatically attempt to reconnect.

**TypeScript**

```ts filename="client.ts"
room.onDrop((code, reason) => {
  console.log("connection dropped, attempting to reconnect...");
  console.log("code:", code, "reason:", reason);
});
```

**C#**

```cs filename="Client.cs"
room.OnDrop += (code, reason) => {
  Debug.Log("connection dropped, attempting to reconnect...");
  Debug.Log("code: " + code + " reason: " + reason);
};
```

**Lua**

```lua filename="client.lua"
room:on("drop", function(code, reason)
  print("connection dropped, attempting to reconnect...")
  print("code:", code, "reason:", reason)
end)
```

**Haxe**

```haxe filename="client.hx"
room.onDrop += function(code, reason) {
  trace("connection dropped, attempting to reconnect...");
  trace("code: " + code + " reason: " + reason);
};
```

**GDScript**

```gdscript filename="client.gd"
# The Godot SDK handles reconnection automatically
# Use the error signal to detect connection issues
room.error.connect(func(code: int, message: String):
    print("connection error: ", message))
```

**Dart**

```dart filename="client.dart"
room.onDrop.listen((error) {
  print('connection dropped, attempting to reconnect...');
  print('code: ${error.code} reason: ${error.message}');
});
```

> **Note:**
>
> The `onDrop` event is different from `onLeave`. While `onLeave` is triggered when the client intentionally leaves or the connection is permanently closed, `onDrop` indicates a temporary disconnection where reconnection will be attempted.

> **Note:**
>
> **Close codes that trigger `onDrop`:**
> - `1005` - No status received
> - `1006` - Abnormal closure
> - `1001` - Going away
> - `4010` - May try reconnect

### On Reconnect Event

Triggered when the client successfully reconnects after a connection drop. While disconnected, your `room.send()` calls will be queued and sent to the server when the client reconnects. The maximum number of queued messages is configurable using `room.reconnection.maxEnqueuedMessages`.

**TypeScript**

```ts filename="client.ts"
room.onReconnect(() => {
  console.log("successfully reconnected to the room!");
});
```

**C#**

```cs filename="Client.cs"
room.OnReconnect += () => {
  Debug.Log("successfully reconnected to the room!");
};
```

**Lua**

```lua filename="client.lua"
room:on("reconnect", function()
  print("successfully reconnected to the room!")
end)
```

**Haxe**

```haxe filename="client.hx"
room.onReconnect += function() {
  trace("successfully reconnected to the room!");
};
```

**GDScript**

```gdscript filename="client.gd"
# The Godot SDK handles reconnection automatically
# The joined signal will fire again after successful reconnection
room.joined.connect(func():
    print("connected/reconnected to the room!"))
```

**Dart**

```dart filename="client.dart"
room.onReconnect.listen((_) {
  print('successfully reconnected to the room!');
});
```

### Reconnection Options

You may configure the reconnection behavior using `room.reconnection`.

**Reconnection config options**

| Option | Default | Description |
|--------|---------|-------------|
| `enabled` | `true` | Set to `false` to disable automatic reconnection entirely |
| `maxRetries` | `15` | Maximum reconnection attempts |
| `minDelay` | `100` | Minimum delay between attempts (ms) |
| `maxDelay` | `5000` | Maximum delay between attempts (ms) |
| `minUptime` | `5000` | Minimum room uptime before reconnection is allowed (ms) |
| `delay` | `100` | Initial delay between attempts (ms) |
| `maxEnqueuedMessages` | `10` | Maximum buffered messages during reconnection |
| `backoff` | exponential | Delay calculation function |

**Status properties** _(read-only)_

| Property | Type | Description |
|----------|------|------------|
| `isReconnecting` | boolean | Whether currently reconnecting |
| `retryCount` | number | Current reconnection attempt count |
| `enqueuedMessages` | array | Messages buffered while disconnected (count: `.length`) |

**Customizing reconnection behavior:**

**TypeScript**

```ts filename="client.ts"
const room = await client.joinOrCreate("battle");

// Customize reconnection options
room.reconnection.maxRetries = 10;
room.reconnection.maxDelay = 10000; // 10 seconds max delay
room.reconnection.minUptime = 3000; // Allow reconnection after 3 seconds
```

**C#**

```cs filename="Client.cs"
Colyseus.Room<YourStateClass> room = await client.JoinOrCreate<YourStateClass>("battle");

// Customize reconnection options
room.Reconnection.MaxRetries = 10;
room.Reconnection.MaxDelay = 10000; // 10 seconds max delay
room.Reconnection.MinUptime = 3000; // Allow reconnection after 3 seconds
```

**Lua**

```lua filename="client.lua"
client:join_or_create("battle", {}, function(err, room)
  -- Customize reconnection options
  room.reconnection.max_retries = 10
  room.reconnection.max_delay = 10000 -- 10 seconds max delay
  room.reconnection.min_uptime = 3000 -- Allow reconnection after 3 seconds
end)
```

**Haxe**

```haxe filename="client.hx"
client.joinOrCreate("battle", [], YourStateClass, function(err, room) {
  // Customize reconnection options
  room.reconnection.maxRetries = 10;
  room.reconnection.maxDelay = 10000; // 10 seconds max delay
  room.reconnection.minUptime = 3000; // Allow reconnection after 3 seconds
});
```

**GDScript**

```gdscript filename="client.gd"
# Reconnection is handled automatically by the Godot SDK
# Configuration options may vary - check the SDK documentation
```

**Dart**

```dart filename="client.dart"
final room = await client.joinOrCreate('battle');

// Customize reconnection options
room.setReconnectionOptions(
  maxRetries: 10,
  maxDelayMs: 10000, // 10 seconds max delay
  minUptimeMs: 3000, // Allow reconnection after 3 seconds
);
```

**Custom backoff function:**

**TypeScript**

```ts filename="client.ts"
room.reconnection.backoff = (attempt: number, delay: number) => {
  return Math.floor(Math.pow(2, attempt) * delay);
};
```

**C#**

```cs filename="Client.cs"
room.Reconnection.Backoff = (attempt, delay) => {
  return (int)Math.Floor(Math.Pow(2, attempt) * delay);
};
```

**Lua**

```lua filename="client.lua"
room.reconnection.backoff = function(attempt, delay)
  return math.floor(math.pow(2, attempt) * delay)
end
```

**Haxe**

```haxe filename="client.hx"
room.reconnection.backoff = function(attempt:Int, delay:Int):Int {
  return Math.floor(Math.pow(2, attempt) * delay);
};
```

**GDScript**

```gdscript filename="client.gd"
# Custom backoff functions are not currently exposed in the Godot SDK
# The SDK uses a default exponential backoff strategy
```

**Dart**

```dart filename="client.dart"
// Custom backoff functions are not exposed in the Flutter SDK.
// The native core uses a default exponential backoff strategy.
```

## Manual Reconnection

For more control, you can manually reconnect using a cached reconnection token. Because this method returns a new room instance on the client, you must reattach all event listeners to the room after reconnecting.

- You must store/cache the `room.reconnectionToken` from an active room connection.
- The server needs to call [`.allowReconnection()`](https://docs.colyseus.io/room/reconnection.md#allowreconnectionclient-seconds) for that client.

**TypeScript**

```ts filename="client.ts"
try {
  const room = await client.reconnect(cachedReconnectionToken);
  console.log("joined successfully", room);

} catch (e) {
  console.error("join error", e);
}
```

**C#**

```cs filename="Client.cs"
try {
  Colyseus.Room<YourStateClass> room = await client.Reconnect<YourStateClass>(cachedReconnectionToken);
  Debug.Log("joined successfully");

} catch (ex) {
  Debug.Log("join error");
  Debug.Log(ex.Message);
}
```

**Lua**

```lua filename="client.lua"
client:reconnect(cached_reconnection_token, function(err, room)
  if (err ~= nil) then
    print("join error: " .. err)
    return
  end

  print("joined successfully")
end)
```

**Haxe**

```haxe filename="client.hx"
client.reconnect(cachedReconnectionToken, YourStateClass, function(err, room) {
  if (err != null) {
    trace("join error: " + err);
    return;
  }

  trace("joined successfully");
});
```

**GDScript**

```gdscript filename="client.gd"
var room: Colyseus.Room = client.reconnect(cached_reconnection_token)

room.joined.connect(func():
    print("reconnected successfully"))

room.error.connect(func(code: int, message: String):
    printerr("reconnect error: ", message))
```

**Dart**

```dart filename="client.dart"
try {
  final room = await client.reconnect(cachedReconnectionToken);
  print('joined successfully');

} catch (e) {
  print('join error: $e');
}
```

## Error Handling

Listen for errors that occur in the room.

**TypeScript**

```ts filename="client.ts"
room.onError((code, message) => {
  console.log("oops, error occurred:");
  console.log(message);
});
```

**C#**

```cs filename="Client.cs"
room.OnError += (code, message) => {
  Debug.Log ("oops, error occurred:");
  Debug.Log(message);
}
```

**Lua**

```lua filename="client.lua"
room:on("error", function(code, message)
  print("oops, error occurred:")
  print(message)
end)
```

**Haxe**

```haxe filename="client.hx"
room.onError += function(code, message) {
  trace("oops, error occurred:");
  trace(message);
};
```

**GDScript**

```gdscript filename="client.gd"
room.error.connect(_on_room_error)

func _on_room_error(code: int, message: String):
    printerr("oops, error occurred: ", message)
```

**Dart**

```dart filename="client.dart"
room.onError.listen((error) {
  print('oops, error occurred:');
  print('${error.code}: ${error.message}');
});
```

## Removing Listeners

Remove all event listeners from the room (`onJoin`, `onStateChange`, `onError`, `onLeave`, `onReconnect`, `onDrop`, registered message handlers, and schema callbacks):

```ts filename="client.ts"
room.removeAllListeners();
```

> **Note:**
>
> The SDK calls `removeAllListeners()` automatically when the room is left. You only need it to detach early, e.g. when tearing down a UI screen while staying connected.

---
Source: https://docs.colyseus.io/sdk/connection


# Server

The Colyseus `Server` instance holds the server configuration options, such as transport options, presence, matchmaking driver, etc.

- [**Transport**](https://docs.colyseus.io/server/transport.md) is the layer for bidirectional communication between server and client.
- [**Presence**](https://docs.colyseus.io/server/presence.md) is the implementation that enables communication between rooms and/or Node.js processes.
- [**Driver**](https://docs.colyseus.io/server/driver.md) is the storage driver used for storing and querying rooms during matchmaking.

## Overview

The recommended structure to initialize a new Colyseus server is created using `npm create colyseus-app@latest` command.

```sh filename="Terminal"
npm create colyseus-app@latest ./my-server
```

You may add your own [Room Definitions](https://docs.colyseus.io/room.md), and [API routes](https://docs.colyseus.io/server/http-routes.md) to your server:

```ts {2,6,10-12} filename="app.config.ts"
import { defineServer, defineRoom } from "colyseus";
import { MyRoom } from "./rooms/MyRoom";

const server = defineServer({
    rooms: {
        my_room: defineRoom(MyRoom),
    },
    express: (app) => {
        // Bind your express routes here:
        app.get("/", (req, res) => {
            res.send("It's time to kick ass and chew bubblegum!");
        });
    }
});
```

---

### Server Options

#### Transport (`transport`)

The Transport Layer is responsible for the networked communication between the server and the client.
Colyseus uses TCP/WebSockets for communication by default.

Each Transport has its own options you may customize.

> **Note:**
>
> The default transport is `WebSocketTransport`. See [Transport → WebSocket Transport (ws)](https://docs.colyseus.io/server/transport/ws.md) for more details.

```ts {2,5-7} filename="app.config.ts"
import { defineServer } from "colyseus";
import { WebSocketTransport } from "@colyseus/ws-transport";

const server = defineServer({
    transport: new WebSocketTransport({
        pingInterval: 10000
    }),
});
```

> **Note:**
>
> See [Transport](https://docs.colyseus.io/server/transport.md) for more details.

#### Driver (`driver`)

The matchmaking driver. Rooms are cached and queried against a Driver implementation. When scaling your Colyseus servers, you may need to provide a `driver` option that fits your needs.

> **Note:**
>
> See [Driver](https://docs.colyseus.io/server/driver.md) for more details.

#### Presence (`presence`)

When scaling Colyseus through multiple processes / machines, you need to provide a presence server. Read more about [Scalability](https://docs.colyseus.io/scalability.md), and the [`Presence API`](https://docs.colyseus.io/server/presence.md#presence-api).

``` typescript
import { defineServer, RedisPresence } from "colyseus";

const server = defineServer({
    // ...
    presence: new RedisPresence()
});
```

---

#### Routes (`routes`)

Type-safe HTTP endpoints for your server, built with `createRouter()` and `createEndpoint()`.

```ts {5-9} filename="app.config.ts"
import { defineServer, createRouter, createEndpoint } from "colyseus";

const server = defineServer({
    // ...
    routes: createRouter({
        hello: createEndpoint("/hello", { method: "GET" }, async (ctx) => {
            return { message: "Hello, world!" };
        }),
    }),
});
```

> **Note:**
>
> See [HTTP Routes](https://docs.colyseus.io/server/http-routes.md) for the full reference, including middleware and CORS.

#### Express (`express`)

A callback that receives an Express-compatible `app`, for binding routes with the classic Express API. With `uWebSocketsTransport`, the app is provided via the `uwebsockets-express` compatibility layer.

```ts {5-9} filename="app.config.ts"
import { defineServer } from "colyseus";

const server = defineServer({
    // ...
    express: (app) => {
        app.get("/", (req, res) => {
            res.send("Hello, world!");
        });
    },
});
```

> **Note:**
>
> Prefer [`routes`](#routes-routes) for new code: endpoints defined there are type-checked end to end, including on the client SDK.

#### Before Listen (`beforeListen`)

An optional callback executed before the server starts listening. Use it to connect to a database or other services first. `async` is supported: the server waits for it.

```ts {5-7} filename="app.config.ts"
import { defineServer } from "colyseus";

const server = defineServer({
    // ...
    beforeListen: async () => {
        await connectToMyDatabase();
    },
});
```

#### Database (`database`)

Boots a database module (usually `@colyseus/database`'s `db` instance) before the matchmaker accepts connections. The database may also contribute default routes, such as the auth endpoints.

```ts {2,6} filename="app.config.ts"
import { defineServer } from "colyseus";
import { db } from "./db";

const server = defineServer({
    // ...
    database: db,
});
```

> **Note:**
>
> See [Database](https://docs.colyseus.io/database.md) for the full setup.

#### Auth (`auth`)

Controls mounting of the [`@colyseus/auth`](https://docs.colyseus.io/auth/module.md) routes. Pass an options object to mount them explicitly (useful when `database` is not in use), or `false` to disable auto-mounting even when a `database` would provide defaults.

```ts filename="app.config.ts"
const server = defineServer({
    // ...
    auth: {
        oauth: true,
        prefix: "/auth",
    },
});
```

#### Public Address (`publicAddress`)

The public address advertised for this process (e.g. `"server-1.example.com"`). When scaling across multiple machines, each process should advertise its own address. The seat reservation returned to the SDK carries it, so clients connect to the right machine directly.

> **Note:**
>
> See [Scalability](https://docs.colyseus.io/scalability.md) for the multi-process setup.

#### Logger (`logger`)

Replace the built-in logger (an alias to `console` by default) with your own implementation, such as `pino` or `winston`.

> **Note:**
>
> See [Logging](https://docs.colyseus.io/server/logging.md) for ready-made configurations.

#### Greeting Banner (`greet`)

Whether to display the Colyseus greeting banner on server start. Default is `true`.

---

#### Select Process ID to Create Room

The `selectProcessIdToCreateRoom` is a callback that allows you to customize which process the new rooms should be created at, when your deployment uses multiple Colyseus processes.

By default, the process with the **least amount of rooms** is selected to create a new room.

```ts {4-8} filename="app.config.ts"
import { defineServer, matchMaker } from "colyseus";

const server = defineServer({
    selectProcessIdToCreateRoom: async function (roomName: string, clientOptions: any) {
        return (await matchMaker.stats.fetchAll())
            .sort((p1, p2) => p1.roomCount > p2.roomCount ? 1 : -1)[0]
            .processId;
    },
});
```

A common alternative is to use the process with least amount of **connections**:

```ts {4-8} filename="app.config.ts"
import { defineServer, matchMaker } from "colyseus";

const server = defineServer({
    selectProcessIdToCreateRoom: async function (roomName: string, clientOptions: any) {
        return (await matchMaker.stats.fetchAll())
            .sort((p1, p2) => p1.ccu > p2.ccu ? 1 : -1)[0]
            .processId;
    },
});
```

---

#### Standalone Matchmaker (`isStandaloneMatchMaker`)

When set to `true`, this process will only handle matchmaking and will **not** spawn rooms locally. Room creation is delegated to other game server processes via IPC.

Default is `false`.

```ts {4} filename="app.config.ts"
import { defineServer } from "colyseus";

const server = defineServer({
    isStandaloneMatchMaker: true,
});
```

> **Note:**
>
> See [Standalone Matchmaker](https://docs.colyseus.io/matchmaker/standalone.md) for a full setup guide.

---

#### Development Mode

When `devMode` is enabled, the server restores previous rooms and room state after a restart caused by a code change. This option is meant for iterating on room code in a local environment.

Default is `false`.

```ts {4} filename="app.config.ts"
import { defineServer } from "colyseus";

const server = defineServer({
    devMode: true,
});
```

> **Note:**
>
> See [Development Mode](https://docs.colyseus.io/server/devmode.md). If you use Vite, the [Vite Plugin](https://docs.colyseus.io/server/vite.md) provides HMR for both your frontend and server code from a single project.

---

#### Graceful Shutdown (`gracefullyShutdown`)

Whether to register the shutdown routine automatically. Default is `true`.

If disabled, you should call [`gracefullyShutdown()`](#graceful-shutdown) method manually in your shutdown process.

```ts {4} filename="app.config.ts"
import { defineServer } from "colyseus";

const server = defineServer({
    gracefullyShutdown: false,
});
```

> **Note:**
>
> See [Graceful Shutdown](https://docs.colyseus.io/server/graceful-shutdown.md).

---

## Methods

### Define Room Type

Define room types for the matchmaker using the `rooms` configuration in `defineServer()`.

- Rooms are **not created** during configuration
- Rooms are created upon client request ([See frontend methods](https://docs.colyseus.io/sdk.md#joining-rooms))

**Parameters:**

- `room_name` - The public name of the room. You'll use this name when joining the room from the frontend
- `RoomClass` - The `Room` class
- `defaultOptions` - _(optional)_ Default options merged into the client-provided options for `onCreate()` (room creation only)

```ts
const server = defineServer({
  rooms: {
    // Define "chat" room
    chat: defineRoom(ChatRoom),

    // Define "battle" room
    battle: defineRoom(BattleRoom),

    // Define "battle" room with custom options
    battle_woods: defineRoom(BattleRoom, { map: "woods" }),
  }
})
```

> **Note:**
>
> You may define the same room type multiple times with different `options`. When [Room#onCreate()](https://docs.colyseus.io/room/lifecycle.md#on-create) is called, the `options` will contain the merged values you specified on [`defineRoom()`](https://docs.colyseus.io/server.md#define-room-type) with the options provided by the client SDK.

---

#### Definition Options

The matchmaking-related options (`filterBy()`, `sortBy()`, and
`enableRealtimeListing()`) are documented in
**[Matchmaking → Matchmaking Options](https://docs.colyseus.io/matchmaker.md#matchmaking-options)**.

##### Lifecycle Events

You can listen for matchmaking events from outside the room instance scope, such as:

- `"create"` - when a room has been created
- `"dispose"` - when a room has been disposed
- `"join"` - when a client join a room
- `"leave"` - when a client leave a room (`(room, client, willDispose)`)
- `"lock"` - when a room has been locked
- `"unlock"` - when a room has been unlocked
- `"visibility-change"` - when a room's listing visibility changed (`(room, isVisible)`)
- `"metadata-change"` - when a room's metadata changed

**Usage:**

```typescript
const server = defineServer({
  rooms: {
    chat: defineRoom(ChatRoom)
      .on("create", (room) => console.log("room created:", room.roomId))
      .on("dispose", (room) => console.log("room disposed:", room.roomId))
      .on("join", (room, client) => console.log(client.sessionId, "joined", room.roomId))
      .on("leave", (room, client) => console.log(client.sessionId, "left", room.roomId))
  }
})
```

> **Warning:**
>
> Use these events for logging and monitoring purposes only. Do not manipulate a room's state through them. Use the [Room's Lifecycle Events](https://docs.colyseus.io/room/lifecycle.md) in your room class instead.

---

### Remove Room Type

Revert a room definition, making a `roomName` unavailable for matchmaking. This
method is usually not recommended but it may be useful in some scenarios.

```ts
server.removeRoomType("battle");
```

---

### Simulate Latency

Colyseus allows you to simulate latency between the server and the client. `simulateLatency()` is a convenience method for simulating clients with high latency during development.

```ts filename="server.ts"
// Make sure to never call the `simulateLatency()` method in production.
if (process.env.NODE_ENV !== "production") {

  // simulate 200ms latency between server and client.
  server.simulateLatency(200);
}
```

> **Warning:**
>
> Make sure to never enable this feature in production environments.

---

### Start Listening

Binds the [Transport](https://docs.colyseus.io/server/transport.md) layer into the specified port.

```ts {5} filename="src/app.config.ts"
import { defineServer } from "colyseus";
const server = defineServer({
    // ...
});
server.listen(2567);
```

---

### On Before Shutdown

Register a custom callback that is called **before** the Graceful Shutdown routine starts.

```ts filename="server.ts"
server.onBeforeShutdown(async () => {
    // ... custom logic
});
```

> **Note:**
>
> See [Graceful Shutdown](https://docs.colyseus.io/server/graceful-shutdown.md).

---

### On Shutdown

Register a custom callback that is called **after** the graceful shutdown is fully complete.

```typescript
server.onShutdown(async () => {
    // ... custom logic
});
```

> **Note:**
>
> See [Graceful Shutdown](https://docs.colyseus.io/server/graceful-shutdown.md).

---

### Graceful Shutdown

Triggers the Graceful Shutdown routine.

```ts filename="app.config.ts"
server.gracefullyShutdown();
```

This method is called automatically when the process receives a `SIGINT`, `SIGTERM`, or `SIGUSR2` signal, or an `uncaughtException`.

If `gracefullyShutdown: false` has been provided on `Server` constructor, you should call this method manually.

> **Note:**
>
> See [Graceful Shutdown](https://docs.colyseus.io/server/graceful-shutdown.md).

---

## Next Steps

- [Room API](https://docs.colyseus.io/room.md) - Implement rooms and handle client connections
- [State Synchronization](https://docs.colyseus.io/state.md) - Define and sync shared game state
- [Netcode](https://docs.colyseus.io/netcode.md) - Authoritative input, fixed timestep, and lag compensation
- [HTTP Routes](https://docs.colyseus.io/server/http-routes.md) - Add custom REST endpoints
- [Deployment](https://docs.colyseus.io/deployment.md) - Deploy your server to production

---
Source: https://docs.colyseus.io/server


# Debugging

- [Debug messages](#debug-messages)
- [Inspector (`--inspect` flag)](#inspector)

## Debug Messages

To enable all debug logs, run your server using the `DEBUG=colyseus:*` environment variable:

```sh filename="Terminal"
DEBUG=colyseus:* npm start
```

| Name | Description |
|------|-------------|
| `colyseus:errors` | Whenever unexpected (or expected, internally) errors happens on the backend. |
| `colyseus:matchmaking` | Whenever a room is spawned or disposed. |
| `colyseus:message` | Incoming and outgoing room messages |
| `colyseus:patch` | The number of bytes and interval between patches broadcasted to all clients. |
| `colyseus:connection` | Incoming and outgoing connections |
| `colyseus:driver` | Matchmaking driver queries and room-cache operations |
| `colyseus:presence` | Presence operations (pub/sub and data) |
| `colyseus:devmode` | Development-mode room caching and restore |

## Inspector

You can use the the built-in inspector from Node.js to debug your application.

> **Note:**
>
> See [Debugging Node.js Applications](https://nodejs.org/en/docs/inspector/) for more information.

### Remote Server Debugging

Be careful when using the inspector on production. Using memory snapshots and breakpoints will impact the experience of your users directly.

#### SSH into the Remote Server

```sh filename="Terminal (local)"
ssh root@remote.example.com
```

#### Check the PID of the Node process

```sh filename="Terminal (remote)"
ps aux | grep node
```

#### Attach the inspector on the Node.js process

The `kill` command will send the `SIGUSR1` signal to the Node.js process, which will start the inspector. It does not kill the process.

```sh filename="Terminal (remote)"
kill -usr1 PID
```

#### Create a SSH tunnel to access the inspector

From a new terminal window, create a SSH tunnel to access the inspector:

```sh filename="Terminal (local)"
ssh -L 9229:localhost:9229 root@remote.example.com
```

#### Open Chrome and access the inspector

Open Chrome and access the inspector by navigating to `chrome://inspect`. It will show the remote server as a target.

---
Source: https://docs.colyseus.io/server/debugging


# Development Mode

## How Development Mode Works

The `devMode` option has been introduced to speed up **local development** while updating your room implementation.

> **Warning:**
>
> **Do not use `devMode` in a production environment** - This feature is not optimized for a large amount of rooms. Use it for local development only.

Whenever you update your server code, all active rooms are cached locally before the server restarts. The cache includes their state and the sessionId's of previously connected clients (seat reservations). After the restart, all rooms are recreated and the cached state is restored.

Clients try to reconnect as soon as the server goes down. They keep trying a few times until they succeed, or the attempt limit is reached.

![devMode flow](https://docs.colyseus.io/server/devmode_flow.png)

> **Note:**
>
> The frontend code is **not reloaded**, only the connection is re-established. If you want HMR for both your frontend and server code from a single Vite project, see the [Vite Plugin](https://docs.colyseus.io/server/vite.md).

---

## Enabling Development Mode

The `devMode` is disabled by default and it can be enabled via [Server option](https://docs.colyseus.io/server.md#development-mode):

```ts {5} filename="app.config.ts"
import { defineServer } from "colyseus";

const server = defineServer({
    // ...
    devMode: true,
    // ...
});
```

> **Warning:**
>
> **Attention on the frontend**
>
> Upon re-establishing a connection on devMode, the `onAdd` schema callback will be triggered again on the frontend.
> Be prepared to ignore additional `onAdd` calls during development.

---

## Restoring External Data

- By default, only the `state` of the room is cached and restored when the server restarts.
- You can restore data outside the room's `state` by implementing the `onCacheRoom()` and `onRestoreRoom()` methods.
- Only JSON-serializable data is allowed.

---

#### onCacheRoom

The `onCacheRoom` will be executed before the room is cached and disposed.

```ts filename="MyRoom.ts"
export class MyRoom extends Room {
  // ...

  onCacheRoom() {
    return { foo: "bar" };
  }
}
```

---

#### onRestoreRoom

The `onRestoreRoom` will be executed after the room has been restored and the restored state is available.

The argument provided for the `onRestoreRoom` is the data previously returned by the `onCacheRoom` method.

No clients are connected yet at this point.

```ts filename="MyRoom.ts"
export class MyRoom extends Room {
  // ...

  onRestoreRoom(cachedData: any): void {
    console.log("restoring room", cachedData);

    this.state.players.forEach((player) => {
      player.method(cachedData["foo"]);
    });
  }
}
```

---
Source: https://docs.colyseus.io/server/devmode


# Driver

The driver is responsible for storing and querying room data used by the matchmaker.

When a room is created, deleted, or has its metadata updated, the driver persists this information. The matchmaker then uses it to find available rooms for players to join.

For single-process deployments, the default in-memory driver is sufficient. For multi-process or distributed deployments, you need an external driver (like Redis or PostgreSQL) so all server instances share the same room data.

## Available Drivers

- [In-Memory Driver (default)](#in-memory-driver)
- [Redis Driver](#redis-driver)
- [Database Driver (`@colyseus/database`)](#database-driver)
- [Drizzle Driver (PostgreSQL)](#drizzle-driver-postgresql)
- [MongoDB Driver](#mongodb-driver)

### In-Memory Driver

The default driver used by Colyseus is the `LocalDriver`, which stores all room data in memory. This driver is suitable for development and small-scale single-process applications.

---

### Redis Driver

The `RedisDriver` stores room data in a Redis database using [ioredis](https://github.com/redis/ioredis). This driver is suitable for large-scale multi-process applications and is recommended for production environments.

```sh npm2yarn
npm install --save @colyseus/redis-driver
```

#### Basic Usage

```ts {2,5} filename="app.config.ts"
import { defineServer } from "colyseus";
import { RedisDriver } from "@colyseus/redis-driver";

const server = defineServer({
    driver: new RedisDriver(),
    // ...
});
```

#### Connection Options

The driver accepts multiple connection formats:

```ts
// Using a connection URL
new RedisDriver("redis://username:password@localhost:6379/0")

// Using a port number (connects to localhost)
new RedisDriver(6379)

// Using RedisOptions object
new RedisDriver({
    host: "localhost",
    port: 6379,
    password: "your-password",
    db: 0,
    // ... any ioredis options
})
```

See [ioredis connection options](https://redis.github.io/ioredis/index.html#RedisOptions) for the full list of available options.

#### Redis Cluster

For high-availability setups, the driver supports Redis Cluster mode:

```ts {2,5-12} filename="app.config.ts"
import { defineServer } from "colyseus";
import { RedisDriver } from "@colyseus/redis-driver";

const server = defineServer({
    driver: new RedisDriver([
        { host: "node1.redis.example.com", port: 6379 },
        { host: "node2.redis.example.com", port: 6379 },
        { host: "node3.redis.example.com", port: 6379 },
    ], {
        // ClusterOptions (optional)
        redisOptions: { password: "your-password" }
    }),
    // ...
});
```

See [ioredis Cluster documentation](https://redis.github.io/ioredis/classes/Cluster.html) for all available cluster options.

---

### Database Driver

The `DatabaseDriver` from [`@colyseus/database`](https://docs.colyseus.io/database.md) stores room data on the same connection your `GameDatabase` already uses for players, cloud saves, and configs. One pool, one dialect (SQLite, PostgreSQL, or PGlite), no second service to run. Use it when your server has a `database:` option. This driver is a different package from the [Drizzle driver](#drizzle-driver-postgresql) below, which manages its own PostgreSQL connection and `roomcaches_v1` table.

```ts {2,8} filename="app.config.ts"
import { defineServer } from "colyseus";
import { GameDatabase, DatabaseDriver } from "@colyseus/database";

export const db = new GameDatabase({ connectionString: process.env.DATABASE_URL });

export default defineServer({
    database: db,
    driver: new DatabaseDriver(), // adopts the GameDatabase connection
});
```

Without options, the driver binds to the most recently constructed `GameDatabase`. With more than one instance in the process, pass it explicitly: `new DatabaseDriver({ database: db })`. The class is also exported from the `@colyseus/database/driver` subpath.

The driver creates its `colyseus_room_caches` table at boot (`CREATE TABLE IF NOT EXISTS`) on whichever dialect the database uses. The table is driver-owned: a server that uses `@colyseus/database` with the in-memory or Redis driver never gets it. Room fields that are not columns (`metadata` and any custom option) are stored in the `metadata` JSON column and remain queryable by `join()` / `joinOrCreate()` filters.

#### Custom Table

To add columns or change the physical name, build the table with the `roomCaches` factory (see [Customizing schemas](https://docs.colyseus.io/database/schemas.md)) and pass it as `schema`. Extra columns persist with the room and work as matchmaking filters. `schema` is the only option needed: the driver still binds to the `GameDatabase` constructed above.

**SQLite**

```ts {3,7-9,13} filename="app.config.ts"
import { defineServer } from "colyseus";
import { GameDatabase, DatabaseDriver, tables } from "@colyseus/database";
import { text } from "drizzle-orm/sqlite-core";

export const db = new GameDatabase({ connectionString: "./game.db" });

const roomCaches = tables.sqlite.roomCaches("colyseus_room_caches", {
    region: text("region"),
});

export default defineServer({
    database: db,
    driver: new DatabaseDriver({ schema: roomCaches }),
});
```

**PostgreSQL**

```ts {3,7-9,13} filename="app.config.ts"
import { defineServer } from "colyseus";
import { GameDatabase, DatabaseDriver, tables } from "@colyseus/database";
import { text } from "drizzle-orm/pg-core";

export const db = new GameDatabase({ connectionString: process.env.DATABASE_URL });

const roomCaches = tables.pg.roomCaches("colyseus_room_caches", {
    region: text("region"),
});

export default defineServer({
    database: db,
    driver: new DatabaseDriver({ schema: roomCaches }),
});
```

#### Without a `GameDatabase`

The driver also works on a Drizzle instance you manage yourself (node-sqlite, postgres-js, or PGlite). Pass the SQL flavor, since it cannot be detected from the instance. In this mode the driver closes the connection on server shutdown; set `closeOnShutdown: false` if you share the instance elsewhere:

```ts filename="app.config.ts"
import { defineServer } from "colyseus";
import { DatabaseDriver } from "@colyseus/database";
import { drizzle } from "drizzle-orm/node-sqlite";

const sdb = drizzle({ connection: { path: "game.db" } });

export default defineServer({
    driver: new DatabaseDriver({ drizzle: sdb, dialect: "sqlite" }),
});
```

---

### Drizzle Driver (PostgreSQL)

> **Note:**
>
> The Drizzle/PostgreSQL driver is experimental. Use at your own risk. Please report any issues you may find.

The `PostgresDriver` stores room data in a PostgreSQL database using [Drizzle ORM](https://orm.drizzle.team/). This driver is suitable for large-scale multi-process applications and is recommended for production environments.

```sh npm2yarn
npm install --save @colyseus/drizzle-driver
```

#### Basic Usage

The simplest way to use the driver is to set the `DATABASE_URL` environment variable:

```ts {2,5} filename="app.config.ts"
import { defineServer } from "colyseus";
import { PostgresDriver } from "@colyseus/drizzle-driver";

const server = defineServer({
    driver: new PostgresDriver(),
    // ...
});
```

The driver will automatically connect using the `DATABASE_URL` environment variable, or fall back to `postgresql://postgres:postgres@localhost:5432/postgres`.

#### Using an Existing Database Instance

If you already have a Drizzle database instance in your application, you can pass it to the driver:

```ts {2,3,6,9} filename="app.config.ts"
import { defineServer } from "colyseus";
import { drizzle } from "drizzle-orm/postgres-js";
import { PostgresDriver } from "@colyseus/drizzle-driver";

// Your existing database instance
const db = drizzle(process.env.DATABASE_URL);

const server = defineServer({
    driver: new PostgresDriver({ db }),
    // ...
});
```

> **Warning:**
>
> When providing your own database instance, you are responsible for managing the schema initialization. The `roomcaches_v1` table must exist before the driver is used.

#### Custom Schema

You can provide a custom schema if you need to modify the table structure:

```ts filename="app.config.ts"
import { defineServer } from "colyseus";
import { PostgresDriver, roomcaches } from "@colyseus/drizzle-driver";
import { pgTable, integer, boolean, timestamp, jsonb, varchar } from "drizzle-orm/pg-core";

// Custom schema with additional fields or different table name
const customRoomCaches = pgTable('my_room_caches', {
    roomId: varchar({ length: 9 }).primaryKey(),
    processId: varchar({ length: 9 }),
    name: varchar({ length: 64 }).notNull(),
    clients: integer().notNull(),
    maxClients: integer().notNull(),
    locked: boolean(),
    private: boolean(),
    metadata: jsonb(),
    publicAddress: varchar({ length: 255 }),
    createdAt: timestamp().notNull().defaultNow(),
    unlisted: boolean(),
    // Add your custom fields here
});

const server = defineServer({
    driver: new PostgresDriver({ schema: customRoomCaches }),
    // ...
});
```

#### Default Table Schema

The driver creates a `roomcaches_v1` table with the following structure:

| Column | Type | Description |
|--------|------|-------------|
| `roomId` | `varchar(9)` | Primary key, unique room identifier |
| `processId` | `varchar(9)` | ID of the process hosting the room |
| `name` | `varchar(64)` | Room type name |
| `clients` | `integer` | Current number of connected clients |
| `maxClients` | `integer` | Maximum allowed clients |
| `locked` | `boolean` | Whether the room is locked |
| `private` | `boolean` | Whether the room is private |
| `metadata` | `jsonb` | Custom room metadata |
| `publicAddress` | `varchar(255)` | Public address for the room |
| `createdAt` | `timestamp` | Room creation timestamp |
| `unlisted` | `boolean` | Whether the room is hidden from lobby/listing queries (still matched by `join()`/`joinOrCreate()`) |

---

### MongoDB Driver

The `MongooseDriver` stores room data in a MongoDB database. This driver is not actively maintained and is not recommended for production environments.

```ts {2,5} filename="app.config.ts"
import { defineServer } from "colyseus";
import { MongooseDriver } from "@colyseus/mongoose-driver";

const server = defineServer({
    driver: new MongooseDriver(/* connection URI (falls back to MONGO_URI env, then mongodb://127.0.0.1:27017/colyseus) */),
    // ...
});
```

---
Source: https://docs.colyseus.io/server/driver


# Graceful Shutdown Process

Colyseus listens for `SIGTERM`, `SIGINT`, and `SIGUSR2` signals (and `uncaughtException`) to gracefully shut down the process.

These actions will be performed, in order, before the process is killed:

    ### Server: On Before Shutdown

    The custom `server.onBeforeShutdown()` is called, if defined.

```ts filename="app.config.ts"
server.onBeforeShutdown(async () => {
    // (...) custom logic
});
```

    > **Note:**
>
> See [Server API → On Before Shutdown](https://docs.colyseus.io/server.md#on-before-shutdown)

    ### Process is excluded from matchmaking.

    The process is not going to be selected for new room creations anymore.

    > **Note:**
>
> See [Server API → Select Process ID to Create Room](https://docs.colyseus.io/server.md#select-process-id-to-create-room)

    ### Rooms are locked

    The rooms handled by this process are locked via `room.lock()`.

    > **Note:**
>
> See [Room API → Lock Room](https://docs.colyseus.io/matchmaker/visibility.md#lock-room)

    ### Room: On Before Shutdown

    All rooms `room.onBeforeShutdown()` is called.

    You may override this method to perform custom actions that will result in the room being disposed in a few minutes. By default, it simply calls `room.disconnect()`, which will trigger `room.onLeave()` for all clients, and then `room.onDispose()` almost immediately.

```ts filename="MyRoom.ts"
onBeforeShutdown() {
    //
    // Notify users that process is shutting down, they may need to save their progress and join a new room
    //
    this.broadcast("going-down", "Server is shutting down. Please save your progress and join a new room.");

    //
    // Disconnect all clients after 5 minutes
    //
    this.clock.setTimeout(() => this.disconnect(), 5 * 60 * 1000);
}
```

    > **Note:**
>
> See [Room API → On Before Shutdown](https://docs.colyseus.io/room/lifecycle.md#on-before-shutdown)

    ### (...) wait until all rooms are disposed

    The server waits for local room count to be zero before proceeding to the next step.

    > **Note:**
>
> See [Matchmaker → Get Local Room Count](https://docs.colyseus.io/matchmaker.md#get-local-ccu)

    ### Close Transport, Presence, and Driver

    The [Transport](https://docs.colyseus.io/server/transport.md), [Presence](https://docs.colyseus.io/server/presence.md), and [Driver](https://docs.colyseus.io/server/driver.md) are closed and disconnected.

    ### Server: On Shutdown

    The custom `server.onShutdown()` is called, if defined.

    At this point there is no more rooms or clients connected to the server.

```ts filename="app.config.ts"
server.onShutdown(async () => {
    // (...) custom logic
});
```

    > **Note:**
>
> See [Server API → On Shutdown](https://docs.colyseus.io/server.md#on-shutdown)

    ### Process is killed

    The process is killed after all the steps above are completed.

---

You may use `async` functions or return a `Promise` to perform asynchronous operations on `onLeave` and `onDispose` methods, as well as `server.onBeforeShutdown()` and `server.onShutdown()`.

**Returning a Promise**

By returning a `Promise`, the server will wait for them to be completed before killing the worker process.

```ts {5,17} filename="MyRoom.ts"
import { Room } from "colyseus";

class MyRoom extends Room {
    onLeave (client) {
        return new Promise((resolve, reject) => {
            doDatabaseOperation((err, data) => {
                if (err) {
                    reject(err);
                } else {
                    resolve(data);
                }
            });
        });
    }

    onDispose () {
        return new Promise((resolve, reject) => {
            doDatabaseOperation((err, data) => {
                if (err) {
                    reject(err);
                } else {
                    resolve(data);
                }
            });
        });
    }
}
```

**Using async**

The `async` keyword will make your function return a `Promise` under the hood. [Read more about Async / Await](https://basarat.gitbook.io/typescript/future-javascript/async-await).

```ts {4,8} filename="MyRoom.ts"
import { Room } from "colyseus";

class MyRoom extends Room {
    async onLeave (client) {
        await doDatabaseOperation(client);
    }

    async onDispose () {
        await removeRoomFromDatabase();
    }
}
```

---
Source: https://docs.colyseus.io/server/graceful-shutdown


# HTTP Routes

Colyseus provides two ways to add HTTP endpoints to your server:

- **API Routes** (recommended): Type-safe, with validation, middleware, frontend SDK integration, and visual testing via the [Playground](https://docs.colyseus.io/tools/playground.md#api-endpoints).
- **Express**: Use if you rely on existing Express middleware or libraries.

## API Routes

Define type-safe HTTP endpoints using `createEndpoint` and `createRouter`.

```ts filename="app.config.ts"
import { defineServer, createEndpoint, createRouter } from "colyseus";
import { z } from "zod";

const getProfile = createEndpoint("/profile/:id", {
    method: "GET",
    query: z.object({ include: z.string().optional() }),
}, async (ctx) => {
    return {
        id: ctx.params.id,
        include: ctx.query.include,
    };
});

const updateProfile = createEndpoint("/profile/:id", {
    method: "POST",
    body: z.object({ name: z.string() }),
}, async (ctx) => {
    ctx.setStatus(201);
    return { id: ctx.params.id, name: ctx.body.name };
});

const server = defineServer({
    routes: createRouter({
        getProfile,
        updateProfile,
    })
});
```

### Middleware

Use `createMiddleware` to share logic across endpoints. The returned context is merged into `ctx.context`.

```ts
import { createEndpoint, createMiddleware } from "colyseus";

const auth = createMiddleware(async (ctx) => {
    const token = ctx.headers.get("authorization");
    if (!token) throw ctx.error("UNAUTHORIZED", { message: "Missing token" });
    return { userId: "user-123" };
});

export const secureEndpoint = createEndpoint("/secure", {
    method: "GET",
    use: [auth],
}, async (ctx) => {
    ctx.setHeader("X-User", ctx.context.userId);
    ctx.setCookie("session", "abc", { httpOnly: true });
    return { ok: true, userId: ctx.context.userId };
});
```

### JWT Authentication

For JWT-based auth, [`@colyseus/auth`](https://docs.colyseus.io/auth/module.md) exports `auth.middleware()`, a middleware that verifies the `Authorization: Bearer <token>` header and exposes the decoded payload on `ctx.context.auth`. It's the canonical way to gate an endpoint behind a logged-in user.

```ts
import { createEndpoint } from "colyseus";
import { auth } from "@colyseus/auth";

export const profile = createEndpoint("/profile", {
    method: "GET",
    use: [auth.middleware()],
}, async (ctx) => {
    return { user: ctx.context.auth };
});
```

> **Note:**
>
> When [`@colyseus/database`](https://docs.colyseus.io/database.md) is in use, `auth.middleware()` is **revocation-aware** automatically. `db.auth.ban(userId)` and `db.auth.bumpTokenVersion(userId)` both invalidate live JWTs at the token layer (no per-route check needed). See [Database → Authentication](https://docs.colyseus.io/database/authentication.md).

See [Authentication → HTTP Middleware](https://docs.colyseus.io/auth/http.md) for the dual Express/`createEndpoint` modes, and [Auth Module](https://docs.colyseus.io/auth/module.md) for backend setup.

### Basic Authentication

`basicAuth` is a built-in middleware for HTTP Basic Auth. Drop it into any
endpoint's `use:` array to gate it behind the browser's native credentials
prompt.

```ts
import { createEndpoint, basicAuth } from "colyseus";

export const adminStats = createEndpoint("/admin-stats", {
    method: "GET",
    use: [ basicAuth({ users: { admin: "s3cret" } }) ],
}, async (ctx) => {
    return { onlineUsers: 123 };
});
```

A common use is protecting the [Playground](https://docs.colyseus.io/tools/playground.md) and
[Monitor](https://docs.colyseus.io/tools/monitoring.md) in production. Both accept a `use:` array:

```ts filename="app.config.ts"
import { defineServer, createRouter, basicAuth } from "colyseus";
import { playground } from "@colyseus/playground";
import { monitor } from "@colyseus/monitor";

const guard = basicAuth({ users: { admin: "s3cret" } });

const server = defineServer({
    routes: createRouter({
        ...playground({ use: [guard] }),
        ...monitor({    use: [guard] }),
    })
});
```

**Options**

| Option | Description |
|--------|-------------|
| `users` | `Record<string, string>` mapping username → password. The common static case. |
| `validate` | `(username, password) => boolean \| Promise<boolean>`: custom/DB-backed check. Takes precedence over `users`. |
| `realm` | Label shown in the browser prompt. Default `"Restricted"`. |

> **Note:**
>
> On a missing or invalid credential the middleware responds `401` with a
> `WWW-Authenticate: Basic` header, so browsers show the native login dialog.
> Passwords are compared in constant time. You must provide at least one of
> `users` or `validate`.

### Endpoint Options

`createEndpoint(path, options, handler)` accepts the following options:

| Option | Description |
|--------|-------------|
| `method` | HTTP method string or array (e.g. `"GET"` or `["GET", "POST"]`). |
| `body` | Zod schema for request body validation. Invalid bodies return 400. |
| `query` | Zod schema for query string validation. Invalid queries return 400. |
| `use` | Array of middlewares created with `createMiddleware`. |
| `requireHeaders` | When `true`, requires `headers` when calling the endpoint as a function. |
| `requireRequest` | When `true`, requires a `request` object when calling the endpoint as a function. |
| `metadata.scope` | `"rpc"` (default): available to RPC client. `"server"`: routed and callable directly, hidden from the typed RPC client. `"http"`: routed only. |
| `metadata.allowedMediaTypes` | Restricts accepted `Content-Type` values for this endpoint. |

### Handler Context

The handler signature is `async (ctx) => response`.

**Properties**

| Property | Description |
|----------|-------------|
| `ctx.request` | The raw `Request` object (when running via HTTP). |
| `ctx.headers` | `Headers` instance for the incoming request. |
| `ctx.body` | Parsed and validated request body. |
| `ctx.query` | Parsed and validated query string. |
| `ctx.params` | Route parameters (e.g. `:id`, `**:name`). |
| `ctx.method` | HTTP method (useful for multi-method endpoints). |
| `ctx.context` | Merged middleware context. |

**Methods**

| Method | Description |
|--------|-------------|
| `ctx.setStatus(status)` | Override the default success status code. |
| `ctx.error(codeOrStatus, data?, headers?)` | Throw an API error. |
| `ctx.redirect(url)` | Throw a redirect response. |
| `ctx.json(data)` | Return a JSON response. |
| `ctx.setHeader(name, value)` | Set a response header. |
| `ctx.setCookie(name, value, options?)` | Set a response cookie. |
| `ctx.getCookie(name)` | Read a request cookie. |
| `ctx.setSignedCookie(name, value, secret, options?)` | Set a signed cookie. |
| `ctx.getSignedCookie(name, secret)` | Read a signed cookie. |

---

## Express Routes

Use Express if you rely on existing Express middleware or libraries.

```ts filename="app.config.ts"
import { defineServer } from "colyseus";
import express from "express";

const server = defineServer({
    // ...
    express: (app) => {
        app.use(express.json({ limit: "100kb" }));

        app.get("/hello", (req, res) => {
            res.json({ hello: "world" });
        });

        app.post("/profile", (req, res) => {
            res.json({ received: req.body });
        });
    },
    // ...
});
```

> **Note:**
>
> See the [Express routing guide](https://expressjs.com/en/guide/routing.html) for more details.

---

## CORS

CORS is enabled by default. You can customize the headers:

```typescript
import { matchMaker } from "colyseus";

matchMaker.controller.DEFAULT_CORS_HEADERS = {
    'Access-Control-Allow-Headers': 'Origin, X-Requested-With, Content-Type, Accept, Authorization',
    'Access-Control-Allow-Methods': 'GET,HEAD,PUT,PATCH,POST,DELETE',
    'Access-Control-Allow-Credentials': 'true',
    'Access-Control-Allow-Origin': '*',
    'Access-Control-Max-Age': '2592000',
    // ...
}
```

You can also return custom CORS headers based on the request:

```typescript
import { matchMaker } from "colyseus";

matchMaker.controller.getCorsHeaders = function(requestHeaders) {
    // check for 'requestHeaders' and return custom key-value headers here.
    return {};
}
```

> **Note:**
>
> See [MDN documentation on CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) for more information.

---

## Frontend Usage

Use `client.http.*` methods to call your HTTP endpoints from the frontend.

> **Note:**
>
> See [Client SDK → HTTP Requests](https://docs.colyseus.io/sdk.md#http-requests) for the full API reference.

---
Source: https://docs.colyseus.io/server/http-routes


# Logging

Colyseus allows you to import a `logger` variable, which is customizable via its
initial settings.

```typescript
import { logger } from "@colyseus/core";
// ...

logger.debug("this is debug");
logger.info("this is information");
logger.warn("this is a warning");
logger.error("this is an error");
```

By default, the `logger` instance is just an alias to `console`. You may want to
use a different logger than `console` for a number of different reasons, such
as:

- External logging storage
- Configure different logging levels
- Customize logging output
- (...) more!

## Customizing the Logger

``` typescript
import { defineServer } from "colyseus";

const server = defineServer({
  // ...
  logger: yourPreferredLoggerInstance,
  // ...
});
```

---

## Choosing your preferred logger

The Node.js ecosystem has a few different logging solutions, each of them has its own advantages and disadvantages, such as:

- [pino](https://www.npmjs.com/package/pino)
- [Winston](https://www.npmjs.com/package/winston)
- [Bunyan](https://www.npmjs.com/package/bunyan)

---

## Using `pino` as your logger

Install the `pino` module:

```sh npm2yarn
npm install --save pino
```

Configure it in your application:

``` typescript
import { defineServer } from "colyseus";
import pino from "pino";

const server = defineServer({
  // ...
  logger: pino({
    level: "error",
    msgPrefix: '[HTTP] '
  }),
  // ...
});
```

> **Note:**
>
> See [full documentation for `pino` options](https://github.com/pinojs/pino/blob/HEAD/docs/api.md).

---

## Using `winston` as your logger

Install the `winston` module:

```sh npm2yarn
npm install --save winston
```

Configure it in your application:

``` typescript
import { defineServer } from "colyseus";
import winston from "winston";

const server = defineServer({
  // ...
  logger: winston.createLogger({
    level: 'info',
    format: winston.format.json(),
    defaultMeta: { service: 'user-service' },
    transports: [
      //
      // - Write all logs with importance level of `error` or less to `error.log`
      // - Write all logs with importance level of `info` or less to `combined.log`
      //
      new winston.transports.File({ filename: 'error.log', level: 'error' }),
      new winston.transports.File({ filename: 'combined.log' }),
    ],
  }),
  // ...
});
```

> **Note:**
>
> See [full documentation for `winston` options](https://github.com/winstonjs/winston#table-of-contents).

---
Source: https://docs.colyseus.io/server/logging


# Presence

The Presence API is responsible for inter-process communication (IPC) when scaling Colyseus across multiple processes or machines. This API provides pub/sub messaging and shared key-value storage that all server instances can access.

For single-process deployments, the default in-memory presence is sufficient. For multi-process or distributed deployments, you need an external presence (like Redis) so all server instances can communicate with each other.

## Available Presence Options

- [Local Presence (default)](#local-presence)
- [Redis Presence](#redis-presence)

---

### Local Presence

The default presence used by Colyseus is `LocalPresence`, which stores all data in memory and only works within a single process. This presence is suitable for development and small-scale single-process applications.

---

### Redis Presence

The `RedisPresence` uses Redis for pub/sub messaging and shared storage using [ioredis](https://github.com/redis/ioredis). This presence is required for multi-process or distributed deployments.

```sh npm2yarn
npm install --save @colyseus/redis-presence
```

#### Basic Usage

```ts {2,5} filename="app.config.ts"
import { defineServer } from "colyseus";
import { RedisPresence } from "@colyseus/redis-presence";

const server = defineServer({
    presence: new RedisPresence(),
    // ...
});
```

#### Connection Options

The presence accepts multiple connection formats:

```ts
// Using a connection URL
new RedisPresence("redis://username:password@localhost:6379/0")

// Using a port number (connects to localhost)
new RedisPresence(6379)

// Using RedisOptions object
new RedisPresence({
    host: "localhost",
    port: 6379,
    password: "your-password",
    db: 0,
    // ... any ioredis options
})
```

See [ioredis connection options](https://redis.github.io/ioredis/index.html#RedisOptions) for the full list of available options.

#### Redis Cluster

For high-availability setups, the presence supports Redis Cluster mode:

```ts {2,5-12} filename="app.config.ts"
import { defineServer } from "colyseus";
import { RedisPresence } from "@colyseus/redis-presence";

const server = defineServer({
    presence: new RedisPresence([
        { host: "node1.redis.example.com", port: 6379 },
        { host: "node2.redis.example.com", port: 6379 },
        { host: "node3.redis.example.com", port: 6379 },
    ], {
        // ClusterOptions (optional)
        redisOptions: { password: "your-password" }
    }),
    // ...
});
```

See [ioredis Cluster documentation](https://redis.github.io/ioredis/classes/Cluster.html) for all available cluster options.

---

## Presence API

The Presence API is based on Redis's data structures, providing key-value storage, pub/sub messaging, sets, hashes, and lists.

Every [`Room`](https://docs.colyseus.io/room.md) instance has a [`presence`](https://docs.colyseus.io/room.md#presence) property:

```ts filename="MyRoom.ts"
export class MyRoom extends Room {
    onCreate() {
        this.presence // Presence API is available 
    }
}
```

Alternatively, you can access `matchMaker.presence` from anywhere by importing the [Matchmaker API](https://docs.colyseus.io/matchmaker.md):

```ts filename="server.ts"
import { matchMaker } from "colyseus";

matchMaker.presence // full Presence API is available from here
```

---

## Pub/Sub Methods

### subscribe

Subscribes to the given `topic`. The `callback` will be triggered whenever a message is [published](#publish) on that topic.

```ts filename="MyRoom.ts"
this.presence.subscribe("global-event", (data) => {
    console.log("received message:", data);
});
```

---

### unsubscribe

Unsubscribe from a given `topic`.

**Unsubscribe from all**

Unsubscribe from all previously subscribed "global-event" callbacks.

```ts filename="MyRoom.ts"
//
this.presence.unsubscribe("global-event");
```

**Unsubscribe from specific callback**

Unsubscribe from a specific "topic" callback.

``` typescript
function callback(data) { }
this.presence.subscribe("global-event", callback);

// unsubscribing from specific callback
this.presence.unsubscribe("global-event", callback);
```

---

### publish

Posts a message to the given `topic`. All subscribers will receive the message.

```ts filename="MyRoom.ts"
this.presence.publish("global-event", { any: 1, data: 2, here: "3" });
```

---

### channels

Returns the list of active channels matching a pattern.

```ts filename="MyRoom.ts"
// Get all channels
const allChannels = await this.presence.channels();

// Get channels matching a pattern
const gameChannels = await this.presence.channels("game:*");
```

---

## Key-Value Methods

### set

Set a key to hold a string value.

```ts filename="MyRoom.ts"
await this.presence.set("global-key", "a string value");
```

---

### setex

Set a key to hold a string value with an expiration time in seconds.

```ts filename="MyRoom.ts"
// Set a key that expires after 2 minutes
await this.presence.setex("global-key", "a string value", 120);
```

---

### expire

Set a timeout on a key. After the timeout, the key will be automatically deleted.

```ts filename="MyRoom.ts"
await this.presence.set("global-key", "value");
await this.presence.expire("global-key", 60); // expires in 60 seconds
```

---

### get

Get the value of a key.

```ts filename="MyRoom.ts"
const value = await this.presence.get("global-key");
```

---

### del

Delete a key.

```ts filename="MyRoom.ts"
await this.presence.del("global-key");
```

---

### exists

Check if a key exists.

```ts filename="MyRoom.ts"
const exists = await this.presence.exists("global-key");
```

---

### incr

Increment the integer value of a key by one.

If the key does not exist, it is set to `0` before performing the operation.

```ts filename="MyRoom.ts"
await this.presence.incr("global-count");
await this.presence.incr("global-count");
await this.presence.incr("global-count");

const count = await this.presence.get("global-count");
console.log(count); // => "3"
```

---

### decr

Decrement the integer value of a key by one.

If the key does not exist, it is set to `0` before performing the operation.

```ts filename="MyRoom.ts"
await this.presence.set("global-count", "10");
await this.presence.decr("global-count");

const count = await this.presence.get("global-count");
console.log(count); // => "9"
```

---

## Set Methods

Sets are collections of unique string values.

### sadd

Add a member to a set.

If the member already exists, it is ignored. If the key does not exist, a new set is created.

```ts filename="MyRoom.ts"
await this.presence.sadd("global-set", "member-one");
await this.presence.sadd("global-set", "member-one"); // ignored, already exists
await this.presence.sadd("global-set", "member-two");
```

---

### smembers

Get all members of a set.

```ts filename="MyRoom.ts"
const members = await this.presence.smembers("global-set");
console.log(members); // => ["member-one", "member-two"]
```

---

### sismember

Check if a value is a member of a set.

Returns `1` if the element is a member, `0` if not (or if the key does not exist).

```ts filename="MyRoom.ts"
const isMember = await this.presence.sismember("global-set", "member-one");
if (isMember) {
    console.log("member-one is in the set");
}
```

---

### srem

Remove a member from a set.

```ts filename="MyRoom.ts"
await this.presence.srem("global-set", "member-one");
```

---

### scard

Get the number of members in a set (cardinality).

```ts filename="MyRoom.ts"
const count = await this.presence.scard("global-set");
console.log(count); // => 2
```

---

### sinter

Get the intersection of multiple sets.

```ts filename="MyRoom.ts"
await this.presence.sadd("set1", "a");
await this.presence.sadd("set1", "b");
await this.presence.sadd("set2", "b");
await this.presence.sadd("set2", "c");

const intersection = await this.presence.sinter("set1", "set2");
console.log(intersection); // => ["b"]
```

---

## Hash Methods

Hashes are maps of field-value pairs, useful for storing objects.

### hset

Set a field in a hash.

Returns `true` if the field is new, `false` if it was updated.

```ts filename="MyRoom.ts"
await this.presence.hset("player:123", "name", "John");
await this.presence.hset("player:123", "score", "100");
```

---

### hget

Get the value of a field in a hash.

```ts filename="MyRoom.ts"
const name = await this.presence.hget("player:123", "name");
console.log(name); // => "John"
```

---

### hgetall

Get all fields and values of a hash.

```ts filename="MyRoom.ts"
const player = await this.presence.hgetall("player:123");
console.log(player); // => { name: "John", score: "100" }
```

---

### hdel

Delete a field from a hash.

Returns `true` if the field was removed, `false` if the field did not exist.

```ts filename="MyRoom.ts"
await this.presence.hdel("player:123", "score");
```

---

### hlen

Get the number of fields in a hash.

```ts filename="MyRoom.ts"
const fieldCount = await this.presence.hlen("player:123");
console.log(fieldCount); // => 2
```

---

### hincrby

Increment the integer value of a hash field.

```ts filename="MyRoom.ts"
await this.presence.hset("player:123", "score", "100");
const newScore = await this.presence.hincrby("player:123", "score", 10);
console.log(newScore); // => 110
```

---

## List Methods

Lists are ordered collections of strings, supporting push/pop operations from both ends.

### llen

Get the length of a list.

```ts filename="MyRoom.ts"
const length = await this.presence.llen("queue");
```

---

### rpush

Append a value to the end of a list.

Returns the length of the list after the push.

```ts filename="MyRoom.ts"
await this.presence.rpush("queue", "task1");
await this.presence.rpush("queue", "task2");
```

---

### lpush

Prepend a value to the beginning of a list.

Returns the length of the list after the push.

```ts filename="MyRoom.ts"
await this.presence.lpush("queue", "urgent-task");
```

---

### rpop

Remove and return the last element of a list.

```ts filename="MyRoom.ts"
const lastItem = await this.presence.rpop("queue");
```

---

### lpop

Remove and return the first element of a list.

```ts filename="MyRoom.ts"
const firstItem = await this.presence.lpop("queue");
```

---

### brpop

Remove and return the last element of a list, or block until one is available.

The last argument is the timeout in seconds. Returns `null` if the timeout is reached.

```ts filename="MyRoom.ts"
// Block for up to 5 seconds waiting for an item
const result = await this.presence.brpop("queue", 5);
if (result) {
    const [key, value] = result;
    console.log("Got item:", value);
}
```

---
Source: https://docs.colyseus.io/server/presence


# Transport

The Transport layer is responsible for handling the low-level network communication between the Colyseus server and clients. It manages WebSocket connections, handles ping/pong heartbeats to detect disconnected clients, and provides the underlying HTTP server for the application.

## Available Transports

### Node.js Runtime

- [WebSockets (Default)](https://docs.colyseus.io/server/transport/ws.md)
- [uWebSockets.js (Native)](https://docs.colyseus.io/server/transport/uwebsockets.md)
- [WebTransport](https://docs.colyseus.io/server/transport/webtransport.md)

### Bun Runtime

- [Bun WebSockets](https://docs.colyseus.io/server/transport/bun-websockets.md)

> **Note:**
>
> Each Transport implementation has its own set of options for customization.

## Connection Lifecycle

When a client connects to the server, the transport layer:

1. Accepts the WebSocket connection
2. Starts heartbeat monitoring (ping/pong) to detect unresponsive clients
3. Parses the connection URL for `sessionId`, `roomId`, and authentication tokens
4. Forwards the connection to the appropriate room via `matchMaker`

---
Source: https://docs.colyseus.io/server/transport


# Bun WebSockets

Colyseus supports Bun's native WebSockets implementation through the `@colyseus/bun-websockets` package. This transport layer is designed for Bun's built-in HTTP server. The package also provides an Express compatibility layer for easier integration with existing codebases.

> **Warning:**
>
> Bun support on Colyseus is still experimental. Please report any issues you may find.

## Installation

```sh filename="Terminal"
bun add @colyseus/bun-websockets
```

```ts {2,6-8} filename="app.config.ts"
import { defineServer } from "colyseus";
import { BunWebSockets } from "@colyseus/bun-websockets"

const server = defineServer({
  // ...
  transport: new BunWebSockets({
    /* Bun WebSocketHandler options (e.g. maxPayloadLength, idleTimeout) */
  }),

  //
  // BunWebSockets comes with Express compatibility layer.
  //
  express: (app) => {
    // register routes
    app.get("/hello", (req, res) => {
      res.json({ hello: "world!" });
    });
  },
  // ...
});
```

## Transport options

This transport accepts Bun's own
[`WebSocketHandler`](https://bun.sh/docs/api/websockets) options, plus the
option below.

### `options.beforeUpgrade`

Runs before the WebSocket handshake, while the connection is still a plain HTTP
request.

```ts
beforeUpgrade?: (request: Request, context: AuthContext) => Response | void | Promise<Response | void>;
```

The callback receives the upgrade request as a standard
[`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request), and the
same `context` object [onAuth](https://docs.colyseus.io/auth/room.md#onauth-context) receives: `token`,
`headers`, and `ip`. The context is read-only here, and changes to it do not
carry over to `onAuth`.

Return a
[`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) to answer
the request without upgrading, or nothing to accept the handshake. The callback
may be `async`, and the handshake waits for it to resolve.

A callback that throws answers `500 Internal Server Error`, and the connection is
not upgraded.

---
Source: https://docs.colyseus.io/server/transport/bun-websockets


# uWebSockets.js

The uWebSockets.js generally performs better than the default WebSockets implementation, and is capable of handling more connections while using less resources. This transport is recommended for production environments.

> **Note:**
>
> The underlying library [`uNetworking/uWebSockets.js`](https://github.com/uNetworking/uWebSockets.js) is a C++ implementation of WebSockets. It benchmarks at least [10x Socket.IO](https://unetworkingab.medium.com/100k-secure-websockets-with-raspberry-pi-4-1ba5d2127a23) and [8.5x Fastify](https://unetworkingab.medium.com/serving-100k-requests-second-from-a-fanless-raspberry-pi-4-over-ethernet-fdd2c2e05a1e). It also forms the [core of Bun](https://x.com/uNetworkingAB/status/1810380862556397887), and is the fastest standards-compliant web server in the TechEmpower ([not endorsed](https://x.com/uNetworkingAB/status/1811425564764610926)) benchmarks.

## Installation

```sh npm2yarn
npm install --save @colyseus/uwebsockets-transport@^0.18.0
```

To use the `express:` option with this transport, also install the optional [`uwebsockets-express`](https://github.com/colyseus/uWebSockets-express) compatibility layer (`^2.0.1` for Express v5, `^1.4.1` for Express v4):

```sh npm2yarn
npm install --save uwebsockets-express
```

**Usage**

```ts {1,6-10} filename="app.config.ts"
import { uWebSocketsTransport } from "@colyseus/uwebsockets-transport"
import { defineServer } from "colyseus";

const server = defineServer({
  // ...
  transport: new uWebSocketsTransport({
    /* transport options */
  }, {
    /* ssl options */
  }),

  //
  // bind express routes
  //
  express: (app) => {

    app.get("/hello", (req, res) => {
      res.json({ hello: "world!" });
    });

  },
  // ...
});
```

## Transport options

### `options.maxPayloadLength`
Maximum length of received message. If a client tries to send you a message larger than this, the connection is immediately closed.

Default: `4096`

### `options.idleTimeout`
Maximum amount of seconds that may pass without sending or getting a message. Connection is closed if this timeout passes. Resolution (granularity) for timeouts are typically 4 seconds, rounded to closest. Disable by using `0`.

Default: `120`

### `options.sendPingsAutomatically`

Whether or not we should automatically send pings to uphold a stable connection given `idleTimeout`.

Default: `true`

### `options.compression`

What permessage-deflate compression to use. `uWS.DISABLED`, `uWS.SHARED_COMPRESSOR` or any of the `uWS.DEDICATED_COMPRESSOR_xxxKB`.

Default: `uWS.DISABLED`

### `options.maxBackpressure`

Maximum length of allowed backpressure per socket when publishing or sending messages. Slow receivers with too high backpressure will be skipped until they catch up or timeout.

Default: `1024 * 1024`

### `options.beforeUpgrade`

Runs before the WebSocket handshake, while the connection is still a plain HTTP
request.

```ts
beforeUpgrade?: (request: Request, context: AuthContext) => Response | void | Promise<Response | void>;
```

The callback receives the upgrade request as a standard
[`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request), and the
same `context` object [onAuth](https://docs.colyseus.io/auth/room.md#onauth-context) receives: `token`,
`headers`, and `ip`. The context is read-only here, and changes to it do not
carry over to `onAuth`.

Return a
[`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) to answer
the request without upgrading, or nothing to accept the handshake. The callback
may be `async`, and the handshake waits for it to resolve.

A callback that throws answers `500 Internal Server Error`, and the connection is
not upgraded.

## SSL options

### `options.key_file_name`

Path to the SSL key file. (for SSL termination through the Node.js application.)

### `options.cert_file_name`

Path to the SSL certificate file. (for SSL termination through the Node.js application.)

### `options.passphrase`

Password for the SSL file. (for SSL termination through the Node.js application.)

---

## Overriding the uWebSockets.js version

The `@colyseus/uwebsockets-transport` package ships with a specific version of `uWebSockets.js` as a dependency. You may need a different version, for example to pick up a bug fix or to match a specific platform requirement. In that case, override it directly from your project's `package.json`.

**npm**

Use the [`overrides`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#overrides) field:
```json filename="package.json"
{
  "overrides": {
    "uWebSockets.js": "uNetworking/uWebSockets.js#v20.51.0"
  }
}
```

**yarn**

Use the [`resolutions`](https://classic.yarnpkg.com/lang/en/docs/selective-version-resolutions/) field:
```json filename="package.json"
{
  "resolutions": {
    "uWebSockets.js": "uNetworking/uWebSockets.js#v20.51.0"
  }
}
```

**pnpm**

Use the [`pnpm.overrides`](https://pnpm.io/package_json#pnpmoverrides) field:
```json filename="package.json"
{
  "pnpm": {
    "overrides": {
      "uWebSockets.js": "uNetworking/uWebSockets.js#v20.51.0"
    }
  }
}
```

After updating `package.json`, remove your `node_modules` directory and reinstall dependencies for the override to take effect.

> **Warning:**
>
> Check the [uWebSockets.js releases](https://github.com/uNetworking/uWebSockets.js/releases) for available versions.

---

## Troubleshooting

### 431 Request Header Fields Too Large

The maximum header size is 4 KiB by default. If you need to increase the maximum header size, you can use the `UWS_HTTP_MAX_HEADERS_SIZE` environment variable:

```bash
UWS_HTTP_MAX_HEADERS_SIZE=32768
```

---
Source: https://docs.colyseus.io/server/transport/uwebsockets


# WebTransport

WebTransport is a new transport protocol that allows for low-latency, bidirectional, and multiplexed communication between a client and a server. The protocol is built on top of HTTP/3 and QUIC, which in turn is built on UDP instead of TCP.

> **Warning:**
>
> **Experimental** - This WebTransport implementation hasn't been battle tested. Please report any issues you may find - WebTransport is still an emerging technology and [not widely available yet](https://caniuse.com/webtransport).

> **Note:**
>
> The underlying library is [`@fails-components/webtransport`](https://github.com/fails-components/webtransport) - a backend implementation of HTTP3/WebTransport.

## Unreliable delivery

WebTransport is the only Colyseus transport with a real **unreliable** channel: QUIC datagrams, delivered at most once and never retransmitted. Two features depend on it, and both are experimental alongside it:

- [`.unreliable()` schema fields](https://docs.colyseus.io/state/schema.md#delivery-modifiers): a value replaced every tick ships on the datagram channel. A dropped packet then costs nothing, instead of stalling the ordered stream behind a retransmit.
- [Unreliable input](https://docs.colyseus.io/netcode/recipes.md#unreliable-input-over-webtransport): `room.input({ mode: "unreliable" })`, where each packet carries the last few inputs as redundancy against drops.

Every WebSocket transport lacks that channel. `.unreliable()` fields then stop updating after the full state sync, with a warning logged once. Unreliable input falls back to the reliable channel, its redundancy wasted. Client-side WebTransport support is currently limited to the JavaScript/TypeScript SDK.

```sh npm2yarn
npm install --save @colyseus/h3-transport
```

**Usage**

```ts {2-3,9-13} filename="app.config.ts"
import express from "express";
import { defineServer } from "colyseus";
import { H3Transport } from "@colyseus/h3-transport"

const app = express();
app.get("/hello", (req, res) => {
  res.json({ hello: "world!" });
});

const server = defineServer({
  // ...
  transport: new H3Transport({
    app, // required: H3Transport serves HTTP through this Express app
    /* other H3Transport options */
  }),
  // ...
});
```

> **Warning:**
>
> Pass your Express app via the transport's `app` option. The `defineServer({ express })` callback is **not** supported by `H3Transport`: it is silently ignored.

## Available options

- `app`: **(required)** The Express app served over HTTP/3.
- `cert`: Certificate contents (cert.pem)
- `key`: Private key contents (key.pem)
- `secret`: (?)
- `server`: The `http.Server` instance to be used.
- `localProxy`: (optional) Fallback every URL through the this local proxy.

> **Note:**
>
> `beforeUpgrade`, available on the WebSocket transports, is not supported here.
> WebTransport sessions arrive already established, so there is no upgrade
> handshake to intercept. `H3Transport` warns and ignores the option.

---
Source: https://docs.colyseus.io/server/transport/webtransport


# WebSocket Transport (via `ws`)

The `WebSocketTransport` with its default options is going to be used automatically if no `transport` is provided. You may customize its options by providing a custom `WebSocketTransport` instance.

> **Note:**
>
> The underlying library is [`websockets/ws`](https://github.com/websockets/ws). The `ws` package is a fast and thoroughly tested WebSocket client and server for Node.js.

## Example

```ts {2,7-11} filename="app.config.ts"
import { defineServer } from "colyseus";
import { WebSocketTransport } from "@colyseus/ws-transport"

const server = defineServer({
  // ...

  transport: new WebSocketTransport({
    pingInterval: 6000,
    pingMaxRetries: 4,
    maxPayload: 1024 * 1024 * 1, // 1MB Max Payload
  }),

  // ...
});
```

---

## Available options

### `options.server`

A Node.js http server instance to re-use for the WebSocket server. Useful when you'd like to use Express along with Colyseus.

**Example**

```ts {3,8-10} filename="app.config.ts"
import { createServer } from "http";
import { defineServer } from "@colyseus/core";
import { WebSocketTransport } from "@colyseus/ws-transport"

const httpServer = createServer(); // create the http server manually

const server = defineServer({
  transport: new WebSocketTransport({
    server: httpServer // provide the custom server for `WebSocketTransport`
  })
});
```

**Example + Express**

```ts {1,4,6-7,10-12} filename="server.ts"
import express from "express";
import { createServer } from "http";
import { defineServer } from "@colyseus/core";
import { WebSocketTransport } from "@colyseus/ws-transport"

const app = express();
const httpServer = createServer(app); // create the http server manually

const server = defineServer({
  transport: new WebSocketTransport({
    server: httpServer // provide the custom server for `WebSocketTransport`
  })
});
```

By not providing this option, an http server is going to be created automatically for you.

---

### `options.pingInterval`

Number of milliseconds for the server to "ping" the clients.

The clients are going to be forcibly disconnected if they can't respond after [pingMaxRetries](#optionspingmaxretries) retries.

Default: `3000`

---

### `options.pingMaxRetries`

Maximum allowed number of pings without a response.

Default: `2`

---

### `options.maxPayload`

Maximum payload clients can send per message to the server.

Default: `4096` (4kb)

---

### `options.perMessageDeflate`

Enable/disable per-message deflate compression. Disabling this can reduce CPU usage and latency at the cost of increased bandwidth.

Default: `false`

---

### `options.beforeUpgrade`

Runs before the WebSocket handshake, while the connection is still a plain HTTP
request.

```ts
beforeUpgrade?: (request: Request, context: AuthContext) => Response | void | Promise<Response | void>;
```

The callback receives the upgrade request as a standard
[`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request), and the
same `context` object [onAuth](https://docs.colyseus.io/auth/room.md#onauth-context) receives: `token`,
`headers`, and `ip`. The context is read-only here, and changes to it do not
carry over to `onAuth`.

Return a
[`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) to answer
the request without upgrading, or nothing to accept the handshake. The callback
may be `async`, and the handshake waits for it to resolve.

A callback that throws answers `500 Internal Server Error`, and the connection is
not upgraded.

[verifyClient](#optionsverifyclient) covers the accept-or-reject case on this
transport. `beforeUpgrade` answers with a full `Response`, and behaves the same
way on every WebSocket transport.

---

### `options.verifyClient`

This method happens before WebSocket handshake. If `verifyClient` is not set
then the handshake is automatically accepted.

- `info` (Object)
    - `origin` (String) The value in the Origin header indicated by the client.
    - `req` (http.IncomingMessage) The client HTTP GET request.
    - `secure` (Boolean) `true` if `req.connection.authorized` or `req.connection.encrypted` is set.

- `next` (Function) A callback that must be called by the user upon inspection of the `info` fields. Arguments in this callback are:
    - `result` (Boolean) Whether or not to accept the handshake.
    - `code` (Number) When `result` is `false` this field determines the HTTP error status code to be sent to the client.
    - `name` (String) When `result` is `false` this field determines the HTTP reason phrase.

---

## Troubleshooting

### 431 Request Header Fields Too Large

The maximum header size is 16 KiB by default. If you need to increase the maximum header size, you can use the `NODE_OPTIONS` environment variable:

```bash
NODE_OPTIONS="--max-http-header-size=32768"
```

> **Note:**
>
> See [Node.js documentation on --max-http-header-size](https://nodejs.org/api/cli.html#--max-http-header-sizesize) for more information.

---
Source: https://docs.colyseus.io/server/transport/ws


# Vite Plugin

The Colyseus Vite plugin runs your game server **inside** Vite's dev server using Vite's [Environment API](https://vite.dev/guide/api-environment). A single `vite` process serves your frontend and hosts the Colyseus server. [Hot Module Replacement](https://vite.dev/guide/features#hot-module-replacement) (HMR) covers both client components **and** server-side room definitions, with no process restart between edits.

It also drives the production build: `vite build` emits your static client and a standalone server bundle.

## Requirements

- A Vite project (`vite >= 6.0.0`).
- The `colyseus` package: the plugin ships with it under the `colyseus/vite` subpath.

## Setup

Add the `colyseus()` plugin to your Vite config, alongside any frontend plugins (such as `@vitejs/plugin-react`):

```ts {3,8-10} filename="vite.config.ts"
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { colyseus } from 'colyseus/vite';

export default defineConfig({
  plugins: [
    react(),
    colyseus({
      serverEntry: '/src/server/index.ts',
    }),
  ],
});
```

The `serverEntry` file must export your server configuration as `server` (from [`defineServer()`](https://docs.colyseus.io/server.md)) or a `rooms` map. A default export of `{ server }` / `{ rooms }` also works.

```ts filename="src/server/index.ts"
import { defineServer, defineRoom, createRouter, createEndpoint } from "colyseus";
import { MyRoom } from "./MyRoom.ts";

export const server = defineServer({
  rooms: {
    my_room: defineRoom(MyRoom),
  },

  // Type-safe HTTP routes, hot-swapped on reload
  routes: createRouter({
    hello: createEndpoint("/hello", { method: "GET" }, async () => {
      return { message: "Hello world!" };
    }),
  }),

  // Express middleware: set up once, persists across reloads
  express: (app) => {
    app.get('/express-hello', (_req, res) => {
      res.json({ message: 'Hello from Express!' });
    });
  },
});
```

Start everything with the usual Vite command:

```bash
npm run dev
```

Editing `MyRoom.ts` reloads the server in place; editing your frontend reloads the browser, both without restarting the process. The Colyseus server attaches to Vite's own HTTP server, so your client and server share a single origin and port (no dev proxy required).

## Options

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `serverEntry` | `string` | *(required)* | Path to the module exporting `server` (or `rooms`). |
| `port` | `number` | `2567` | Port the **production** server listens on. Dev mode reuses Vite's port. |
| `serveClient` | `boolean` | `false` | In the production build, serve the built client via `express.static()` with an SPA fallback to `index.html`. No effect in dev. |
| `quiet` | `boolean` | `false` | Suppress the plugin's reload/room logs. |
| `httpServer` | `http.Server` | — | Required only when running Vite in [middleware mode](#middleware-mode). |
| `loadWsTransport` | `() => Promise<…>` | — | Provide a custom WebSocket transport loader. Defaults to `@colyseus/ws-transport`. |

## How server HMR works

The plugin enables Colyseus [Development Mode](https://docs.colyseus.io/server/devmode.md) internally. When you save a server file:

1. The server module is re-imported, picking up your new code.
2. HTTP routes and room definitions are swapped for the new ones.
3. Active rooms are cached, disposed, and restored: state and seat reservations are preserved, and connected clients reconnect automatically.

Because this reuses the dev-mode machinery, the same hooks and caveats apply:

- Implement [`onCacheRoom()` / `onRestoreRoom()`](https://docs.colyseus.io/server/devmode.md#restoring-external-data) to preserve data held outside the room `state`.
- On the frontend, the `onAdd` schema callbacks fire again after a reload. Be ready to ignore duplicate calls during development.

> **Warning:**
>
> Like `devMode`, this is for **local development only**. The production build (below) runs a normal Colyseus server with HMR disabled.

## Production build

```bash
vite build --app
```

This produces:

- `dist/client/`: your static frontend assets.
- `dist/server/server.mjs`: a standalone server that imports your entry and calls `server.listen()`.

Run it with Node:

```bash
node dist/server/server.mjs
```

To have the server also serve the built client (single deployable), enable `serveClient`:

```ts {4} filename="vite.config.ts"
colyseus({
  serverEntry: '/src/server/index.ts',
  port: 2567,
  serveClient: true,
})
```

With `serveClient`, the production server mounts `dist/client/` via `express.static()` and adds an SPA fallback that returns `index.html` for unmatched `GET` requests.

## Middleware mode

In standalone dev mode the plugin attaches the WebSocket transport to Vite's own HTTP server. When you run Vite in [middleware mode](https://vite.dev/guide/ssr) (embedding it inside your own Express/HTTP server), that server owns the socket. You must pass it explicitly:

```ts
colyseus({
  serverEntry: '/src/server/index.ts',
  httpServer: myHttpServer,
})
```

## Using Nitro

Frameworks such as [TanStack Start](https://tanstack.com/start) deploy through [Nitro](https://nitro.build)'s Vite plugin. The Colyseus plugin runs next to it, in development and in production. This setup needs `colyseus` 0.18.6 or later.

> **Note:**
>
> Earlier versions fail to load the Colyseus server in development, with `TypeError: Cannot read properties of undefined (reading 'import')`. Their production build also omits `dist/server/server.mjs`.

> **Warning:**
>
> Colyseus with Nitro may not work yet on every production target that Nitro supports. The examples below were tested with Nitro's Node.js presets, `node-server` and `node-middleware`. If you deploy to another target, feedback is welcome via [GitHub Issues](https://github.com/colyseus/colyseus/issues).

### Plugin order

List `colyseus()` before `nitro()`. Nitro's dev server handles every request that reaches it, including the matchmaker routes. If Nitro comes first, those requests return a 404 from your app, and joining a room fails. Your rooms still show as defined in the terminal, so check the plugin order first.

```ts {5,9} filename="vite.config.ts"
import { defineConfig } from 'vite';
import { tanstackStart } from '@tanstack/react-start/plugin/vite';
import { nitro } from 'nitro/vite';
import viteReact from '@vitejs/plugin-react';
import { colyseus } from 'colyseus/vite';

export default defineConfig({
  plugins: [
    colyseus({ serverEntry: '/src/server/index.ts' }),
    tanstackStart(),
    nitro(),
    viteReact(),
  ],
});
```

In development, your pages, the matchmaker and room connections share Vite's port.

### Deploying as two processes

`vite build` writes two outputs: the Nitro app in `.output/`, and the Colyseus server in `dist/server/server.mjs`. Run each one as its own process:

```bash
node .output/server/index.mjs   # Nitro, port 3000
node dist/server/server.mjs     # Colyseus, port 2567
```

The two processes listen on different ports. Point your frontend's `Client` at the Colyseus port, which differs from the port it uses in development.

### Deploying as one process

To serve everything from the Colyseus server, build Nitro as a Node middleware instead of a standalone server:

```ts filename="vite.config.ts"
nitro({ preset: 'node-middleware', serveStatic: true }),
```

The `node-middleware` preset makes `.output/server/index.mjs` export a `middleware` function instead of starting a server. The `serveStatic` option makes that middleware serve your frontend's built assets too. Without it, pages render but their scripts return 404.

Mount the middleware from the `express` option of your server entry:

```ts {1-3,11-18} filename="src/server/index.ts"
import { resolve } from "node:path";
import { pathToFileURL } from "node:url";
import { defineServer, defineRoom, isDevMode } from "colyseus";
import { MyRoom } from "./MyRoom.ts";

export const server = defineServer({
  rooms: {
    my_room: defineRoom(MyRoom),
  },

  express: async (app) => {
    // In development, Vite serves the Nitro app itself.
    if (isDevMode) { return; }

    const nitroEntry = pathToFileURL(resolve(".output/server/index.mjs")).href;
    const { middleware } = await import(/* @vite-ignore */ nitroEntry);
    app.use(middleware);
  },
});
```

Colyseus handles its own HTTP routes and WebSocket connections first. Every other request reaches Nitro.

Start the server from your project root. The Nitro path resolves against the working directory, so the server fails to start from anywhere else:

```bash
node dist/server/server.mjs
```

- Leave `serveClient` off. Nitro serves your frontend, so `dist/client/` is never built. With `serveClient` on, every page returns a 404.
- Keep the `isDevMode` check. The plugin also calls `express` in development, before `.output/` exists. Without the check, development logs a misleading `Express not available` warning.

---
Source: https://docs.colyseus.io/server/vite


# Sponsors

Colyseus is an independent project: no venture capital, no corporate parent. One
developer maintains all of it full-time, from the server and the schema
serializer to the SDKs, the documentation, and the demos.

The framework is MIT licensed and free to self-host, and it stays that way. No
paid plan, no gated feature. Your support is simply what buys the time to keep
all of it moving.

Colyseus is proudly sponsored by these amazing companies and people

---

[![Sponsors](https://cdn.jsdelivr.net/gh/colyseus/.github@main/sponsorkit/sponsors.svg)](https://cdn.jsdelivr.net/gh/colyseus/.github@main/sponsorkit/sponsors.svg)

---

## Ways to support Colyseus

There are two ways to help, and both mean a lot

### GitHub Sponsors

The most direct one: sponsor monthly or once, at
[github.com/sponsors/endel](https://github.com/sponsors/endel). Monthly sponsors
get the source code of the [premium demos](https://docs.colyseus.io/learn.md#premium-demos) from $5 up.
Higher tiers add priority on bug fixes, email support, and a logo listing.

### Colyseus Merch

Want something in return? The [Colyseus Shop](https://shop.colyseus.io/) has
t-shirts, hoodies, hats, mugs, and stickers, and it ships worldwide. Every order
funds the work, and you get to look cool doing it. 😎

- [Become a sponsor](https://github.com/sponsors/endel)
- [Visit the shop](https://shop.colyseus.io/)

---
Source: https://docs.colyseus.io/sponsors


# State Synchronization

- [Schema Definition](https://docs.colyseus.io/state/schema.md)
- [State View](https://docs.colyseus.io/state/view.md)
- [State Sync Callbacks](https://docs.colyseus.io/state/callbacks.md)
- [Optimizing State](https://docs.colyseus.io/state/optimization.md)

## Overview

Colyseus uses a schema-based approach to define the state of a room. The server is responsible for mutating the state, and the client listens for state changes to keep the user interface in sync.

- The room's state is defined using `schema()` from `@colyseus/schema`. Only the server can directly mutate the state.
- Clients send messages to the server to request state changes. Your room code processes these requests and updates the state.
- Colyseus optimizes performance and bandwidth by tracking property-level changes. Only the latest mutation of each property is queued and sent to clients during the [patchRate](https://docs.colyseus.io/room.md#configuration-properties) interval.
- On the frontend, you listen for state changes to keep the user interface in sync.

	### Backend: Define your state structures

    Define your state structures using `schema()` and `t.*` field builders from `@colyseus/schema`, or the classic [`@type()` decorator style](https://docs.colyseus.io/state/schema/decorators.md):

    **Schema Builder**

```ts filename="src/rooms/MyState.ts"
import { schema, t, type SchemaType } from "@colyseus/schema";

export const Player = schema({
    name: t.string(),
    x: t.number(),
    y: t.number(),
}, "Player");
export type Player = SchemaType<typeof Player>;

export const MyState = schema({
    players: t.map(Player),
}, "MyState");
export type MyState = SchemaType<typeof MyState>;
```

        The `type` aliases are TypeScript-only sugar: `schema()` returns a value, and `SchemaType` derives the instance type under the same name. Plain JavaScript users omit those lines.

**Decorators**

```ts filename="src/rooms/MyState.ts"
import { Schema, MapSchema, type } from "@colyseus/schema";

export class Player extends Schema {
    @type("string") name: string;
    @type("number") x: number;
    @type("number") y: number;
}

export class MyState extends Schema {
    @type({ map: Player }) players = new MapSchema<Player>();
}
```

        The decorator style requires two `tsconfig.json` flags. See [Decorators → TypeScript Config](https://docs.colyseus.io/state/schema/decorators.md#typescript-config).

    ### ... assign and mutate the state

    Setting up the state in your room class and mutating it when clients join or leave the room:

    **TypeScript**

```ts {2,5,8,11} filename="src/rooms/MyRoom.ts"
import { Room } from "colyseus";
import { MyState, Player } from "./MyState";

export class MyRoom extends Room<MyState> {
    state = new MyState();

    onJoin (client, options) {
        this.state.players.set(client.sessionId, new Player());
    }
    onLeave (client) {
        this.state.players.delete(client.sessionId);
    }
}
```

**JavaScript**

```js {2,5,8,11} filename="src/rooms/MyRoom.js"
import { Room } from "colyseus";
import { MyState, Player } from "./MyState";

export class MyRoom extends Room {
    state = new MyState();

    onJoin (client, options) {
        this.state.players.set(client.sessionId, new Player());
    }
    onLeave (client) {
        this.state.players.delete(client.sessionId);
    }
}
```

    ### Frontend: Full state received on join

    Clients receive the full state when they join the room. Whenever a mutation occurs in the backend, the state is automatically synchronized with all clients in the room.

    Below is an example of how to listen to player additions and removals on the frontend:

```js {9-11,14-16} copy filename="client.js"
import { Client, Callbacks } from "@colyseus/sdk";

// ...
const client = new Client('http://localhost:2567');
const room = await client.joinOrCreate('my_room', {/* */});
const callbacks = Callbacks.get(room);

// Listen to 'player' instance additions
callbacks.onAdd("players", (player, sessionId) => {
    console.log('Player joined:', player);
});

// Listen to 'player' instance removals
callbacks.onRemove("players", (player, sessionId) => {
    console.log('Player left:', player);
});
```

    ### ... request the server to mutate the state

    The frontend is not capable of mutating the state directly. Instead, it sends messages to the server to request state changes.

```js {4} filename="client.js"
import { Client, Callbacks } from '@colyseus/sdk';

// ...
room.send("set-position", { x: 16, y: 16 });
```

    ### Backend: Listen to client messages

    The backend processes the client messages and mutates the state. Colyseus will take care of synchronizing the state with all clients in the room.

```ts {6-11} filename="src/rooms/MyRoom.ts"
// ...
export class MyRoom extends Room<MyState> {
    state = new MyState();

    messages = {
        "set-position": (client, data) => {
            const player = this.state.players.get(client.sessionId);
            player.x = data.x;
            player.y = data.y;
        }
    }
    // ...
```

    ### Frontend: Listen to state changes

    The client listens to state changes on the instance directly to keep the user interface in sync.

    **Using .onChange() on an instance**

```js {10-12} filename="client.js"
import { Client, Callbacks } from "@colyseus/sdk";
// ...
const client = new Client('http://localhost:2567');
const room = await client.joinOrCreate('my_room', {/* */});
const callbacks = Callbacks.get(room);

// Listen to 'player' instance additions
callbacks.onAdd("players", (player, sessionId) => {
    // Listening for any change on the player instance
    callbacks.onChange(player, () => {
        console.log('Player changed:', player.x, player.y);
    });
});
```

**Using .listen() on a property**

```js {10-15} filename="client.js"
import { Client, Callbacks } from "@colyseus/sdk";
// ...
const client = new Client('http://localhost:2567');
const room = await client.joinOrCreate('my_room', {/* */});
const callbacks = Callbacks.get(room);

// Listen to 'player' instance additions
callbacks.onAdd("players", (player, sessionId) => {
    // Listen to property changes directly
    callbacks.listen(player, "x", (x, prevX) => {
        console.log('Player changed:', x, "from", prevX);
    });
    callbacks.listen(player, "y", (y, prevY) => {
        console.log('Player changed:', y, "from", prevY);
    });
});
```

---

## Limitations

- Each `Schema` structure can hold up to `63` serialized fields. If you need more fields, use nested `Schema` structures.
    - Inherited fields count toward the limit, so check the parent class too. Defining the 64th field throws where the class is defined.
- `NaN` is encoded as `0`. `Infinity` is encoded as the largest safe integer, which costs 9 bytes.
- `null` strings are encoded as `""`.
- Multi-dimensional arrays are not supported. [See how to use 1D arrays as multi-dimensional](https://softwareengineering.stackexchange.com/questions/212808/treating-a-1d-data-structure-as-2d-grid/212813#212813)
- `@colyseus/schema` encoding order is based on field definition order: the order fields appear in the `schema()` object literal (or, for decorators, declaration order).
    - Both encoder (server) and decoder (client) must have the same schema definition.
    - The order of the fields must be the same.

For what a patch costs in bytes and how to make it smaller, see [Optimizing State](https://docs.colyseus.io/state/optimization.md).

---

## How does it work, internally?

- **Handshake**: When a client joins a room, the server sends all the types that compose the room's state, followed by the full state.
    - Handshake is skipped on automatic reconnections, OR when the client has provided the concrete state classes when joining the room.
- **Enqueueing changes**: When the server mutates the state, it tracks which properties have changed since the last state synchronization, per `Schema` instance. Each `Schema` instance holds a `ChangeTree` object that tracks its changes.
- **Sending changes**: The server encodes only the changed properties and sends them to the client during the [patchRate](https://docs.colyseus.io/room.md#configuration-properties) interval.
- **`refId`**: Each `Schema` instance has a unique `refId` that is used to identify the instance across the network. The `refId` is how Colyseus knows which instance has been added, removed, or updated.
- **Decoding changes**: When the client receives the state changes, it decodes them and applies them to each `Schema` instance based on the `refId`. Decoding triggers the `onChange`, `listen`, and `onAdd`/`onRemove` callbacks on the frontend.

---

## Troubleshooting

The `schema()` builder needs no compiler configuration. If you use the [`@type()` decorator style](https://docs.colyseus.io/state/schema/decorators.md), two `tsconfig.json` flags are required. See [Decorators → TypeScript Config](https://docs.colyseus.io/state/schema/decorators.md#typescript-config).

---

## Next Steps

- [Schema Definition](https://docs.colyseus.io/state/schema.md) - Complete reference for defining state structures
- [Decorators (@type)](https://docs.colyseus.io/state/schema/decorators.md) - The classic decorator-based definition style
- [State Sync Callbacks](https://docs.colyseus.io/state/callbacks.md) - All methods for listening to state changes
- [State View](https://docs.colyseus.io/state/view.md) - Control which parts of state each client can see
- [Optimizing State](https://docs.colyseus.io/state/optimization.md) - What a patch costs, and how to make it smaller

---
Source: https://docs.colyseus.io/state


# Advanced Schema Customization

Since `@colyseus/schema` 3.0, experimental APIs are available allowing you to
customize:

- [Custom types and encoding](#custom-types-and-encoding)
- [Change tracking](#change-tracking)
- [Byte-level encoding](#byte-level-encoding)
- [Byte-level decoding](#byte-level-decoding)
- [Encoding non-`Schema` structures](#encoding-non-schema-structures)
- [Instance pooling](#instance-pooling)

## Custom types and encoding

You can define custom types to encode and decode your data structures.

> **Note:**
>
> Custom type identifiers currently require the decorator style. See [Decorators](https://docs.colyseus.io/state/schema/decorators.md#typescript-config) for the required tsconfig flags.

```typescript
import { Schema, defineCustomTypes } from "@colyseus/schema";
import { TextDecoder, TextEncoder } from "util";

const _encoder = new TextEncoder();
const _decoder = new TextDecoder();

const customType = defineCustomTypes({
        cstring: {
            encode: (bytes, value, it) => {
                value ??= "";
                value += "\x00";
                if (bytes instanceof Uint8Array) {
                    it.offset += _encoder.encodeInto(value, bytes.subarray(it.offset)).written;
                } else {
                    const encoded = _encoder.encode(value);
                    const len = encoded.length;
                    for (let i = 0; i < len; ++i) bytes[it.offset++] = encoded[i]; // could probably also figure out if bytes has .set
                }
            },
            decode: (bytes, it) => {
                // should short circuit if buffer length can't be determined for some reason so we don't just infinitely loop
                const len = (bytes as Buffer | ArrayBuffer).byteLength ?? (bytes as number[]).length;
                if (len === undefined) throw TypeError("Unable to determine length of 'BufferLike' " + bytes.toString());
                let start = it.offset;
                while (it.offset < len && bytes[it.offset++] !== 0x00) { }; // nop, fast search for terminator
                return _decoder.decode(new Uint8Array((bytes as Buffer | Uint8Array)?.subarray?.(start, it.offset - 1) ?? bytes.slice(start, it.offset - 1))); // ignore terminator
            }
        },
});

class MyState extends Schema {
    @customType("cstring") message: string;
}
```

See [CustomPrimitiveTypes.test.ts](https://github.com/colyseus/schema/blob/master/test/CustomPrimitiveTypes.test.ts) for more examples, which includes:

| Type | Description | Limitation | Size (Bytes) |
|------|-------------|------------|--------------|
| `"varInt"` | signed variable-length encoded integer (`number` type) | -2147483648 to 2147483647 (safely) | 1 - 8 (depending on bits used) |
| `"varUint"` | unsigned variable-length encoded integer (`number` type) | 0 to 4294967296 (safely) | 1 - 8 (depending on bits used) |
| `"varBigInt"` | signed variable-length encoded integer (`bigint` type) | limitations based on platforms bigint implementation | 1 - ? (depending on the bits used) |
| `"varBigUint"` | unsigned variable-length encoded integer (`bigint` type) | limitations based on platforms bigint implementation | 1 - ? (depending on the bits used) |
| `"varFloat32"` | single-precision variable-length encoded floating-point number | `-3.40282347e+38` to `3.40282347e+38`| 2 - 6 (depending on bits used) |
| `"varFloat64"` | double-precision variable-length encoded floating-point number | `-1.7976931348623157e+308` to `1.7976931348623157e+308` | 2 - 10 (depending on the bits used) |

## Change Tracking

The `$track` method is called whenever a synchronized attribute gets mutated, and
marks which properties must be encoded. The `$track`/`$encoder`/`$decoder`
hooks below attach to any `Schema` class, hand-written or returned by `schema()`.

```ts filename="Vec3.ts"
import { $track, Schema, OPERATION } from "@colyseus/schema";

class Vec3 extends Schema {
    x: number;
    y: number;
    z: number;
}

Vec3[$track] = function (changeTree, index, operation = OPERATION.ADD) {
    changeTree.change(index, operation);
};
```

See [`ChangeTree`](https://github.com/colyseus/schema/blob/f755b94c5e618cfd6cdf2182199ec87b68fdae47/src/encoder/ChangeTree.ts) for more information.

## Byte-level encoding

At the `$encoder` method call, you may customize how a particular structure gets
encoded into the buffer that is sent over the wire for the client.

```ts filename="Vec3.ts"
import { $encoder, Schema } from "@colyseus/schema";

class Vec3 extends Schema {
    x: number;
    y: number;
    z: number;
}

Vec3[$encoder] = function (encoder, buffer, changeTree, index, operation, it, isEncodeAll, hasView) {
    //
    // encode x / y / z into a single byte
    // (this limits for values ranging from 0 to 7 for x, y, and z.)
    //
    const { x, y, z } = changeTree.ref;
    buffer[it.offset++] = (x << 6) | (y << 3) | z;
}
```

See [`EncodeOperation`](https://github.com/colyseus/schema/blob/f755b94c5e618cfd6cdf2182199ec87b68fdae47/src/encoder/EncodeOperation.ts#L16-L25) method signature for full list of arguments.

## Byte-level decoding

At the `$decoder` method call, you may customize how a particular structure gets
decoded, and how to interact with the callback system.

```ts filename="Vec3.ts"
import { $decoder, $refId, Schema, OPERATION } from "@colyseus/schema";

class Vec3 extends Schema {
    x: number;
    y: number;
    z: number;
}

Vec3[$decoder] = function (decoder, bytes, it, ref, allChanges) {
    //
    // decode x / y / z from a single byte
    // (values can only range from 0 to 7)
    //
    const byte = bytes[it.offset++];

    ref.x = (byte >> 6) & 0x07;
    ref.y = (byte >> 3) & 0x07;
    ref.z = byte & 0x07;

    //
    // (optional) add change to list of changes, for callback handling
    //
    allChanges.push({
        ref: ref,
        refId: ref[$refId],
        op: OPERATION.REPLACE,
        field: "x",
        value: ref.x,
        previousValue: undefined,
    });

    allChanges.push({
        ref: ref,
        refId: ref[$refId],
        op: OPERATION.REPLACE,
        field: "y",
        value: ref.y,
        previousValue: undefined,
    });

    allChanges.push({
        ref: ref,
        refId: ref[$refId],
        op: OPERATION.REPLACE,
        field: "z",
        value: ref.z,
        previousValue: undefined,
    });
}
```

See [`DecodeOperation`](https://github.com/colyseus/schema/blob/f755b94c5e618cfd6cdf2182199ec87b68fdae47/src/decoder/DecodeOperation.ts#L28-L34) method signature for full list of arguments.

## Encoding non-`Schema` structures

In order to encode 3rd party structures, there are 2 steps to take:

1. Use `Metadata.setFields()` to define the properties to be encoded.
2. Initialize each instance with `Schema.initialize()` as soon as the 3rd party structure has been instantiated.

> **Warning:**
>
> **Possible conflicts with 3rd party libraries**
>
> - `Schema.initialize()` is going to assign a property descriptor per property defined by `Metadata.setFields()`.
> - If the 3rd party library you use also defines their own property descriptors (or use getters/setters for such properties), synchronization will not work as expected.

```ts filename="Vec3.ts"
import { Schema, Metadata } from "@colyseus/schema";

// the 3rd party structure...
class Vec3 {
    x: number;
    y: number;
    z: number;
}

// define how to encode the properties
Metadata.setFields(Vec3, {
    x: "number",
    y: "number",
    z: "number",
});

// initialize it!
const vec3 = new Vec3();
Schema.initialize(vec3);

```

## Instance pooling

Constructing a `Schema` is not free: each instance gets its own change-tracking state, a property descriptor, and a values array. Every node in an entity tree multiplies that cost. A room that spawns and despawns entities continuously (projectiles, ECS entities, bots) pays it over and over.

`createPool()` recycles instances instead:

```ts
import { createPool } from "@colyseus/schema";

const pool = createPool(Entity, { preallocate: 1000 });

// spawn
const entity = pool.acquire();
entity.x = 10;
entity.y = 20;
state.entities.set(id, entity);

// despawn: detach from the state tree FIRST, then release
state.entities.delete(id);
pool.release(entity);
```

| Member | Description |
|--------|-------------|
| `createPool(ctor, opts?)` | Creates a pool for a zero-argument `Schema` class |
| `pool.acquire()` | Returns a free instance, or constructs one if the pool is empty |
| `pool.release(instance)` | Resets the instance and returns it to the pool |
| `pool.size` | Instances currently available for reuse |

Options:

| Option | Default | Description |
|--------|---------|-------------|
| `preallocate` | `0` | Construct this many instances up front, so early spawns reuse rather than allocate |
| `maxSize` | *unbounded* | Cap on retained free instances; releases beyond it are dropped and garbage-collected |

### Reuse is invisible on the wire

`release()` resets the instance to its construction defaults and drops its internal ref id, so re-adding it acquires a fresh one. A pooled instance therefore encodes **byte-identically** to a freshly constructed one. Clients cannot tell the difference, and a late joiner receiving a full state sync sees a consistent state regardless of how much churn preceded it.

### Order matters: detach, then release

> **Warning:**
>
> Remove the instance from its parent collection **before** calling `release()`. Releasing an instance that is still attached throws: it would otherwise be reset while the encoder still considered it part of the state tree.

```ts
state.entities.delete(id);   // detach first
pool.release(entity);        // then release
```

### Re-assign every field after `acquire()`

> **Warning:**
>
> **Pooling does not clear primitive values.** An acquired instance still carries the numbers, strings and booleans from its previous life. Those retained values *are* re-encoded when it re-enters the state tree. A field you forget to re-assign will silently ship the previous entity's value to clients.

Treat `acquire()` as `new` and assign every field you would have set on a fresh instance. Ref-type children (nested schemas, collections) *are* reset recursively, so a pooled entity's collections come back empty.

### Restrictions

`release()` throws when the instance is:

- **still attached** to the state tree (see above);
- **shared across multiple parents**: another owner may still hold it, so recycling it is unsafe;
- **decoder-side**: client mirror instances aren't change-tracked and can't be pooled. Pooling is a server-side optimization only;
- **holding a [streamed](https://docs.colyseus.io/state/streaming.md) collection field**: a `.stream()` map, set, collection or array cannot be reset, since per-client delivery state outlives the instance.

---
Source: https://docs.colyseus.io/state/advanced-usage


# State Sync Callbacks (Schema Callbacks)

When applying state changes coming from the server, the frontend is going to trigger callbacks on local instances according to the changes being applied.

In order to register callbacks to Schema instances, you must access the instances through a "callbacks handler".

> **Note:**
>
> Read more about [ State Synchronization](https://docs.colyseus.io/state.md)

## Overview

### Get the callback handler

**TypeScript**

```ts {10} filename="client.ts"
import { Client, Callbacks } from "@colyseus/sdk";

// initialize SDK
const client = new Client("http://localhost:2567");

// join room
const room = await client.joinOrCreate("my_room");

// get state callbacks handler
const callbacks = Callbacks.get(room);
```

**C#**

```cs {10} filename="client.cs"
using Colyseus;

// initialize SDK
var client = new Client("http://localhost:2567");

// join room
var room = await client.JoinOrCreate<MyRoomState>("my_room");

// get state callbacks handler
var callbacks = Colyseus.Schema.Callbacks.Get(room);
```

**Lua**

```lua {10} filename="client.lua"
local ColyseusSDK = require("colyseus.sdk")

-- initialize SDK
local client = ColyseusSDK.Client("http://localhost:2567")

-- join room
client:join_or_create("my_room", function(room)

    -- get state callbacks handler
    local callbacks = ColyseusSDK.callbacks(room)
end)
```

**Haxe**

```haxe {2,11} filename="client.hx"
import colyseus.Client;
import io.colyseus.serializer.schema.Callbacks;

// initialize SDK
var client = new Colyseus.Client("http://localhost:2567");

// join room
client.joinOrCreate("my_room", [], MyRoomState, function(err, room) {

    // get state callbacks handler
    var callbacks = Callbacks.get(room);
});
```

**GDScript**

```gdscript {10} filename="client.gd"
# initialize SDK
var client = Colyseus.Client.new("ws://localhost:2567")

# join room
var room = client.join_or_create("my_room")

room.joined.connect(func():
    # get state callbacks handler
    var callbacks = Colyseus.Callbacks.of(room))
```

**Dart**

```dart {10} filename="client.dart"
import 'package:colyseus/colyseus.dart';

// initialize SDK
final client = ColyseusClient('ws://localhost:2567');

// join room
final room = await client.joinOrCreate('my_room', stateType: MyRoomState.new);

// get state callbacks handler
final callbacks = Callbacks.get(room);
```

### Register the callbacks

**TypeScript**

```ts filename="client.ts"
callbacks.listen("currentTurn", (currentValue, previousValue) => {
    // ...
});

// when an entity was added (ArraySchema or MapSchema)
callbacks.onAdd("entities", (entity, sessionId) => {
    // ...
    console.log("entity added", entity);

    callbacks.listen(entity, "hp", (currentHp, previousHp) => {
        console.log("entity", sessionId, "changed hp to", currentHp);
    })
});

// when an entity was removed (ArraySchema or MapSchema)
callbacks.onRemove("entities", (entity, sessionId) => {
    // ...
    console.log("entity removed", entity);
});
```

**C#**

```cs filename="client.cs"
callbacks.Listen(state => state.currentTurn, (currentValue, previousValue) => {
    // ...
});

// when an entity was added (ArraySchema or MapSchema)
callbacks.OnAdd(state => state.entities, (sessionId, entity) => {
    // ...
    Debug.Log($"entity added, {entity}");

    callbacks.Listen(entity, entity => entity.hp, (currentHp, previousHp) => {
        Debug.Log($"entity {sessionId} changed hp to {currentHp}");
    });
});

// when an entity was removed (ArraySchema or MapSchema)
callbacks.OnRemove(state => state.entities, (sessionId, entity) => {
    // ...
    Debug.Log($"entity removed {entity}");
});
```

**Lua**

```lua filename="client.lua"
callbacks:listen("currentTurn", function (currentValue, previousValue)
    -- ...
end)

-- when an entity was added (ArraySchema or MapSchema)
callbacks:on_add("entities", function (entity, sessionId)
    -- ...
    print("entity added", entity)

    callbacks:listen(entity, "hp", function (currentHp, previousHp)
        print("entity", sessionId, "changed hp to", currentHp)
    end)
end)

-- when an entity was removed (ArraySchema or MapSchema)
callbacks:on_remove("entities", function (entity, sessionId)
    -- ...
    print("entity removed")
    pprint(entity)
end)
```

**Haxe**

```haxe filename="client.hx"
callbacks.listen("currentTurn", function (currentValue, previousValue) {
    // ...
});

// when an entity was added (ArraySchema or MapSchema)
callbacks.onAdd("entities", function (entity, sessionId) {
    // ...
    trace("entity added", entity);

    callbacks.listen(entity, "hp", function (currentHp, previousHp) {
        trace("entity", sessionId, "changed hp to", currentHp);
    });
});

// when an entity was removed (ArraySchema or MapSchema)
callbacks.onRemove("entities", function (entity, sessionId) {
    // ...
    trace("entity removed", entity);
});
```

**GDScript**

```gdscript filename="client.gd"
callbacks.listen("currentTurn", _on_turn_change)

func _on_turn_change(current_value, previous_value):
    pass  # ...

# when an entity was added (ArraySchema or MapSchema)
callbacks.on_add("entities", _on_entity_add)

func _on_entity_add(entity, session_id):
    print("entity added: ", entity)

    callbacks.listen(entity, "hp", func(current_hp, previous_hp):
        print("entity ", session_id, " changed hp to ", current_hp))

# when an entity was removed (ArraySchema or MapSchema)
callbacks.on_remove("entities", _on_entity_remove)

func _on_entity_remove(entity, session_id):
    print("entity removed: ", entity)
```

**Dart**

```dart filename="client.dart"
final state = room.state!;

callbacks.listen(state, 'currentTurn', (value, previous) {
    // ...
});

// when an entity was added (ArraySchema or MapSchema)
callbacks.onAdd(state.entities, (sessionId, entity) {
    // ...
    print('entity added: $entity');

    callbacks.listen(entity, 'hp', (currentHp, previousHp) {
        print('entity $sessionId changed hp to $currentHp');
    });
});

// when an entity was removed (ArraySchema or MapSchema)
callbacks.onRemove(state.entities, (sessionId, entity) {
    // ...
    print('entity removed: $entity');
});
```

> **Warning:**
>
> **C#, C++, Haxe, Dart** - When using statically typed languages, you need to generate the frontend schema files based on your TypeScript schema definitions. [See generating schema on the frontend](#frontend-schema-generation).

## How to use

### On `Schema` instances

#### Listen

Listens for a single property change within a `Schema` instance.

**TypeScript**

```ts filename="client.ts"
callbacks.listen("currentTurn", (currentValue, previousValue) => {
    console.log(`currentTurn is now ${currentValue}`);
    console.log(`previous value was: ${previousValue}`);
});
```

**C#**

```cs filename="client.cs"
callbacks.Listen(state => state.currentTurn, (currentValue, previousValue) => {
    Debug.Log($"currentTurn is now {currentValue}");
    Debug.Log($"previous value was: {previousValue}");
});
```

**Lua**

```lua filename="client.lua"
callbacks:listen("currentTurn", function (currentValue, previousValue)
    print("currentTurn is now " .. currentValue)
    print("previous value was: " .. previousValue)
end)
```

**Haxe**

```haxe filename="client.hx"
callbacks.listen("currentTurn", function (currentValue, previousValue) {
    trace("currentTurn is now " + currentValue);
    trace("previous value was: " + previousValue);
});
```

**GDScript**

```gdscript filename="client.gd"
callbacks.listen("currentTurn", _on_turn_change)

func _on_turn_change(current_value, previous_value):
    print("currentTurn is now ", current_value)
    print("previous value was: ", previous_value)
```

**Dart**

```dart filename="client.dart"
callbacks.listen(state, 'currentTurn', (value, previous) {
    print('currentTurn is now $value');
    print('previous value was: $previous');
});
```

**Removing the callback:** The `.listen()` method returns a function that, when called, removes the attached callback. In Dart, it returns a `StreamSubscription`. Call `cancel()` on it instead:

**TypeScript**

```ts filename="client.ts"
const unbindCallback = callbacks.listen("currentTurn", (currentValue, previousValue) => {
    // ...
});

// stop listening for `"currentTurn"` changes.
unbindCallback();
```

**C#**

```cs filename="client.cs"
var unbindCallback = callbacks.Listen(state => state.currentTurn, (currentValue, previousValue) => {
    // ...
});

// stop listening for `"currentTurn"` changes.
unbindCallback();
```

**Lua**

```lua filename="client.lua"
local unbind_callback = callbacks:listen("currentTurn", function (currentValue, previousValue)
    -- ...
end)

-- stop listening for `"currentTurn"` changes.
unbind_callback()
```

**Haxe**

```haxe filename="client.hx"
var unbindCallback = callbacks.listen("currentTurn", function (currentValue, previousValue) {
    // ...
});

// stop listening for `"currentTurn"` changes.
unbindCallback();
```

**GDScript**

```gdscript filename="client.gd"
var unbind_callback = callbacks.listen("currentTurn", _on_turn_change)

# stop listening for "currentTurn" changes
unbind_callback.call()
```

**Dart**

```dart filename="client.dart"
final subscription = callbacks.listen(state, 'currentTurn', (value, previous) {
    // ...
});

// stop listening for `"currentTurn"` changes.
await subscription.cancel();
```

---

#### Bind To

Bind properties directly to `targetObject`, whenever the client receives an update from the server.

**Parameters:**

- `targetObject`: the object that will receive updates
- `properties`: (optional) list of properties that will be assigned to
  `targetObject`. By default, every synchronized property will be used.

**TypeScript**

```ts filename="client.ts"
callbacks.onAdd("players", (player, sessionId) => {
    const playerVisual = PIXI.Sprite.from('player');
    callbacks.bindTo(player, playerVisual);
});
```

**C#**

```cs filename="client.cs"
callbacks.OnAdd(state => state.players, (sessionId, player) => {
    var playerVisual = new PlayerVisual();
    callbacks.BindTo(player, playerVisual);
});
```

**Lua**

```lua filename="client.lua"
--
-- callbacks:bind_to() is not implemented in Lua SDK yet
-- contributions are very welcome!
--
```

**Haxe**

```haxe filename="client.hx"
//
// callbacks.bindTo() is not implemented in Haxe SDK yet
// contributions are very welcome!
//
```

**GDScript**

```gdscript filename="client.gd"
#
# callbacks.bind_to() is not implemented in Godot SDK yet
# contributions are very welcome!
#
```

**Dart**

```dart filename="client.dart"
//
// callbacks.bindTo() is not implemented in Flutter SDK yet
// contributions are very welcome!
//
```

---

#### On Change

The On Change callback is invoked whenever a direct property of a `Schema` instance is modified.

- **Triggers only for direct property changes:** It does not cascade or propagate changes from nested properties within the Schema.
- The callback fires after the changes have been applied to the Schema instance, so you're dealing with the updated instance when it executes.

**TypeScript**

```ts {3-5} filename="client.ts"
callbacks.onAdd("entities", (entity, sessionId) => {
    // ...
    callbacks.onChange(entity, () => {
        // some property changed inside `entity`
    })
});
```

**C#**

```cs {3-5} filename="client.cs"
callbacks.OnAdd(state => state.entities, (sessionId, entity) => {
    // ...
    callbacks.OnChange(entity, () => {
        // some property changed inside `entity`
    });
});
```

**Lua**

```lua {3-5} filename="client.lua"
callbacks:on_add("entities", function (entity, sessionId)
    -- ...
    callbacks:on_change(entity, function ()
        -- some property changed inside `entity`
    end)
end)
```

**Haxe**

```haxe {3-5} filename="client.hx"
callbacks.onAdd("entities", function(entity, sessionId) {
    // ...
    callbacks.onChange(entity, function() {
        // some property changed inside `entity`
    });
});
```

**GDScript**

```gdscript filename="client.gd"
callbacks.on_add("entities", _on_entity_add)

func _on_entity_add(entity, session_id):
    # ...
    callbacks.on_change(entity, func():
        # some property changed inside entity
        pass)
```

**Dart**

```dart {3-5} filename="client.dart"
callbacks.onAdd(state.entities, (sessionId, entity) {
    // ...
    callbacks.onChange(entity, () {
        // some property changed inside `entity`
    });
});
```

---

### On Maps or Arrays

#### On Add

Register the `onAdd` callback is called whenever a new instance is added to a collection.

By default, the callback is called immediately for existing items in the collection.

Registering before the server has sent the collection is fine. A collection the client still holds as `null`, or as the empty instance a generated C# class starts with, counts as not yet received. The callback waits and fires when the first sync, or a later patch, delivers it, replaying the items that arrived with it. A collection a [`StateView`](https://docs.colyseus.io/state/view.md) adds later arrives the same way.

**TypeScript**

```ts {1} filename="client.ts"
callbacks.onAdd("players", (player, sessionId) => {
    console.log(player, "has been added at", sessionId);

    // add your player entity to the game world!

    // detecting changes on object properties
    callbacks.listen(player, "field_name", (value, previousValue) => {
        console.log(value);
        console.log(previousValue);
    });
});
```

**C#**

```cs {1} filename="client.cs"
callbacks.OnAdd(state => state.players, (string sessionId, Player player) => {
    Debug.Log("player has been added at " + sessionId);

    // add your player entity to the game world!

    // detecting changes on object properties
    callbacks.Listen(player, player => player.field_name, (value, previousValue) => {
        Debug.Log(value);
        Debug.Log(previousValue);
    });
});
```

**Lua**

```lua {1} filename="client.lua"
callbacks:on_add("players", function (player, sessionId)
    print("player has been added at " .. sessionId);

    -- add your player entity to the game world!

    -- detecting changes on object properties
    callbacks:listen(player, "field_name", function(value, previous_value)
        print(value)
        print(previousValue)
    end)
end)
```

**Haxe**

```haxe {1} filename="client.hx"
callbacks.onAdd("players", (player, sessionId) => {
    trace("player has been added at " + sessionId);

    // add your player entity to the game world!

    // detecting changes on object properties
    callbacks.listen(player, "field_name", (value, previousValue) => {
        trace(value);
        trace(previousValue);
    });
});
```

**GDScript**

```gdscript filename="client.gd"
callbacks.on_add("players", _on_player_add)

func _on_player_add(player, session_id):
    print("player has been added at ", session_id)

    # add your player entity to the game world!

    # detecting changes on object properties
    callbacks.listen(player, "field_name", func(value, previous_value):
        print(value)
        print(previous_value))
```

**Dart**

```dart {1} filename="client.dart"
callbacks.onAdd(state.players, (sessionId, player) {
    print('player has been added at $sessionId');

    // add your player entity to the game world!

    // detecting changes on object properties
    callbacks.listen(player, 'field_name', (value, previousValue) {
        print(value);
        print(previousValue);
    });
});
```

---

#### On Remove

The `onRemove` callback is called with the removed item and its key on holder object as argument.

**TypeScript**

```ts {1} filename="client.ts"
callbacks.onRemove("players", (player, sessionId) => {
    console.log(player, "has been removed at", sessionId);

    // remove your player entity from the game world!
});
```

**C#**

```cs {1} filename="client.cs"
callbacks.OnRemove(state => state.players, (string sessionId, Player player) => {
    Debug.Log("player has been removed at " + sessionId);

    // remove your player entity from the game world!
});
```

**Lua**

```lua {1} filename="client.lua"
callbacks:on_remove("players", function (player, sessionId)
    print("player has been removed at " .. sessionId);

    -- remove your player entity from the game world!
end)
```

**Haxe**

```haxe {1} filename="client.hx"
callbacks.onRemove("players", (player, sessionId) => {
    trace("player has been removed at " + sessionId);

    // remove your player entity from the game world!
});
```

**GDScript**

```gdscript filename="client.gd"
callbacks.on_remove("players", _on_player_remove)

func _on_player_remove(player, session_id):
    print("player has been removed at ", session_id)

    # remove your player entity from the game world!
```

**Dart**

```dart {1} filename="client.dart"
callbacks.onRemove(state.players, (sessionId, player) {
    print('player has been removed at $sessionId');

    // remove your player entity from the game world!
});
```

---

## Frontend Schema Generation

> **Warning:**
>
> **Not required when using [JavaScript SDK](https://docs.colyseus.io/getting-started/typescript.md) or [Defold SDK](https://docs.colyseus.io/getting-started/defold.md).** The following section is only required when using statically typed languages in your frontend, such as C#, Haxe, etc.

The `schema-codegen` is a command-line tool designed to convert your backend schema definitions into compatible frontend schemas.

To decode the state on the frontend, its local schema definitions must be compatible with those on the server.

**Usage:**

To see the usage, From your terminal, `cd` into your server's directory and run the following command:

```sh filename="Terminal"
npx schema-codegen --help
```

**Output:**

```sh filename="Terminal"
schema-codegen [path/to/Schema.ts]

Usage (C#/Unity)
    schema-codegen src/Schema.ts --output frontend/ --csharp --namespace MyGame.Schema

Valid options:
    --output: the output directory for generated client-side schema files
    --c: generate for C
    --csharp: generate for C#/Unity
    --cpp: generate for C++
    --dart: generate for Dart/Flutter
    --gdscript: generate for Godot
    --haxe: generate for Haxe
    --ts: generate for TypeScript
    --js: generate for JavaScript
    --java: generate for Java
    --lua: generate for Lua
    --swift: generate for Swift

Optional:
    --namespace: generate namespace on output code
    --bundle: bundle all schemas into a single output file
    --decorator: custom decorator name (default: "type")
```

### Example: Unity / C#

Below is a real example to generate the C# schema files from the [demo Unity project](https://github.com/colyseus/colyseus-unity3d/blob/aa9a722a50b2958ce01785969cd8ecb8aee24fd0/Server/package.json#L12).

```sh filename="Terminal"
npx schema-codegen src/rooms/schema/* --csharp --output ../Assets/Scripts/States/
generated: Player.cs
generated: State.cs
```

**Using `npm` scripts:**

For short, it is recommended to have your `schema-codegen` arguments configured under a `npm` script in your `package.json`:

```json filename="package.json"
"scripts": {
    "schema-codegen": "schema-codegen src/rooms/schema/* --csharp --output ../Assets/Scripts/States/"
}
```

This way you can run `npm run schema-codegen` rather than the full command:

```sh filename="Terminal"
npm run schema-codegen
generated: Player.cs
generated: State.cs
```

---
Source: https://docs.colyseus.io/state/callbacks


# Advanced: Implement Your Own Callback System

The `@colyseus/schema` version `3.0` introduced a way to bring your own callback system during decoding.

The standard way of attaching callbacks uses the same "flavor" as Colyseus is used to from previous versions. However, you can bring your own callback system by overriding the `Decoder`'s `triggerChanges` method.

The following example shows how to bring your own callback system:

```ts filename="client.ts"
import { getRawChangesCallback } from "@colyseus/schema";

// Also available on the decoder root:
// - decoder.root.refs        => map of all Schema instances by refId
// - decoder.root.refCount    => map of reference counts by refId
// - instance[$refId]         => a ref's id, stored on the instance itself
//                               ($refId is exported from @colyseus/schema)

const room = await client.joinOrCreate("my_room");
getRawChangesCallback(room['serializer']['decoder'], (changes) => {
    console.log("raw list of changes", changes);
});
```

On the above example, the raw list of changes is being printed to the console.

Each SDK has its own way of handling the callback system.

- [JavaScript SDK](https://github.com/colyseus/schema/blob/3.0/src/decoder/strategy/StateCallbacks.ts)
- [Unity SDK](https://github.com/colyseus/colyseus-unity-sdk/blob/0.16/Assets/Colyseus/Runtime/Colyseus/Serializer/Schema/Callbacks/Callbacks.cs)
- [Defold SDK](https://github.com/colyseus/colyseus-defold/blob/0.16/colyseus/serializer/schema/callbacks.lua)
- [Haxe SDK](https://github.com/colyseus/colyseus-haxe/blob/0.16/src/io/colyseus/serializer/schema/Callbacks.hx)

---
Source: https://docs.colyseus.io/state/callbacks/custom


# React

Here you will find a guide on how to use the Frontend State Sync Callbacks with React.

> **Warning:**
>
> React hooks for state synchronization ship today as the separate [`@colyseus/react`](https://github.com/colyseus/react-tools) package: `useRoom`, `useRoomState`, `useRoomMessage`, `useLobbyRoom`, and friends. See [Getting Started with React](https://docs.colyseus.io/getting-started/react.md) for usage.

---
Source: https://docs.colyseus.io/state/callbacks/react


# Optimizing State

State synchronization is already delta-encoded. Only the properties that changed since the last patch are sent, and a property re-assigned to the same value is not sent at all. Most rooms never need to think past that.

This page is for the rooms that do: many entities, a high tick rate, or a bandwidth bill. It documents what a patch actually costs, so you can reason about your own state instead of guessing.

## What a patch costs

Every patch is built from these costs:

| Unit | Cost | Notes |
|------|------|-------|
| Each instance that changed this tick | 1 byte, plus its `refId` | A `refId` is 1 byte below 128, 2 below 256, 3 below 65,536, then 5 |
| Each changed `Schema` field | **1 byte**, plus the value | The operation and the field index share one byte |
| Each changed collection entry | 1 byte, plus its index, plus the value | No packing: the index is a separate number, sized as above |
| A `MapSchema` insertion | The above, plus the UTF-8 key | Only on insert. Later updates to that entry omit the key |

A `Schema` field is the cheapest slot Colyseus has. One byte carries both "what happened" and "which field", for every field from the first to the sixty-third.

### A worked example

Sixty entities in a `t.map(Entity)`, each with an `x`, a `y` and a hit-point value. All of them move every tick, so only `x` and `y` change.

Per entity, per tick: 1 byte to switch to the instance, then 1 byte for its `refId`. Each of `x` and `y` then costs one field header plus its value. Only the declared type differs between the rows:

| Declaration | Value bytes each | Per entity | 60 entities, 20 ticks per second |
|---|---|---|---|
| `t.number()` | 5 | 14 B | 16.4 KB/s |
| `t.float32()` | 4 | 12 B | 14.1 KB/s |
| `t.quantized({ min: 0, max: 1024 })` | 2 | 8 B | 9.4 KB/s |

The declaration is the only thing that changed. Your game code still reads and writes a plain `number` in all three rows.

> **Note:**
>
> **Instances that did not change cost nothing.** The encoder walks a list of instances with recorded changes and skips the rest. A parent whose own fields were untouched contributes zero bytes, even when its children changed.
>
> Re-assigning a field to the value it already holds also costs nothing. The setter compares first and returns early.

## Choosing field types

Fixed-width types write exactly their width, with no type tag: `t.uint8()` is 1 byte, `t.int16()` is 2, `t.float32()` is 4, `t.float64()` is 8, `t.boolean()` is 1.

`t.number()` is different. This type is self-describing, so it carries a tag byte and sizes itself to the value:

| `t.number()` value | Bytes |
|---|---|
| Integer `0` to `127`, or `-32` to `-1` | 1 |
| Integer up to ±255 | 2 |
| Integer up to ±32767 | 3 |
| Integer up to ±2147483647 | 5 |
| **Any non-integer** | **5**, or 9 when `float32` precision is not enough |

That last row is the trap. A position of `12.5` costs 5 bytes as `t.number()` and 4 as `t.float32()`.

> Small integers keep `t.number()`: it costs 1 byte below 128 and adapts if the value grows. Per-tick floats take `t.float32()`. Bounded floats take `t.quantized()`.

[Quantized floats](https://docs.colyseus.io/state/schema.md#quantized-floats-tquantized--tangle) win twice. A 16-bit quantized field is 2 bytes instead of 4, and its setter snaps the value to the nearest representable step before comparing. A rotation that drifts by less than one step is therefore not a change, and emits nothing. The same drift on a `float32` emits a full delta every tick.

Strings carry a length prefix: 1 byte under 32 UTF-8 bytes, 2 under 256, then 3 and 5. Keep `MapSchema` keys short, because the key is written on every insertion.

## Shaping your schemas

**Prefer a declared field to a collection entry** for a fixed set of things. Three declared fields cost 3 bytes of framing. Three map entries cost at least 6, plus their keys on insert.

**Splitting fields onto a nested `Schema` is usually free, but not always.** When only the child changes, the parent emits nothing and the cost is identical to a flat layout. The extra header is paid only when parent and child change in the same tick. What a nested instance always costs is another `refId` and another change-tracking structure on the server.

**Keep `refId` values low if you can.** They are allocated monotonically and never recycled. Once a room has created 128 instances over its lifetime, every instance header in every patch grows by one byte. A long-lived room that churns thousands of entities pays that permanently, which is one of the arguments for [instance pooling](https://docs.colyseus.io/state/advanced-usage.md#instance-pooling).

**Declare `.fullStateOnly()` and `.stream()` fields early.** Both resolve through a bitmask for the first 32 fields. At index 32 and above they fall back to a linear scan over the tagged-field list, on every mutation. This costs server CPU rather than bandwidth, and only applies to a schema wide enough to reach index 32.

**Field count barely matters on the wire.** A field at index 62 costs the same single byte as a field at index 0. A `Schema` with 8 fields or fewer does track its changes more cheaply, without a per-instance array allocation. The bytes it produces are identical, so this is a memory saving rather than a bandwidth one.

> **Warning:**
>
> A `Schema` holds at most **63 fields**. Colyseus rejects the 64th field where the class is defined. A field index shares one byte with the operation code, and the last combination collides with the marker that starts a new structure. Nest a child `Schema` before you reach the cap.

## Collection operations

Most `ArraySchema` operations cost far less than people assume:

| Operation | Cost |
|---|---|
| `push()` | One insertion per item |
| `shift()` | A single deletion. Survivors are not re-indexed |
| `splice(i, n)` | One deletion per **removed** element. The tail is not re-sent |
| `unshift()` | One shift marker, then one insertion per item |
| `reverse()` | 1 byte |
| `clear()` | 1 byte, and it discards any operations already pending |
| **`sort()`** | **The entire array** |

> **Warning:**
>
> **`sort()` re-sends every element.** The call marks every index as changed. A sorted array of 200 entities therefore produces a full 200-element patch, every time. Sort a plain copy on the client instead, or sort a separate array of indexes.

Avoid detaching and re-attaching the same instance. Moving an instance between collections, or calling `map.delete(key)` and then `map.set(key, sameInstance)`, re-stages every field on it as a fresh insertion. The client receives the whole object again.

## Sending less, and less often

Everything above shrinks a patch. These shrink how much of it each client receives, or how often:

- [**Delivery modifiers**](https://docs.colyseus.io/state/schema.md#delivery-modifiers). `.fullStateOnly()` for room configuration set once in `onCreate()`, so it never touches a tick patch. `.patchOnly()` for data a late joiner does not need.
- [**`.noSync()`**](https://docs.colyseus.io/state/schema.md#field-modifiers) for fields that should never leave the server at all.
- [**`patchRate`**](https://docs.colyseus.io/room.md#configuration-properties). The simplest lever, and the first one to try. Only the latest value of each property is sent, so patching half as often roughly halves the traffic from fields that change every tick.
- [**State View**](https://docs.colyseus.io/state/view.md). Send each client only the slice it can see.
- [**Streaming collections**](https://docs.colyseus.io/state/streaming.md#maxpertick). Cap how many new entries a client receives per tick, so a hundred-entity spawn burst does not arrive as one packet.

Three things about `StateView` that are easy to learn the expensive way:

- **A single `.view()` field anywhere in the state tree changes the cost model for the whole room.** Without one, the server encodes the patch once and sends the same buffer to everyone. With one, it encodes per client. Use views deliberately, not decoratively.
- **Clients that see the same slice should share one `StateView` instance.** The serializer caches the encoded buffer per view object, so ten clients on one view cost one encode, not ten.
- **Re-adding an instance to a view re-sends all of its fields.** Area-of-interest logic that adds and removes entities as they cross a radius pays a full re-send on every crossing. Give the radius some hysteresis so entities near the boundary do not oscillate.

## Server-side cost

Not every cost is bandwidth. Two levers reduce work on the server instead.

[**Instance pooling**](https://docs.colyseus.io/state/advanced-usage.md#instance-pooling) recycles `Schema` instances in rooms that spawn and despawn constantly. Pooled instances encode byte-identically to fresh ones.

### Change-tracking control

Every mutation of a synchronized field is recorded as a change. These methods opt out. They exist on `Schema` and on `ArraySchema`, `MapSchema`, `SetSchema` and `CollectionSchema`:

| Method | Effect |
|---|---|
| `instance.untracked(fn)` | Runs `fn` with recording paused, then restores the previous state. Safe to nest |
| `instance.pauseTracking()` | Stops recording mutations on this instance |
| `instance.resumeTracking()` | Resumes recording |
| `instance.isTrackingPaused` | `true` while recording is paused |
| `instance.setDirty(property, operation?)` | Forces a field into the next patch |

```ts filename="src/rooms/MyRoom.ts"
onCreate() {
    this.state = new MyState();

    // Restoring saved values before any client can join. The full state
    // sync carries them anyway, so recording them is wasted work.
    this.state.untracked(() => {
        this.state.mapName = saved.mapName;
        this.state.roundNumber = saved.roundNumber;
        this.state.seed = saved.seed;
    });
}
```

Two properties of this API are worth stating plainly, because neither is guessable:

- **Pausing is per instance, not global.** `player.pauseTracking()` silences that player, and only that player. Every other instance keeps recording, nested children included. To silence a collection, call the method on the collection itself.
- **Untracked values still reach a late joiner.** A full state sync is derived by walking the structure, not by replaying recorded changes. A client that joins later sees the current value of every field, tracked or not.

> **Note:**
>
> Use this for an instance's own fields. Pausing a parent does not pause the child instances hanging off it. A structural change, such as inserting into a collection, is still recorded on the structure that owns it.

> **Warning:**
>
> **A mutation made while tracking is paused never reaches clients that are already connected.** It is not queued, and resuming does not flush it. The value stays invisible until something marks the field dirty: a later ordinary mutation, an explicit `setDirty()`, or a full state sync on join.

## Reducing the join payload

Two costs apply once per client, at join time, rather than every tick.

**Fields left `undefined`, and fields set to `null`, are skipped entirely in the full state sync.** An `.optional()` field that is never assigned costs nothing. So does a [`.deprecated()`](https://docs.colyseus.io/state/schema.md#versioning-and-backwardsforwards-compatibility) field: its setter is a no-op, so it never holds a value to send.

> **Warning:**
>
> `.deprecated(false)` is the exception. Silencing the access error keeps the real accessors, so the field can still hold a value. That value then ships in every full state sync. A retired field also keeps its slot against the 63-field cap.

**Passing your state class when joining skips the handshake.** By default the server first sends every type definition that composes the room state, then the state itself. A client that already has the concrete classes can skip the first half. See [Getting Started with TypeScript](https://docs.colyseus.io/getting-started/typescript.md).

## Next Steps

- [Schema Definition](https://docs.colyseus.io/state/schema.md) - Field types, modifiers, and delivery modifiers
- [State View](https://docs.colyseus.io/state/view.md) - Per-client filtering
- [Streaming Collections](https://docs.colyseus.io/state/streaming.md) - Per-tick budgets for large collections
- [Advanced Usage](https://docs.colyseus.io/state/advanced-usage.md) - Instance pooling and custom primitive types

---
Source: https://docs.colyseus.io/state/optimization


# Schema Definition

- Schema structures are defined on the backend and describe data that is continuously synchronized between server and client.
- A field is synchronized when it is **declared**: with a `t.*` builder, or with a [`@type()` decorator](https://docs.colyseus.io/state/schema/decorators.md). Plain class properties are invisible to the serializer.
- A declared field can opt out with [`.noSync()`](#field-modifiers), and *how* it reaches clients is tunable with [delivery modifiers](#delivery-modifiers).

> **Warning:**
>
> `Schema` is for the two things that synchronize continuously: your room's **state**, and the **[input](https://docs.colyseus.io/netcode/server-input.md)** clients send back. Don't reach for it elsewhere. [Room messages](https://docs.colyseus.io/room/messages.md) and other one-off payloads have their own serialization and don't need a schema.

> **Note:**
>
> Coming from `@type()` decorators? Every example below offers a **Decorators** tab, and your selection is remembered across pages. Decorator-specific setup and details live in [Decorators](https://docs.colyseus.io/state/schema/decorators.md).

## Defining a `Schema` structure

**Schema Builder**

```ts filename="MyState.ts"
import { schema, t } from "@colyseus/schema";

export const MyState = schema({
    currentTurn: t.string(),
}, "MyState");
```

    `schema()` returns a real class: `instanceof` works, and you instantiate it with `new`. It runs in plain JavaScript and TypeScript alike, with no compiler configuration.

    Each field takes a `t.*` builder. Since schema 5 (Colyseus 0.18), raw strings like `"string"` as field values are no longer accepted and throw at definition time. (They remain valid as [collection](#array-arrayschema) child types, e.g. `t.array("string")`.)

**Decorators**

```ts filename="MyState.ts"
import { Schema, type } from "@colyseus/schema";

export class MyState extends Schema {
    @type("string") currentTurn: string;
}
```

    The decorator style requires two `tsconfig.json` flags. See [Decorators → TypeScript Config](https://docs.colyseus.io/state/schema/decorators.md#typescript-config).

Assign an instance to your room's `state` property to start synchronizing it. [State Synchronization](https://docs.colyseus.io/state.md#overview) walks through the full loop, from definition to client callbacks.

The sections below cover each aspect of a schema definition, in both styles. The tabs remember your choice across pages.

### Deriving the TypeScript type

**Schema Builder**

`schema()` returns a value, not a type. To reference the instance type in TypeScript (`Room<MyState>`, function parameters, etc.), declare a type alias with the same name using `SchemaType`:

```ts filename="MyState.ts"
import { schema, t, type SchemaType } from "@colyseus/schema";

export const Player = schema({
    x: t.number(),
    y: t.number(),
}, "Player");
export type Player = SchemaType<typeof Player>;
```

    The `const` and the `type` merge under one name, so `Player` works as both: `new Player()` and `function move(player: Player)`. Plain JavaScript users omit the `type` line.

**Decorators**

A decorator class is already its own type (no alias needed):

```ts filename="MyState.ts"
import { Schema, type } from "@colyseus/schema";

export class Player extends Schema {
    @type("number") x: number;
    @type("number") y: number;
}

function move(player: Player) { /* ... */ }
```

### Naming schemas

The serializer identifies each structure by its runtime class name. An anonymous class degrades error messages, debug output and cross-language code generation.

**Schema Builder**

The second argument of `schema()` sets the runtime class name. Pass it for every state structure:

```ts
const Player = schema({ /* ... */ }, "Player");
```

**Decorators**

The class name is used automatically:

```ts
class Player extends Schema { /* ... */ }
```

### Default values

**Schema Builder**

Chain `.default(value)` to set a field's initial value. Passing a **function** makes it a factory, invoked once per construction. Use it for any mutable default that must not be shared across instances:

```ts
const Player = schema({
    hp: t.uint8().default(100),
    inputQueue: t.ref(Array).noSync().default(() => []),  // fresh array per instance
}, "Player");
```

    Fields without an explicit default are auto-instantiated when possible: collections start as an empty `ArraySchema`/`MapSchema`/`SetSchema`/`CollectionSchema`, and a child schema field starts as `new Child()` when the child requires no construction arguments. You don't write the decorator style's property initializers with the builder.

**Decorators**

Use regular class property initializers. Collections and child schemas are initialized explicitly on the property:

```ts
class Player extends Schema {
    @type("uint8") hp: number = 100;
    @type({ map: Item }) items = new MapSchema<Item>();
}
```

### Methods and constructors

**Schema Builder**

Function-valued properties become methods on the resulting class. The special `initialize(props)` method acts as the constructor body:

```ts
const Player = schema({
    name: t.string(),
    hp: t.uint8().default(100),

    initialize(props: { name: string }) {
        this.name = props.name.trim();
    },

    takeDamage(amount: number) {
        this.hp -= amount;
    },
}, "Player");

const player = new Player({ name: "Alice " });
player.takeDamage(10);
```

    - Without an `initialize()`, the constructor already accepts a partial props object: `new Player({ hp: 50 })`.
    - With an `initialize()`, its parameter becomes the constructor signature: a required parameter makes `new Player()` a type error, and assigning the schema fields from `props` is `initialize()`'s job.
    - `initialize()` runs only for the exact class being constructed. When extending, invoke the parent's explicitly with `Parent.prototype.initialize.call(this, props)`.

**Decorators**

Methods are ordinary class methods, and a custom constructor replaces `initialize()`:

```ts
class Player extends Schema {
    @type("string") name: string;
    @type("uint8") hp: number = 100;

    constructor(props: { name: string }) {
        super();
        this.name = props.name.trim();
    }

    takeDamage(amount: number) {
        this.hp -= amount;
    }
}

const player = new Player({ name: "Alice " });
player.takeDamage(10);
```

    - Without a custom constructor, the base `Schema` constructor already accepts a partial props object: `new Player({ hp: 50 })`.
    - A custom constructor must call `super()` first: bare `super()` and assign fields yourself, or `super(props)` to keep the automatic property assignment.

### Field modifiers

Every `t.*` builder accepts chainable modifiers. Most have a decorator equivalent; the rest are builder-only:

| Modifier | Effect | Decorator equivalent |
|----------|--------|---------------------|
| `.default(value \| factory)` | Initial value; function form builds a fresh value per instance | property initializer |
| `.view(tag?)` | Field visible only through a client's [StateView](https://docs.colyseus.io/state/view.md) | `@view(tag?)` |
| `.deprecated(throws?)` | Retire a field while keeping encoding order (see [Versioning](#versioning-and-backwardsforwards-compatibility)) | `@deprecated()` |
| `.optional()` | Type becomes `T \| undefined`; skips auto-instantiation | — |
| `.noSync()` | Local-only field: typed and initialized, but never synchronized | — |
| `.unreliable()` | Tick patches carry the field on the unreliable channel (see [Delivery modifiers](#delivery-modifiers)) | `@unreliable` |
| `.patchOnly()` | Sent on tick patches only, never in a full state sync (see [Delivery modifiers](#delivery-modifiers)) | `@patchOnly` |
| `.fullStateOnly()` | Sent in the full state sync only, never in a tick patch (see [Delivery modifiers](#delivery-modifiers)) | `@fullStateOnly` |
| `.stream()` | Drip-feed a collection's additions across ticks (see [Streaming](https://docs.colyseus.io/state/streaming.md)) | `@type({ stream: X })` |

### Delivery modifiers

The modifiers above answer *what* a field is. These three answer **when and how it reaches a client**. The value and its type are unaffected, only its delivery.

`.unreliable()` combines freely with either of the other two. `.patchOnly()` and `.fullStateOnly()` are **mutually exclusive**. They name the only two delivery channels, so a field marked both would never reach a client at all; that throws at `schema()` time.

> **Note:**
>
> `.patchOnly()` and `.fullStateOnly()` are server-side encoder concerns: the client needs no setup, its decoder just receives the field or doesn't. `.unreliable()` additionally depends on the transport, covered below.

#### `.unreliable()`

Tick patches carry the field on the **unreliable transport channel**, dropped rather than retransmitted when the network is congested. For a value that is fully replaced every tick anyway, a dropped packet costs nothing: the next tick supersedes it. Retransmitting it would only add latency.

> **Warning:**
>
> **Experimental, and WebTransport only.** Unreliable delivery needs a datagram channel, which only [WebTransport](https://docs.colyseus.io/server/transport/webtransport.md) provides today, and that transport is itself experimental.
>
> On every WebSocket transport the field reaches clients once, in the full state sync, and then freezes. Tick patches skip it, and the room logs a warning. Keep the field reliable until the transport is in place.

**Schema Builder**

```ts
const Player = schema({
    x:    t.number(),                  // reliable: every change must land
    y:    t.number(),
    aimYaw: t.angle().unreliable(),    // replaced every tick; a drop is free
}, "Player");
```

**Decorators**

```ts
class Player extends Schema {
    @type("number") x: number;                  // reliable: every change must land
    @type("number") y: number;
    @unreliable @type("number") aimYaw: number; // replaced every tick; a drop is free
}
```

    (`t.angle()` quantization is builder-only: the decorator field stays a plain `number`.)

Use it for continuously-overwritten values (look angles, interpolated positions, a cosmetic animation blend). Do **not** use it for anything a client must not miss: inventory, score, health, or any value read as a delta rather than an absolute.

The field is still written to the full state sync, so a late joiner gets the current value on arrival. Combine with `.patchOnly()` to leave it out of that too.

#### `.patchOnly()`

The field travels on **tick patches only**. A full state sync never includes it, so a client that joins mid-game does not receive it at all. The field appears only when it next changes:

**Schema Builder**

```ts
const Explosion = schema({
    x: t.number(),
    y: t.number(),
    flashIntensity: t.number().patchOnly(),  // meaningless to a late joiner
}, "Explosion");
```

**Decorators**

```ts
class Explosion extends Schema {
    @type("number") x: number;
    @type("number") y: number;
    @patchOnly @type("number") flashIntensity: number;  // meaningless to a late joiner
}
```

Use it for values that are only meaningful *as they happen*: a hit flash, a one-frame impulse, a "last damage taken" readout. Sending them in a full state sync would show a late joiner an event that already finished.

Orthogonal to `.unreliable()`: `.patchOnly()` controls whether the field is included in a full state sync, `.unreliable()` controls which channel patches use. A field marked both is skipped in full syncs *and* sent unreliably in patches.

#### `.fullStateOnly()`

For **map and room-wide data** that every client needs once: the level layout, the tile grid, spawn points, the match configuration. Data that is decided when the room is created and then simply *is*.

The field ships in the **full state sync only**: a client receives it on join, and never again.

**Schema Builder**

```ts
const MyState = schema({
    // decided at room creation, sent once to each client
    mapWidth:  t.uint16().fullStateOnly(),
    mapHeight: t.uint16().fullStateOnly(),
    tiles:     t.array("uint8").fullStateOnly(),
    spawns:    t.array(SpawnPoint).fullStateOnly(),

    // the actual game state, patched every tick
    players: t.map(Player),
}, "MyState");
```

**Decorators**

```ts
class MyState extends Schema {
    // decided at room creation, sent once to each client
    @fullStateOnly @type("uint16") mapWidth: number;
    @fullStateOnly @type("uint16") mapHeight: number;
    @fullStateOnly @type([ "uint8" ]) tiles = new ArraySchema<number>();
    @fullStateOnly @type([ SpawnPoint ]) spawns = new ArraySchema<SpawnPoint>();

    // the actual game state, patched every tick
    @type({ map: Player }) players = new MapSchema<Player>();
}
```

Room-wide data like this tends to be **large and constant**, exactly the combination you don't want anywhere near a per-tick patch. The modifier is a guarantee rather than an optimization you have to keep verifying. The field cannot end up in a patch, however the surrounding code evolves.

That makes it the exact mirror of `.patchOnly()`:

| | In the full state sync | In tick patches |
|---|---|---|
| *(default)* | ✅ | ✅ |
| `.patchOnly()` | ❌ | ✅ |
| `.fullStateOnly()` | ✅ | ❌ |

> **Warning:**
>
> Writes after a client has joined are **silently dropped**: no error, and that client keeps the value it joined with. Populate these fields during `onCreate()`, before anyone is connected. If clients need to see a field change while they're connected, it can't be `.fullStateOnly()`.

The field itself is not frozen. It stays an ordinary, mutable property on the server. Only its propagation to clients stops. On a [streamed](https://docs.colyseus.io/state/streaming.md) field the same rule applies per *element*. A client receives each element as it was when sent, and no later update to it.

## Data Types

- [Primitive Types](#primitive-types)
- [Schema Type](#schema-type)
- [ArraySchema](#array-arrayschema)
- [MapSchema](#map-mapschema)
- [SetSchema](#set-setschema)
- [CollectionSchema](#collectionschema)

### Primitive types

Each primitive type is declared through its `t.*` factory (or, in decorator style, by its quoted name):

**Schema Builder**

```ts filename="MyState.ts"
import { schema, t } from "@colyseus/schema";

const Player = schema({
    name: t.string(),
    hp: t.uint8(),
    score: t.number(),
}, "Player");
```

**Decorators**

```ts filename="MyState.ts"
import { Schema, type } from "@colyseus/schema";

class Player extends Schema {
    @type("string") name: string;
    @type("uint8") hp: number;
    @type("number") score: number;
}
```

The available primitive types:

- `string`: utf8 string type
- `boolean`: `true` or `false`
- `number`: auto-detects the number type to use. (may use one extra byte when encoding)
- `int8`, `int16`,  `int32`, `int64`: signed number types.
- `uint8`, `uint16`, `uint32`, `uint64`: unsigned number types.
- `float32`, `float64`: floating-point number types.
- `bigint64`, `biguint64`: unsigned / signed 64-bit bigint type.

#### Table of types and their limitations

| Type | Description | Limitation |
|------|-------------|------------|
| `"string"` | length-prefixed utf8 strings | maximum byte size of `4294967295` |
| `"number"` | also known as "variable length encoding". Auto-detects the number type to use. (may use one extra byte when encoding to identify the type) | ±`1.7976931348623157e+308` (float64 limits) |
| `"boolean"` | `true` or `false` | `0` or `1` |
| `"int64"` and `"uint64"` | JavaScript numbers are 64 bit floats and thus cannot represent full 64 bit integers safely | The minimum/maximum integer that can be safely represented by float64 is `-9007199254740991` to `9007199254740991` (53 bits of precision) |

Specialized number types:

| Type | Description | Limitation |
|------|-------------|------------|
| `"int8"` | signed 8-bit integer | `-128` to `127` |
| `"uint8"` | unsigned 8-bit integer | `0` to `255` |
| `"int16"` | signed 16-bit integer | `-32768` to `32767` |
| `"uint16"` | unsigned 16-bit integer | `0` to `65535` |
| `"int32"` | signed 32-bit integer | `-2147483648` to `2147483647` |
| `"uint32"` | unsigned 32-bit integer | `0` to `4294967295` |
| `"int64"` | signed 64-bit integer (`number` type) | `-2^53-1 (-9007199254740991)` to `2^53-1 (9007199254740991)` (safely) |
| `"uint64"` | unsigned 64-bit integer (`number` type) | `0` to `2^53-1 (9007199254740991)` (safely) |
| `"float32"` | single-precision floating-point number | `-3.40282347e+38` to `3.40282347e+38`|
| `"float64"` | double-precision floating-point number | `-1.7976931348623157e+308` to `1.7976931348623157e+308` |
| `"bigint64"` | signed 64-bit integer (`bigint` type) | `-2^63 (-9223372036854775808)` to `2^63-1 (9223372036854775807)` |
| `"biguint64"` | unsigned 64-bit integer (`bigint` type) | `0` to `2^64-1 (18446744073709551615)` |

#### Quantized floats (`t.quantized()` / `t.angle()`)

A float that changes every tick within a **known range** doesn't need a full 4-byte `float32`. Think of a look angle, a normalized scalar, or a unit-vector component. `t.quantized()` maps the range onto an 8-, 16- or 32-bit unsigned integer on the wire, at a precision you choose:

```ts
const Input = schema({
    yaw:      t.angle(),                                          // 2 bytes, wraps
    pitch:    t.quantized({ min: -Math.PI/2, max: Math.PI/2 }),   // 2 bytes, clamps
    throttle: t.quantized({ min: 0, max: 1, bits: 8 }),           // 1 byte
}, "Input");
```

Your code reads and writes a plain `number`. The conversion is invisible.

> **Note:**
>
> `t.quantized()` and `t.angle()` are **builder-only**: there is no decorator equivalent.

| Option | Default | Meaning |
|--------|---------|---------|
| `min` | *(required)* | Inclusive lower bound of the value domain |
| `max` | *(required)* | Upper bound: inclusive when clamping, exclusive when wrapping |
| `bits` | `16` | Wire width: `8`, `16` or `32`. Schema fields are byte-aligned, so only these three change the size |
| `mode` | `"clamp"` | `"clamp"` or `"wrap"` (see below) |

**Picking `mode`** is the only real decision, and the wire size is identical either way:

- **`"clamp"`**: the value has **hard walls**. A pitch limit, a health bar, a 0–1 throttle. Both endpoints are exact and distinct; out-of-range input clamps to the nearest end. Looking past the pitch limit stops *at* the limit. A range symmetric about zero also carries an exact zero, which matters for input axes and velocities (see below).
- **`"wrap"`**: the value is **cyclic**: `min` and `max` are the same point. An angle, a compass bearing, a hue, a phase. Any input is reduced modulo the range first, so a large accumulated or negative angle folds back in. A yaw keeps spinning instead of jamming.

> Ask: does one step past the top land you back at the bottom, as the same physical thing? → `"wrap"`. Is the top a wall you can't cross? → `"clamp"`.

`t.angle(opts?)` is sugar for a full-circle wrapping angle in radians: `t.quantized({ min: 0, max: 2π, mode: "wrap", bits: opts?.bits ?? 16 })`. At the 16-bit default that's ~0.0055° per step, finer than any mouse can resolve, in 2 bytes.

> **Warning:**
>
> **Choosing the wrong mode is a real bug.** A clamped heading jams at the `0`/`2π` seam. A wrapped pitch flips the camera the instant you look a hair too far up.

> **Note:**
>
> **A range symmetric about zero carries an exact zero.** When `min` is exactly `-max`, as in `t.quantized({ min: -1, max: 1 })` for an input axis or `{ min: -150, max: 150 }` for a velocity, the range is laid out so that `min`, `0` and `max` all land exactly on a step. A released axis reads back as `0`, so a `=== 0` test fires, and a velocity you set to zero comes to rest instead of creeping. Evening out the grid costs one of the `2^bits` codes, so the step is a hair coarser and nothing else changes.

> **Note:**
>
> **Quantization is lossy, but identically lossy on both peers.** The field only ever yields the dequantized value, so a client's prediction and the server's simulation read the *same* number. A predicted hitscan ray matches the server's. The loss is against the original float, never between the two peers.
>
> For a cyclic field that you also *interpolate* on the client, `"wrap"` fixes the wire seam, not the rendering. Lerp it shortest-arc as well, or it unwinds the long way around.

### `Schema` type

A `Schema` type can define properties as primitives, other `Schema` types, or collections (e.g., arrays or maps) that may contain nested types.

**Schema Builder**

```ts filename="MyState.ts"
import { schema, t } from "@colyseus/schema";

const World = schema({
    width: t.number(),
    height: t.number(),
    items: t.number().default(10),
}, "World");

const MyState = schema({
    world: World,   // shorthand for t.ref(World)
}, "MyState");
```

    The `world` field is auto-instantiated: `new MyState().world` is already a `World` instance. Use `t.ref(World)` instead of the bare class when you need to chain [field modifiers](#field-modifiers).

**Decorators**

```ts filename="MyState.ts"
import { Schema, type } from "@colyseus/schema";

class World extends Schema {
    @type("number") width: number;
    @type("number") height: number;
    @type("number") items: number = 10;
}

class MyState extends Schema {
    @type(World) world: World = new World();
}
```

> **Note:**
>
> A `Schema` type may hold up to 63 synchronizable properties. Nest a child `Schema` to go beyond that.
>
> Inherited fields count toward the limit, so check the parent class too. So do [`.deprecated()`](#versioning-and-backwardsforwards-compatibility) fields, which keep their slot on purpose.

### Array (`ArraySchema`)

The `ArraySchema` is a synchronizeable version of the built-in JavaScript [Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array) type.

You can't mix types inside `ArraySchema`.

**Example with primitive child type**

**Schema Builder**

```ts filename="MyState.ts"
import { schema, t } from "@colyseus/schema";

const MyState = schema({
    animals: t.array("string"),
}, "MyState");
```

            At runtime the field is an `ArraySchema` instance: `state.animals.push("cat")` works right away.

**Decorators**

```ts filename="MyState.ts"
import { Schema, ArraySchema, type } from "@colyseus/schema";

class MyState extends Schema {
    @type([ "string" ]) animals = new ArraySchema<string>();
}
```

**Example with Schema child type**

**Schema Builder**

```ts filename="MyState.ts"
import { schema, t } from "@colyseus/schema";

const Block = schema({
    x: t.number(),
    y: t.number(),
}, "Block");

const MyState = schema({
    blocks: t.array(Block),
}, "MyState");
```

**Decorators**

```ts filename="MyState.ts"
import { Schema, ArraySchema, type } from "@colyseus/schema";

class Block extends Schema {
    @type("number") x: number;
    @type("number") y: number;
}

class MyState extends Schema {
    @type([ Block ]) blocks = new ArraySchema<Block>();
}
```

---

#### `array.push()`

Adds one or more elements to the end of an array and returns the new length of the array.

``` typescript
const animals = new ArraySchema<string>();
animals.push("pigs", "goats");
animals.push("sheeps");
animals.push("cows");
// output: 4
```

---

#### `array.pop()`

Removes the last element from an array and returns that element. This method changes the length of the array.

``` typescript
animals.pop();
// output: "cows"

animals.length
// output: 3
```

---

#### `array.shift()`

Removes the first element from an array and returns that removed element. This method changes the length of the array.

``` typescript
animals.shift();
// output: "pigs"

animals.length
// output: 2
```

---

#### `array.unshift()`

Adds one or more elements to the beginning of an array and returns the new length of the array.

``` typescript
animals.unshift("pigeon");
// output: 3
```

---

#### `array.indexOf()`

Returns the first index at which a given element can be found in the array, or -1 if it is not present

``` typescript
const itemIndex = animals.indexOf("sheeps");
```

---

#### `array.splice()`

Changes the contents of an array by removing or replacing existing elements and/or adding new elements [in place](https://en.wikipedia.org/wiki/In-place_algorithm).

``` typescript
// find the index of the item you'd like to remove
const itemIndex = animals.findIndex((animal) => animal === "sheeps");

// remove it!
animals.splice(itemIndex, 1);
```

---

#### `array.shuffle()`

Shuffles the array in place. This method returns the shuffled array.

``` typescript
const animals = new ArraySchema<string>();
animals.push("pigs", "goats", "sheeps", "cows");
animals.shuffle();
// output: ["cows", "pigs", "sheeps", "goats"]
```

---

#### `array.move(cb)`

Allows you to move elements from one index to another without re-encoding them. This method takes a callback function that should mutate the array in place.

```typescript
state.cards.move((cards) => {
    // swap items at index 2 and 3
    [cards[3], cards[2]] = [cards[2], cards[3]];
})
```

---

#### `array.forEach()`

Iterates over each element of the array.

**TypeScript**

``` typescript
this.state.array1 = new ArraySchema<string>('a', 'b', 'c');

this.state.array1.forEach(element => {
    console.log(element);
});
// output: "a"
// output: "b"
// output: "c"
```

**C#**

``` cs
// ArraySchema<T> is an IReadOnlyList<T>: foreach, the indexer and LINQ all work
foreach (var value in State.array1) {
    Debug.Log(value);
}

// the callback form: type the parameters, since two overloads match
State.array1.ForEach((int index, string value) => Debug.Log(value));
```

**Lua**

``` lua
state.array1:each(function(value, index)
    print(index, "=>")
    pprint(value)
end)
```

**Haxe**

``` haxe
for (index => value in state.array1) {
    trace(index + " => " + value);
}
```

> **Note:**
>
> **More methods available for Array** - Have a look at the [MDN Documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/).

---

#### `array.clear()`

Empties the array. The frontend will trigger the `onRemove` callback for each element.

---

### Map (`MapSchema`)

The `MapSchema` is a synchronizeable version of the built-in JavaScript [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) type.

Maps are recommended to track your game entities by id, such as players, enemies, etc.

> **Warning:**
>
> **Only string keys are supported** - Currently, the `MapSchema` only allows you to customize the value type. The key type is always `string`.

**Schema Builder**

```ts filename="MyState.ts"
import { schema, t } from "@colyseus/schema";

const Player = schema({
    x: t.number(),
    y: t.number(),
}, "Player");

const MyState = schema({
    players: t.map(Player),
}, "MyState");
```

**Decorators**

```ts filename="MyState.ts"
import { Schema, MapSchema, type } from "@colyseus/schema";

class Player extends Schema {
    @type("number") x: number;
    @type("number") y: number;
}

class MyState extends Schema {
    @type({ map: Player }) players = new MapSchema<Player>();
}
```

---

#### `map.get()`

Getting a map item by its key:

``` typescript
const map = new MapSchema<string>();
const item = map.get("key");
```

---

#### `map.set()`

Setting a map item by key:

``` typescript
const map = new MapSchema<string>();
map.set("key", "value");
```

---

#### `map.delete()`

Removes a map item by key:

``` typescript
map.delete("key");
```

---

#### `map.size`

Return the number of elements in a `MapSchema` object.

``` typescript
const map = new MapSchema<number>();
map.set("one", 1);
map.set("two", 2);

console.log(map.size);
// output: 2
```

---

#### `map.forEach()`

Iterates over each key/value pair of the map, in insertion order.

**TypeScript**

``` typescript
this.state.players.forEach((value, key) => {
    console.log("key =>", key)
    console.log("value =>", value)
});
```

**C#**

``` cs
// MapSchema<T> is an IReadOnlyDictionary<string, T>: foreach walks insertion order
foreach (var (key, player) in State.players) {
    Debug.Log(key);
    Debug.Log(player);
}

// typed live views, and LINQ through IReadOnlyDictionary
foreach (var player in State.players.Values) { Draw(player); }
var alive = State.players.Values.Where(p => p.hp > 0);

// the callback form: type the parameters, since two overloads match
State.players.ForEach((string key, Player player) => Debug.Log(key));
```

**Lua**

``` lua
state.players:each(function(value, key)
    print(key, "=>")
    pprint(value)
end)
```

**Haxe**

``` haxe
for (key => value in state.players) {
    trace(index + " => " + value);
}
```

In C#, `foreach` over a `MapSchema<T>` allocates nothing. Adding or removing an entry during enumeration throws an `InvalidOperationException`.

> **Note:**
>
> **More methods available for Map** - Have a look at the [MDN Documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map/).

---

#### `map.clear()`

Empties the Map. (Frontend will trigger `onRemove` for each element.)

---

### Set (`SetSchema`)

> **Warning:**
>
> **`SetSchema` is only available for JavaScript SDK** - Haxe, C# and Lua SDKs are not implemented.

The `SetSchema` is a synchronizeable version of the built-in JavaScript [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) type.

The usage of `SetSchema` is very similar to [`CollectionSchema`], the biggest difference is that Sets hold unique values. Sets do not have a way to access a value directly. (like [collection.at()](#collectionat))

**Schema Builder**

```ts filename="MyState.ts"
import { schema, t } from "@colyseus/schema";

const Effect = schema({
    radius: t.number(),
}, "Effect");

const Player = schema({
    effects: t.set(Effect),
}, "Player");
```

**Decorators**

```ts filename="MyState.ts"
import { Schema, SetSchema, type } from "@colyseus/schema";

class Effect extends Schema {
    @type("number") radius: number;
}

class Player extends Schema {
    @type({ set: Effect }) effects = new SetSchema<Effect>();
}
```

---

#### `set.add()`

Appends an item to the `SetSchema` object.

``` typescript
const set = new SetSchema<number>();
set.add(1);
set.add(2);
set.add(3);
```

---

#### `set.delete()`

Delete an item by its value.

``` typescript
set.delete(3);
```

---

#### `set.has()`

Returns a boolean value whether an item exists in the Collection or not.

``` typescript
if (set.has(2)) {
    console.log("Exists!");
} else {
    console.log("Does not exist!");
}
```

---

#### `set.size`

Return the number of elements in a `SetSchema` object.

``` typescript
const set = new SetSchema<number>();
set.add(10);
set.add(20);
set.add(30);

console.log(set.size);
// output: 3
```

> **Note:**
>
> **More methods available for Set** - Have a look at the [MDN Documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set/).

---

#### `set.clear()`

Empties the Set. (Frontend will trigger `onRemove` for each element.)

---

### CollectionSchema

> **Warning:**
>
> **`CollectionSchema` is only available for JavaScript SDK** - Haxe, C#, Lua and C++ clients are not implemented.

The `CollectionSchema` works similarly as the `ArraySchema`, with the caveat that you don't have control over its indexes.

**Schema Builder**

```ts filename="MyState.ts"
import { schema, t } from "@colyseus/schema";

const Item = schema({
    damage: t.number(),
}, "Item");

const Player = schema({
    items: t.collection(Item),
}, "Player");
```

**Decorators**

```ts filename="MyState.ts"
import { Schema, CollectionSchema, type } from "@colyseus/schema";

class Item extends Schema {
    @type("number") damage: number;
}

class Player extends Schema {
    @type({ collection: Item }) items = new CollectionSchema<Item>();
}
```

---

#### `collection.add()`

Appends an item to the `CollectionSchema` object.

``` typescript
const collection = new CollectionSchema<number>();
collection.add(1);
collection.add(2);
collection.add(3);
```

---

#### `collection.at()`

Gets an item at the specified `index`.

``` typescript
const collection = new CollectionSchema<string>();
collection.add("one");
collection.add("two");
collection.add("three");

collection.at(1);
// output: "two"
```

---

#### `collection.delete()`

Delete an item by its value.

``` typescript
collection.delete("three");
```

---

#### `collection.has()`

Returns a boolean value whether an item exists in the Collection or not.

``` typescript
if (collection.has("two")) {
    console.log("Exists!");
} else {
    console.log("Does not exist!");
}
```

---

#### `collection.size`

Return the number of elements in a `CollectionSchema` object.

``` typescript
const collection = new CollectionSchema<number>();
collection.add(10);
collection.add(20);
collection.add(30);

console.log(collection.size);
// output: 3
```

---

#### `collection.forEach()`

The `forEach()` method executes a provided function once per each index/value pair in the `CollectionSchema` object, in insertion order.

``` typescript
collection.forEach((value, at) => {
    console.log("at =>", at)
    console.log("value =>", value)
});
```

---

#### `collection.clear()`

Empties the Collection. (Frontend will trigger `onRemove` for each element.)

---

### Versioning and backwards/forwards compatibility

Backwards/forwards compatibility is possible by declaring new fields at the end of existing structures. Earlier declarations must not be removed. Mark them `.deprecated()` instead. See a versioning example below.

**Live version 1**

```ts filename="MyState.ts"
import { schema, t } from "@colyseus/schema";

const MyState = schema({
    myField: t.string(),
}, "MyState");
```

**Live version 2**

```ts filename="MyState.ts"
import { schema, t } from "@colyseus/schema";

const MyState = schema({
    // Flag field as deprecated.
    myField: t.string().deprecated(),

    // To allow your server to play nicely with multiple frontend versions.
    newField: t.string(),
}, "MyState");
```

**Live version 3**

```ts filename="MyState.ts"
import { schema, t } from "@colyseus/schema";

const MyState = schema({
    // Flag field as deprecated.
    myField: t.string().deprecated(),

    // Flag field as deprecated again.
    newField: t.string().deprecated(),

    // New fields always at the end of the structure
    anotherNewField: t.string(),
}, "MyState");
```

Accessing a `.deprecated()` field throws an error; use `.deprecated(false)` to keep reads allowed while the field is retired. (Decorator style: `@deprecated() @type(...)`. See [Deprecating fields](https://docs.colyseus.io/state/schema/decorators.md#deprecating-fields).)

This modifier is particularly useful for native-compiled targets (C#, C++, Haxe), where the frontend may not have the latest schema definitions.

---

## Inheritance support

The collection types (`ArraySchema`, `MapSchema`, etc) must hold items of the same type. They support inherited types from the same base instance.
These inherited types may define their own serialized fields.

The following example is supported:

**Schema Builder**

```ts {3-5,8,12-13} filename="MyState.ts"
import { schema, t } from "@colyseus/schema";

const Item = schema({/* base Item fields */}, "Item");
const Weapon = Item.extend({/* specialized Weapon fields */}, "Weapon");
const Shield = Item.extend({/* specialized Shield fields */}, "Shield");

const Inventory = schema({
    items: t.map(Item),
}, "Inventory");

const inventory = new Inventory();
inventory.items.set("left", new Weapon());
inventory.items.set("right", new Shield());
```

    `.extend()` builds a real prototype chain (`new Weapon() instanceof Item` holds), inheriting fields, methods and defaults. Extended classes are registered with the serializer automatically: no extra registration step.

**Decorators**

```ts {3-5,8,12-13} filename="MyState.ts"
import { Schema, MapSchema, type } from "@colyseus/schema";

class Item extends Schema {/* base Item fields */}
class Weapon extends Item {/* specialized Weapon fields */}
class Shield extends Item {/* specialized Shield fields */}

class Inventory extends Schema {
    @type({ map: Item }) items = new MapSchema<Item>();
}

const inventory = new Inventory();
inventory.items.set("left", new Weapon());
inventory.items.set("right", new Shield());
```

    A subclass that adds no new `@type()` fields must be registered with [`@entity`](https://docs.colyseus.io/state/schema/decorators.md#inheritance).

---
Source: https://docs.colyseus.io/state/schema


# Schema Definition with Decorators

The `@type()` decorator style is the classic way of defining schema structures, and remains **fully supported**. The [schema builder](https://docs.colyseus.io/state/schema.md) (`schema()` + `t.*`) is the recommended style for new code, but both produce the identical wire format and interoperate freely: `t.array(DecoratorClass)` and `@type(BuilderClass)` both work.

Schema examples across the docs offer a **Decorators** tab, and your tab selection is remembered across pages. This page collects the decorator-specific setup and details in one place.

## TypeScript Config

The decorator style requires two settings in your `tsconfig.json`. Enable `experimentalDecorators` and disable `useDefineForClassFields`:

```json filename="tsconfig.json"
{
    "compilerOptions": {
        "experimentalDecorators": true,
        "useDefineForClassFields": false
    }
}
```

These flags are needed **only** for decorators. The [`schema()` builder](https://docs.colyseus.io/state/schema.md) works without any compiler configuration. (See [#510](https://github.com/colyseus/colyseus/issues/510) for the discussion behind `useDefineForClassFields`.)

## What is `@type()`?

> **Note:**
>
> `@type()` uses an upcoming JavaScript feature that is yet to be formally established by TC39. `type` is actually just a function imported from the `@colyseus/schema` module. By calling `type` with the `@` prefix at the property level means we're calling it as a _property decorator_. [See the decorators proposal here](https://github.com/tc39/proposal-decorators).

## Defining fields

Extend the `Schema` class and decorate each synchronizable field with `@type()`, passing one of the [primitive type strings](https://docs.colyseus.io/state/schema.md#primitive-types):

```ts filename="MyState.ts"
import { Schema, type } from "@colyseus/schema";

export class MyState extends Schema {
    @type("string") currentTurn: string;
}
```

## Child schemas

Pass the class itself to `@type()` to nest one schema inside another:

```ts filename="MyState.ts"
import { Schema, type } from "@colyseus/schema";

class World extends Schema {
    @type("number") width: number;
    @type("number") height: number;
    @type("number") items: number = 10;
}

class MyState extends Schema {
    @type(World) world: World = new World();
}
```

## Collections

Collection fields take the child type wrapped in the collection shape: `[...]` for arrays, `{ map: ... }`, `{ set: ... }`, or `{ collection: ... }`. Initialize each field with its collection instance:

```ts filename="MyState.ts"
import { Schema, ArraySchema, MapSchema, SetSchema, CollectionSchema, type } from "@colyseus/schema";

class Block extends Schema {
    @type("number") x: number;
    @type("number") y: number;
}

class Player extends Schema {
    @type([ "string" ]) animals = new ArraySchema<string>();
    @type([ Block ]) blocks = new ArraySchema<Block>();
    @type({ map: Block }) blocksByName = new MapSchema<Block>();
    @type({ set: Block }) effects = new SetSchema<Block>();
    @type({ collection: Block }) items = new CollectionSchema<Block>();
}
```

The collection instances themselves work exactly as documented in the [main reference](https://docs.colyseus.io/state/schema.md#data-types). Only the field declaration differs between the two styles.

## Default values

Use regular class property initializers:

```ts filename="MyState.ts"
import { Schema, MapSchema, type } from "@colyseus/schema";

class MyState extends Schema {
    @type("number") countdown: number = 60;
    @type({ map: Player }) players = new MapSchema<Player>();
}
```

## Inheritance

Subclasses may define their own serialized fields, and collections accept inherited types of the same base:

```ts filename="MyState.ts"
import { Schema, MapSchema, type, entity } from "@colyseus/schema";

class Item extends Schema {/* base Item fields */}

class Weapon extends Item {
    @type("number") damage: number;
}

// A subclass that adds NO new @type() fields must be registered
// explicitly with @entity: field decorators are what register a
// class with the serializer, and this class has none of its own.
@entity
class Shield extends Item {}

class Inventory extends Schema {
    @type({ map: Item }) items = new MapSchema<Item>();
}

const inventory = new Inventory();
inventory.items.set("left", new Weapon());
inventory.items.set("right", new Shield());
```

## View tags

Fields visible only to selected clients take the `@view()` decorator alongside `@type()`:

```ts filename="MyState.ts"
import { Schema, type, view } from "@colyseus/schema";

class Player extends Schema {
    // visible to all
    @type("string") name: string;

    // any `view.add(player)` will see this field
    @view() @type("number") health: number;

    // only `view.add(player, 1)` will see this field
    @view(1) @type("number") position: number;
}
```

See [State View](https://docs.colyseus.io/state/view.md) for how `StateView` works. Everything there applies equally to both definition styles.

## Delivery modifiers

`@unreliable`, `@patchOnly`, and `@fullStateOnly` control when and how a field reaches clients. Apply them alongside `@type()`:

```ts filename="MyState.ts"
import { Schema, type, unreliable, patchOnly, fullStateOnly } from "@colyseus/schema";

class Player extends Schema {
    // tick patches ride the unreliable channel (WebTransport only)
    @unreliable @type("number") aimYaw: number;

    // never in a full state sync: invisible to late joiners
    @patchOnly @type("number") flashIntensity: number;

    // full state sync only, never a tick patch
    @fullStateOnly @type("uint16") spawnIndex: number;
}
```

`@patchOnly` and `@fullStateOnly` are mutually exclusive: combining them throws at decoration time. Streaming collections use the type descriptor instead: `@type({ stream: Entity })`, with an optional `priority` key.

The semantics, use cases and cautions are documented in the [main reference → Delivery modifiers](https://docs.colyseus.io/state/schema.md#delivery-modifiers). That includes the transport requirement for `@unreliable`, which is experimental and reaches clients only over [WebTransport](https://docs.colyseus.io/server/transport/webtransport.md).

## Deprecating fields

Flag a retired field with `@deprecated()` while keeping its slot in the encoding order:

```ts filename="MyState.ts"
import { Schema, type, deprecated } from "@colyseus/schema";

class MyState extends Schema {
    @deprecated() @type("string") myField: string;

    // new fields always at the end of the structure
    @type("string") newField: string;
}
```

See [Versioning](https://docs.colyseus.io/state/schema.md#versioning-and-backwardsforwards-compatibility) for the full backwards/forwards compatibility workflow.

## Legacy: `defineTypes()`

> **Warning:**
>
> `defineTypes()` is **deprecated**: it still works, but logs a deprecation warning at runtime and in `schema-codegen`. Migrate to [`schema()` with `t.*` builders](https://docs.colyseus.io/state/schema.md). (It was briefly removed in early schema 5 releases, 5.0.0–5.0.8. Update `@colyseus/schema` if you hit a missing-export error.)

```js filename="MyState.js"
import { Schema, defineTypes } from "@colyseus/schema";

class MyState extends Schema {
}
defineTypes(MyState, {
    currentTurn: "string",
});
```

`defineTypes()` delegates to the same pipeline as the `@type()` decorator, so unlike `schema()` it still accepts raw type strings (`"string"`, `"number"`) as field values.

See the [0.18 migration guide](https://docs.colyseus.io/migrating/0.18.md) for upgrade steps.

---
Source: https://docs.colyseus.io/state/schema/decorators


# Streaming Collections

A collection that gains hundreds of entries in one tick produces one enormous patch. Every client pays for it in the same frame, and most of those entries are irrelevant to most clients.

**Streaming** spreads those additions across ticks. Each client drains a bounded number of new entries per tick, in an order you control. The nearest entities arrive first, and the rest trickle in behind them.

> **Warning:**
>
> **Experimental.** The API may still change: the shape of `t.stream()`, the priority callback, and how the per-tick budget applies. Pin your `@colyseus/schema` version if you depend on it.

## At a glance

```ts
import { schema, t } from "@colyseus/schema";

const Player = schema({ x: t.number(), y: t.number() }, "Player");
const Enemy = schema({ x: t.number(), y: t.number() }, "Enemy");

const MyState = schema({
    players: t.map(Player),
    enemies: t.stream(Enemy),
}, "MyState");
```

```ts
import { StateView } from "@colyseus/schema";

class MyRoom extends Room {
    onCreate() {
        this.state.enemies.maxPerTick = 8;   // per client, per tick (default 32)
        this.state.enemies.add(new Enemy().assign({ x: 10, y: 20 }));
    }

    onJoin(client) {
        const player = this.state.players.get(client.sessionId);

        client.view = new StateView();
        client.view.subscribe(this.state.enemies, (enemy) =>
            -((enemy.x - player.x) ** 2 + (enemy.y - player.y) ** 2));   // nearest first
    }
}
```

Three pieces carry the feature. `t.stream(Enemy)` declares the collection, `maxPerTick` caps how fast it drains, and `subscribe()` connects one client to it. That last call also takes an optional callback, which orders that client's backlog.

> **Note:**
>
> Streaming is a delivery strategy for **additions**. Once an entry reaches a client, later changes to its fields synchronize normally and don't consume the budget.

## `t.stream(Entity)`

Declares a **`StreamSchema`**, a collection keyed by a monotonic position counter rather than an index or a user key.

That position is the point. Entries keep a stable identity even as others are removed, so a client's partially-delivered view stays coherent across ticks.

> **Warning:**
>
> The element type must be a `Schema` subclass. Priority batching relies on stable ref ids, which primitives don't carry, so `t.stream("number")` is a TypeScript error. No runtime check enforces it, so plain JavaScript gets no diagnostic.

### `StreamSchema` API

| Member | Description |
|--------|-------------|
| `add(value)` | Appends an element; returns its wire position, or `-1` if already present |
| `remove(value)` | Removes an element by identity; returns whether it was present |
| `has(value)` | Whether the element is in the stream |
| `clear()` | Empties the stream |
| `size` / `length` | Number of elements |
| `forEach(cb)` | Iterates `(value, position, stream)` |
| `values()` / `entries()` / `toArray()` | Iteration helpers |
| `maxPerTick` | Additions drained per client per encode pass (default `32`) |

### Streaming an existing collection type

`.stream()` opts a regular `MapSchema`, `SetSchema` or `CollectionSchema` into the same batching, keeping that collection's own semantics:

```ts
const MyState = schema({
    pickups: t.map(Pickup).stream(),     // keyed by string, streamed
}, "MyState");
```

> **Warning:**
>
> **`.stream()` is not supported on `t.array(X)`** and throws at definition time.
>
> Array positional operations (`splice`, `unshift`, `reverse`) shift every subsequent index. Holding some additions back for a later tick while indexes move underneath them would leave clients in a state that doesn't match the server. Use `t.stream(X)` (stable positions) or `t.map(X).stream()` (keys never shift) instead.

## `maxPerTick`

The budget is **per client, per encode pass**. With `maxPerTick = 8`, a client holding 100 pending entries receives 8 this tick, 8 the next, and so on. A client with 3 pending gets all 3 immediately.

```ts
state.enemies.maxPerTick = 8;
```

Tune it against your tick rate and entry size. `maxPerTick × bytes-per-entry × tickRate` is the per-client bandwidth ceiling this stream can consume. The default of `32` suits small entities at a typical tick rate; lower it for large ones.

## Getting entries to clients

Streaming decides *how fast* entries reach a client. `view.subscribe()` decides *which* clients get them.

```ts
client.view = new StateView();
client.view.subscribe(this.state.enemies);
```

> **Warning:**
>
> **`subscribe()` is not optional.** As soon as one client holds a `StateView`, the stream stops seeding its broadcast backlog. Every entry added after that point reaches subscribed views only.
>
> Entries added earlier (in `onCreate`, before anyone joined) are already in the broadcast backlog and still reach every client. A room that skips the subscription therefore looks like it works, then silently stops delivering once the first client joins.

Subscription order doesn't matter. A view subscribed to a collection that already holds entries receives those entries too.

## Priority

Without a priority callback, pending entries drain in insertion order. With one, the highest return value emits first.

### Per client

Pass the callback as the second argument to `subscribe()`. It receives the candidate element and closes over whatever that client sorts by:

```ts
onJoin(client) {
    const player = this.state.players.get(client.sessionId);

    client.view = new StateView();
    client.view.subscribe(this.state.enemies, (enemy) =>
        -((enemy.x - player.x) ** 2 + (enemy.y - player.y) ** 2));
}
```

The anchor is the player entity itself, so it never goes stale. Move the player and the next batch reorders. TypeScript infers the element type from the collection, so neither the parameter nor the closure needs annotating.

To retarget the ordering later, subscribe again with a new callback. Pass `null` to drop it and fall back to the field's own callback.

```ts
client.view.subscribe(this.state.enemies, (enemy) => -dist2(enemy, spectatorTarget));
```

### The same order for every client

Declare the callback on the field when the ordering doesn't depend on who is watching:

```ts
const MyState = schema({
    enemies: t.stream(Enemy).priority((view, enemy) => enemy.threatLevel),
}, "MyState");
```

A per-client callback overrides this one for that client. Assigning `state.enemies.priority` at runtime replaces it for everyone.

### Keeping the callback cheap

The callback runs per client, per pending entry, on every tick with a backlog. Avoid allocation and hoist any lookup you can. Squared distance beats `Math.hypot`.

> **Warning:**
>
> Priority applies to per-view encoding only. In broadcast mode, with no `StateView` anywhere in the room, every client receives the same bytes and the backlog drains in insertion order.

## Choosing an approach

| Situation | Use |
|-----------|-----|
| Many entities spawn per tick; each client needs the nearby ones first | `t.stream(Entity)` + [`view.subscribe(collection, fn)`](#per-client) |
| Every client should see the same ordering | `t.stream(Entity).priority(fn)` |
| A keyed collection that grows in bursts | `t.map(X).stream()` |
| Ordered list with positional edits (`splice`, `unshift`) | Not streamable: use a plain `t.array(X)` |
| Whole collection is small and relevant to everyone | Plain collection, no streaming |

## Next

- [StateView](https://docs.colyseus.io/state/view.md): per-client visibility and `view.subscribe()`
- [Delivery modifiers](https://docs.colyseus.io/state/schema.md#delivery-modifiers): `.unreliable()`, `.patchOnly()` and `.fullStateOnly()`

---
Source: https://docs.colyseus.io/state/streaming


# Per-client State Visibility with `StateView`

> **Note:**
>
> This feature was introduced in version `0.16` and replaces the previously experimental `@filter()` and `@filterChildren()` decorators.

By default, the entire state is visible to all clients. However, you may want to control which parts of the state are visible to each client.

**You can do so by:**

1. Assigning a `StateView` instance to the client
2. Tag state fields with the `.view()` field modifier
3. Manually `.add()` schema instances to the `StateView`
4. Manually `.remove()` schema instances from the `StateView`

A `StateView` instance must be assigned to the `client.view`.

> **Warning:**
>
> Avoid relying on `StateView` for large datasets: it is not optimized for that yet. However, it is a great way to filter data per client. Examples: "private fields" per schema instance, "level of detail", area-based or team-owned data.

## Initializing a `StateView`

```ts filename="MyRoom.ts"
import { StateView } from "@colyseus/schema";
// ...
    onJoin(client, options) {
        client.view = new StateView();
        // ...
    }
// ...
```

> **Note:**
>
> **How serialization works**
>
> - Each `StateView` instance is going to add a new encoding step for state serialization.
> - You may re-use the same `StateView` instance for multiple clients, or create a new one for each client.
> - Internally, all "shared" properties (properties not tagged with `.view()`) are serialized first, and then each `StateView` is serialized with its own set of properties.

## Tagging fields with `.view()`

The `.view()` field modifier (or `@view()` decorator) is used to tag a field as only visible to `StateView` instances that contain that `Schema` instance.

**Schema Builder**

```ts {6} filename="MyState.ts"
const Player = schema({
    // visible to all
    name: t.string(),

    // only visible to clients containing this schema instance on their `StateView`
    position: t.number().view(),
}, "Player");
```

**Decorators**

```ts {6} filename="MyState.ts"
class Player extends Schema {
    // visible to all
    @type("string") name: string;

    // only visible to clients containing this schema instance on their `StateView`
    @view() @type("number") position: number;
}
```

In the example above, the `position` field is only visible to clients that contain this `Player` instance in their `StateView`.

### Adding a schema instance to a `StateView`

To add a schema instance to a `StateView`, call `.add()` on the `StateView` instance:

```ts {7,8} filename="MyRoom.ts"
import { StateView } from "@colyseus/schema";
// ...
    onJoin(client, options) {
        const player = new Player();
        this.state.players.set(client.sessionId, player);

        client.view = new StateView();
        client.view.add(player);
    }
```

The frontend receives either an `onAdd` or a `listen` callback, depending on where the `.view()` tag is. See [Listening for `StateView` changes on the frontend](#listening-for-stateview-changes-on-the-frontend).

### Removing a schema instance from a `StateView`

To remove a schema instance from a `StateView`, call `.remove()` on the `StateView` instance:

```typescript
client.view.remove(player);
```

The frontend receives either an `onRemove` or a `listen` callback, depending on where the `.view()` tag is.

### Checking if instance is part of `StateView`

You can check if a schema instance is part of a `StateView` by calling `.has()` on the `StateView` instance:

```typescript
if (client.view.has(player)) {
    // player is part of this client's StateView
}
```

## Specialized tags with `.view(tag: number)`

Sometimes you may want to have multiple views with different fields.

**Schema Builder**

```ts {9} filename="MyState.ts"
const Player = schema({
    // visible to all
    name: t.string(),

    // any `.add(player)` will see this field
    health: t.number().view(),

    // only `.add(player, 1)` will see this field
    position: t.number().view(1),
}, "Player");
```

**Decorators**

```ts {9} filename="MyState.ts"
class Player extends Schema {
    // visible to all
    @type("string") name: string;

    // any `.add(player)` will see this field
    @view() @type("number") health: number;

    // only `.add(player, 1)` will see this field
    @view(1) @type("number") position: number;
}
```

You can assign a numeric tag to the `.view()` modifier. That field is then only visible to clients whose `StateView` contains this `Schema` instance with the same tag:

```ts {6,7} filename="MyRoom.ts"
// ...
    onJoin(client, options) {
        const player = new Player().assign({ name: "Player 1", health: 100, position: 0 });
        this.state.players.set(client.sessionId, player);

        client.view = new StateView();
        client.view.add(player, 1); // add with tag 1 - "position" field is visible
    }
// ...
```

In the example above, only clients that added this `Player` instance with tag `1` can see the `position` field. The `health` field is visible to all clients that contain this `Player` instance in their `StateView`.

---

The following table shows the relation between type annotations and the visibility of each field on the frontend:

| Field declaration                        | Without `view.add()` | `view.add(instance)` | `view.add(instance, 1)` |
|------------------------------------------|----------------------|-------------------------|-----------------|
| `t.*(...)` / `@type(...)`                | ✅                   | ✅                       | ✅              |
| `t.*(...).view()` / `@view() @type(...)` | ❌                   | ✅                       | ✅              |
| `t.*(...).view(1)` / `@view(1) @type(...)` | ❌                 | ❌                       | ✅              |

## Items of `ArraySchema` and `MapSchema`

When you tag an array or map with `.view()`, elements added to the collection **later** must be added to the client's `StateView` individually. (Calling `view.add(collection)` also brings in the elements it holds at that moment.)

> **Note:**
>
> To grant a client every future element automatically, [subscribe to the collection](#subscribing-to-a-collection) instead of adding each element by hand.

**Schema Builder**

```ts {7} filename="MyState.ts"
const Player = schema({
    name: t.string(),
    position: t.number(),
}, "Player");

const MyState = schema({
    players: t.map(Player).view(),
}, "MyState");
```

**Decorators**

```ts {7} filename="MyState.ts"
class Player extends Schema {
    @type("string") name: string;
    @type("number") position: number;
}

class MyState extends Schema {
    @view() @type({ map: Player }) players = new MapSchema<Player>();
}
```

The instance must be assigned to the state and added to the `StateView`:

```ts {5,8} filename="MyRoom.ts"
import { StateView } from "@colyseus/schema";
// ...
    onJoin(client, options) {
        const player = new Player();
        this.state.players.set(client.sessionId, player);

        client.view = new StateView();
        client.view.add(player);
    }
// ...
```

## Subscribing to a collection

`view.add(instance)` is a **one-shot**: it grants visibility of that instance, and nothing else. For a collection that keeps gaining elements, that means calling `.add()` again for every new one. Forgetting a call silently leaves that client behind.

`view.subscribe(collection)` makes it standing. The view receives **all future content changes** of that collection, with no further bookkeeping:

```ts {7} filename="MyRoom.ts"
import { StateView } from "@colyseus/schema";
// ...
    onJoin(client, options) {
        client.view = new StateView();

        // every enemy, present and future, reaches this client
        client.view.subscribe(this.state.enemies);
    }
// ...
```

Subscribing brings in the collection's current contents as well as future ones, so it replaces the initial `view.add(collection)` rather than supplementing it. The call is idempotent. Subscribing to an already-subscribed collection is a no-op.

How new elements are delivered depends on the collection kind:

- **`ArraySchema` / `MapSchema` / `SetSchema` / `CollectionSchema`**: new children are shipped immediately, as they're added.
- **[Streamed](https://docs.colyseus.io/state/streaming.md) collections** (`t.stream(X)`, or any collection with `.stream()`): new elements enter the view's pending queue and drain a bounded number per tick, in priority order.

On a streamed collection, a second argument orders that client's backlog. The callback receives the candidate element, so it can close over whatever this client sorts by:

```ts filename="MyRoom.ts"
client.view.subscribe(this.state.enemies, (enemy) =>
    -((enemy.x - player.x) ** 2 + (enemy.y - player.y) ** 2));   // nearest first
```

Subscribing again with a new callback replaces it; `null` drops it. See [Priority](https://docs.colyseus.io/state/streaming.md#per-client) for the full picture.

> **Note:**
>
> Subscribing is per-view. If several clients share one `StateView` instance, one `subscribe()` call covers all of them.

## Listening for `StateView` changes on the frontend

The frontend has no `StateView` API. When the server adds an instance to a client's view, that client receives the data as a regular state change. You listen for it with the same [state sync callbacks](https://docs.colyseus.io/state/callbacks.md) you use for the rest of the state.

Which callback fires depends on where the `.view()` tag is:

| Tagged on the server | `view.add(instance)` triggers | `view.remove(instance)` triggers |
|---|---|---|
| The collection: `t.map(Player).view()` | `onAdd` on the collection | `onRemove` on the collection |
| A field: `position: t.number().view()` | `listen` on the field, with the value | `listen` on the field, with `undefined` |

### Tagged collections: `onAdd` and `onRemove`

When the collection is tagged, a client only sees the items in its view. Each `view.add()` and `view.remove()` call reaches the frontend as an item being added to or removed from the collection:

```ts filename="client.ts"
import { Client, Callbacks } from "@colyseus/sdk";
import type { MyRoom } from "../server/rooms/MyRoom";

const client = new Client("http://localhost:2567");
const room = await client.joinOrCreate<MyRoom>("my_room");
const callbacks = Callbacks.get(room);

// server called client.view.add(player)
callbacks.onAdd("players", (player, sessionId) => {
    console.log("player is now visible:", sessionId);
});

// server called client.view.remove(player)
callbacks.onRemove("players", (player, sessionId) => {
    console.log("player is no longer visible:", sessionId);
});
```

Items added through [`view.subscribe()`](#subscribing-to-a-collection) trigger the same `onAdd` callback.

### Tagged fields: `listen`

When only some fields are tagged, every client receives the instance itself. Its tagged fields stay `undefined` until the server adds the instance to that client's view. Listen to the field to know when it is revealed or hidden:

```ts filename="client.ts"
callbacks.onAdd("players", (player, sessionId) => {
    // player.position is undefined until the server calls client.view.add(player)
    callbacks.listen(player, "position", (value, previousValue) => {
        if (value === undefined) {
            // server called client.view.remove(player)
        } else {
            // revealed by client.view.add(player), or updated afterwards
        }
    });
});
```

Fields tagged with a [numeric tag](#specialized-tags-with-viewtag-number) behave the same way. They are revealed by `view.add(instance, tag)` with a matching tag.

> **Note:**
>
> You can register callbacks before the data arrives. An `onAdd` on a tagged collection that this client cannot see yet fires once the server adds items to its view.

---
Source: https://docs.colyseus.io/state/view


# Built-in Tools

All the tools below are included in the template projects created via `npm create colyseus-app@latest`

---

- [Playground](https://docs.colyseus.io/tools/playground.md)
- [Monitoring Panel](https://docs.colyseus.io/tools/monitoring.md)
- [Load testing](https://docs.colyseus.io/tools/loadtest.md)
- [Unit Testing](https://docs.colyseus.io/tools/unit-testing.md)

---
Source: https://docs.colyseus.io/tools


# Load Testing

The `@colyseus/loadtest` tool lets you stress test your Colyseus server by simulating multiple concurrent client connections. Each simulated client runs a custom script where you can implement bot behavior (joining rooms, sending messages, and reacting to state changes). Use it to verify how your server performs under load.

## Installation

This package is installed by default on new projects created via `npm create colyseus-app`.

```sh npm2yarn
npm install --save-dev @colyseus/loadtest
```

## Usage

Run the load test command with the following arguments:

- `script`: path to your custom client script
- `--room`: name of the room to connect to
- `--numClients`: number of simulated clients to spawn in this process (see [Running Multiple Processes](#running-multiple-processes))
- `--endpoint`: your server endpoint (defaults to `ws://localhost:2567`)

For example, to connect 50 clients into a `"battle"` room:

```sh filename="Terminal"
npx tsx loadtest/example.ts --room battle --numClients 50 --endpoint http://localhost:2567
```

[![asciicast](https://asciinema.org/a/229378.svg)](https://asciinema.org/a/229378)

## Scripting

Each simulated client executes the script you provide. Use room lifecycle events to implement bot behavior that interacts with the room during the test.

**TypeScript**

```ts filename="loadtest/example.ts"
import { Client, Room } from "@colyseus/sdk";
import { cli, Options } from "@colyseus/loadtest";

async function main(options: Options) {
    const client = new Client(options.endpoint);
    const room: Room = await client.joinOrCreate(options.roomName, {
        // your join options here...
    });

    console.log("joined successfully!");

    room.onMessage("*", (type, message) => {
        console.log("onMessage:", type, message);
    });

    room.onStateChange((state) => {
        console.log(room.sessionId, "new state:", state);
    });

    room.onError((code, message) => {
        console.log(room.sessionId, "!! ERROR !!", message);
    })

    room.onLeave((code) => {
        console.log(room.sessionId, "left.");
    });
}

cli(main);
```

**JavaScript**

```js filename="loadtest/example.js"
import { Client } from "@colyseus/sdk";
import { cli } from "@colyseus/loadtest";

async function main (options) {
    const client = new Client(options.endpoint);
    const room = await client.joinOrCreate(options.roomName, {
        // your join options here...
    });

    console.log("joined successfully!");

    room.onMessage("*", (type, message) => {
        console.log("onMessage:", type, message);
    });

    room.onStateChange((state) => {
        console.log(room.sessionId, "new state:", state);
    });

    room.onError((code, message) => {
        console.log(room.sessionId, "!! ERROR !!", message);
    })

    room.onLeave((code) => {
        console.log(room.sessionId, "left.");
    });
}

cli(main);
```

## Running Multiple Processes

A load test runs all of its simulated clients in a single Node.js process, on one CPU core. Every simulated client decodes its own copy of each state patch. The server encodes each patch only once per room and sends the same bytes to every client in it.

The decoding cost grows with the number of clients. At the default [`patchRate`](https://docs.colyseus.io/room.md#configuration-properties) of 20 patches per second, 500 clients decode 10,000 patches per second on that one core. The load test process can reach its limit before your server does. After that point, patches queue up and the results measure the load test instead of your server.

Watch the `cpu` value in the `processing` panel of the terminal UI. A value at or near 100% means the load test process is the bottleneck. Compare it with the server's CPU usage in `top` or the [Monitoring Panel](https://docs.colyseus.io/tools/monitoring.md).

To simulate more clients, split them across several processes. Run each process in its own terminal, because the terminal UI takes over the screen:

```sh filename="Terminal 1"
npx tsx loadtest/example.ts --room battle --numClients 250 --endpoint http://localhost:2567
```

```sh filename="Terminal 2"
npx tsx loadtest/example.ts --room battle --numClients 250 --endpoint http://localhost:2567
```

Run at most one load test process per CPU core. Keep the load test on a different machine from the server, so the two don't compete for cores. When you run out of cores, spread the processes across more machines.

When you split a load test across processes:

- `options.clientId` counts from `0` in each process, so it isn't unique across processes.
- Each `console.log` call redraws the terminal UI. The example script above logs every state change for demonstration. Remove per-patch logging for large tests.

---
Source: https://docs.colyseus.io/tools/loadtest


# Monitoring Panel

The Colyseus Monitoring Panel is a browser-based administration tool for inspecting and managing your multiplayer server in real time. It gives you visibility into active rooms, connected clients, and room state. It also lets you take actions like disposing rooms, disconnecting clients, or broadcasting messages.

![](https://github.com/colyseus/colyseus-monitor/blob/master/media/demo.gif?raw=1)

## Features

- List all active rooms
    - Force dispose a specific room
- Inspect a specific room
    - View room's state
    - Send/broadcast messages for a client
    - Force disconnect a client

> **Warning:**
>
> The monitoring panel exposes full control over your rooms and clients. Do not expose it in production without password protection. See [Password protection](#password-protection) below.

## Installation

This package is installed by default on new projects created via `npm create colyseus-app`.

```sh npm2yarn
npm install --save @colyseus/monitor
```

## Mounting

The monitor can be mounted in two ways.

### Standard router (recommended)

Spread `monitor()` into `createRouter`. The monitor is served at `/monitor` by default. Customize the mount path with the `prefix` option:

```ts {2,6} filename="app.config.ts"
import { defineServer, createRouter } from "colyseus";
import { monitor } from "@colyseus/monitor";

const server = defineServer({
    routes: createRouter({
        ...monitor(), // served at /monitor by default
    })
});
```

### Express middleware

Use this mode if you rely on existing Express middleware or libraries:

```ts {2,7} filename="app.config.ts"
import { defineServer } from "colyseus";
import { monitor } from "@colyseus/monitor";

const server = defineServer({
    // ...
    express: (app) => {
        app.use("/monitor", monitor());
    }
});
```

In express-middleware mode the Express mount path must match the monitor's `prefix` (default `/monitor`). The monitor dispatches on the full original URL, so a mismatched mount path silently 404s. Pass a matching `prefix` when mounting elsewhere.

## Usage

Once mounted, start your server and navigate to [http://localhost:2567/monitor](http://localhost:2567/monitor) in your browser.

If you mounted the monitor at a different path, adjust the URL accordingly.

All active rooms spawned by your server are automatically listed, along with their clients and metadata.

## Password protection

The monitoring panel exposes full control over your rooms and clients. **Do not expose it in production without password protection.** Pass a guard middleware through the monitor's `use` option. Colyseus ships with a built-in [`basicAuth`](https://docs.colyseus.io/server/http-routes.md#basic-authentication):

```ts {1,4,8} filename="app.config.ts"
import { defineServer, createRouter, basicAuth } from "colyseus";
import { monitor } from "@colyseus/monitor";

const guard = basicAuth({ users: { admin: "s3cret" } });

const server = defineServer({
    routes: createRouter({
        ...monitor({ use: [guard] }),
    })
});
```

The `use` option works in both mounting modes, so you can pass the same guard when mounting via Express:

```ts filename="app.config.ts"
app.use("/monitor", monitor({ use: [guard] }));
```

See [HTTP Routes → Basic authentication](https://docs.colyseus.io/server/http-routes.md#basic-authentication) for `basicAuth` options and behavior.

## Custom room listing columns

Customize which columns appear in the room list by passing a `columns` option:

```ts filename="app.config.ts"
import { defineServer, createRouter } from "colyseus";
import { monitor } from "@colyseus/monitor";

const server = defineServer({
    routes: createRouter({
        ...monitor({
            columns: [
                'roomId',
                'name',
                'clients',
                { metadata: "spectators" }, // display 'spectators' from metadata
                'locked',
                'elapsedTime',
            ],
        }),
    })
});
```

If unspecified, the default columns are: `['roomId', 'name', 'clients', 'maxClients', 'locked', 'elapsedTime']`.

---
Source: https://docs.colyseus.io/tools/monitoring


# Playground

The Colyseus Playground is a browser-based development tool for real-time debugging of your multiplayer server. The Playground lets you create and manage WebSocket room connections, inspect synchronized state, send and receive messages, and test HTTP endpoints. All of it works without writing any client-side code.

![](https://docs.colyseus.io/playground/rooms.webp)

## Features

- Create room connections via `joinOrCreate` / `create` / `join`
- When `joinById` is selected, provides a list of active rooms by id
- Authenticate using credentials auto-detected from [ Auth Module](https://docs.colyseus.io/auth/module.md)
- Simulate room connection drops to test reconnection logic
- Visualize the client state in JSON format
- Allow the client to send messages by type (auto-detected)
- Built-in viewer and tester for server [HTTP endpoints](https://docs.colyseus.io/server/http-routes.md) (similar to Postman)

> **Warning:**
>
> The playground exposes full access to your rooms and server endpoints. Do not expose it in production without password protection. See [Password protection](#password-protection) below.

## Installation

This package is installed by default on new projects created via `npm create colyseus-app`.

```sh npm2yarn
npm install --save @colyseus/playground
```

## Mounting

The playground can be mounted in two ways.

### Standard router (recommended)

Spread `playground()` into `createRouter` and set the `prefix` to the path you want it served from:

```ts {2,6} filename="app.config.ts"
import { defineServer, createRouter } from "colyseus";
import { playground } from "@colyseus/playground";

const server = defineServer({
    routes: createRouter({
        ...playground({ prefix: "/playground" }),
    })
});
```

> **Note:**
>
> `prefix` defaults to `''`, which serves the playground from the root. When spreading into `createRouter` you almost always want to pass an explicit `prefix` such as `"/playground"`.

### Express middleware

Use this mode if you rely on existing Express middleware or libraries:

```ts {2,7} filename="app.config.ts"
import { defineServer } from "colyseus";
import { playground } from "@colyseus/playground";

const server = defineServer({
    // ...
    express: (app) => {
        app.use("/playground", playground());
    }
});
```

In express-middleware mode the `prefix` option is ignored. Express strips its own mount path before dispatching.

## Usage

Once mounted, start your server and navigate to [http://localhost:2567/playground](http://localhost:2567/playground) in your browser.

If you mounted the playground at a different path, adjust the URL accordingly.

## Password protection

The playground exposes full access to your rooms and server endpoints. **Do not expose it in production without password protection.** Pass a guard middleware through the playground's `use` option. Colyseus ships with a built-in [`basicAuth`](https://docs.colyseus.io/server/http-routes.md#basic-authentication):

```ts {1,4,8} filename="app.config.ts"
import { defineServer, createRouter, basicAuth } from "colyseus";
import { playground } from "@colyseus/playground";

const guard = basicAuth({ users: { admin: "s3cret" } });

const server = defineServer({
    routes: createRouter({
        ...playground({ prefix: "/playground", use: [guard] }),
    })
});
```

The `use` option works in both mounting modes, so you can pass the same guard when mounting via Express:

```ts filename="app.config.ts"
app.use("/playground", playground({ use: [guard] }));
```

See [HTTP Routes → Basic authentication](https://docs.colyseus.io/server/http-routes.md#basic-authentication) for `basicAuth` options and behavior.

## API endpoints

All [HTTP routes](https://docs.colyseus.io/server/http-routes.md) registered on your server are automatically detected and listed here, letting you test requests and inspect responses directly from the browser.

![](https://docs.colyseus.io/playground/endpoints.webp)

## Contribute

This tool is built using React and TailwindCSS, making it easy for community members to contribute. See [source-code](https://github.com/colyseus/colyseus/tree/master/packages/playground)

---
Source: https://docs.colyseus.io/tools/playground


# Unit Testing Your Server

The `@colyseus/testing` package provides utility methods for testing your Colyseus application. It simulates client connections and message exchange using the JavaScript SDK, so you can validate both server and client behavior in a single test.

> **Note:**
>
> Use it with your favorite testing framework, such as [Vitest](https://vitest.dev/), [Mocha](https://mochajs.org/), or [Jest](https://jestjs.io/).

## Installation

This package is installed by default on new projects created via `npm create colyseus-app`.

```sh npm2yarn
npm install --save-dev @colyseus/testing
```

## Getting Started

Boot the test server with your `app.config.ts`, then create rooms and connect simulated clients inside each test case.

**Mocha + TypeScript**

```ts filename="App.test.ts"
import assert from "assert";
import { ColyseusTestServer, boot } from "@colyseus/testing";

// import your "app.config.ts" file here.
import appConfig from "../src/app.config";

describe("testing your Colyseus app", () => {
  let colyseus: ColyseusTestServer;

  before(async () => colyseus = await boot(appConfig));
  after(async () => colyseus.shutdown());

  beforeEach(async () => await colyseus.cleanup());

  it("connecting into a room", async() => {
    // `room` is the backend Room instance reference.
    const room = await colyseus.createRoom("my_room", {});

    // `client1` is the frontend `Room` instance reference (from the JavaScript SDK)
    const client1 = await colyseus.connectTo(room);

    // make your assertions
    assert.strictEqual(client1.sessionId, room.clients[0].sessionId);
  });
});
```

**Jest + TypeScript**

```ts filename="App.test.ts"
import { ColyseusTestServer, boot } from "@colyseus/testing";

// import your "app.config.ts" file here.
import appConfig from "../src/app.config";

describe("testing your Colyseus app", () => {
  let colyseus: ColyseusTestServer;

  beforeAll(async () => colyseus = await boot(appConfig));
  afterAll(async () => await colyseus.shutdown());

  beforeEach(async () => await colyseus.cleanup());

  it("connecting into a room", async() => {
    // `room` is the backend Room instance reference.
    const room = await colyseus.createRoom("my_room", {});

    // `client1` is the frontend `Room` instance reference (from the JavaScript SDK)
    const client1 = await colyseus.connectTo(room);

    // make your assertions
    expect(client1.sessionId).toEqual(room.clients[0].sessionId);
  });
});
```

Then run your tests with the framework of the tab you followed:

```sh filename="Terminal"
npx mocha --require ts-node/register App.test.ts   # Mocha
npx jest                                           # Jest
```

## Best Practices

- Assert on both server and client state after simulating message exchange.
- Create a fresh room in each test. Rooms are disposed between tests via `colyseus.cleanup()`, so do not reuse room instances.
- Always declare test cases with `async`.
- [Await for the server or client to process pending actions](#server-side-utilities) before running assertions.

## Server-side Utilities

When sending messages between server and client, wait for the server to process the message before making assertions.

### Wait For Message Type

Wait for a particular message `type` to arrive in the server.

```ts {8} filename="App.test.ts"
it("should receive message", async() => {
    const room = await colyseus.createRoom("my_room");
    const client1 = await colyseus.connectTo(room);

    client1.send("foo", "payload");

    // wait for a specific message
    const [ client, message ] = await room.waitForMessage("foo");

    assert.strictEqual(client.sessionId, client1.sessionId);
    assert.strictEqual("payload", message);
});
```

### Wait For Next Message

Wait for any next message to arrive in the server.

**Parameters**

- `delay: number` - additional delay after `onMessage` has been called in the backend, in milliseconds (optional)

```ts {11} filename="App.test.ts"
it("should receive message", async() => {
    const room = await colyseus.createRoom("my_room");
    const client1 = await colyseus.connectTo(room);

    let received = false;
    room.onMessage("foo", (client, message) => {
        received = true;
    });

    client1.send("foo");
    await room.waitForNextMessage();

    assert.ok(received);
});
```

### Wait For Next Patch

Wait for the server to send the latest patched state to all clients.

```ts {5} filename="App.test.ts"
it("client state must match server's after patch is received", async() => {
    const room = await colyseus.createRoom("my_room");
    const client1 = await colyseus.connectTo(room);

    await room.waitForNextPatch();

    assert.deepStrictEqual(client1.state.toJSON(), room.state.toJSON());
});
```

### Wait For Next Timestep

Wait for the next timestep to complete. Works with either loop: `setTimestep()` and `setFixedTimestep()` both drive the same interval.

```ts {5} filename="App.test.ts"
it("should assert something after room's timestep", async() => {
    const room = await colyseus.createRoom("my_room");
    const client1 = await colyseus.connectTo(room);

    await room.waitForNextTimestep();

    // assuming the room's state has a "tick" property that updates during setTimestep()
    assert.strictEqual(room.state.tick, 1);
});
```

> **Note:**
>
> `waitForNextSimulationTick()` is the previous name and still works (it forwards). Requires `@colyseus/testing` 0.18.2 or newer for `waitForNextTimestep()`.

## Client-side Utilities

You can call any frontend SDK methods through `colyseus.sdk` to simulate client behavior:

- [`colyseus.sdk.joinOrCreate()`](https://docs.colyseus.io/sdk.md#join-or-create-recommended)
- [`colyseus.sdk.create()`](https://docs.colyseus.io/sdk.md#other-join-methods)
- [`colyseus.sdk.join()`](https://docs.colyseus.io/sdk.md#other-join-methods)
- [`colyseus.sdk.joinById()`](https://docs.colyseus.io/sdk.md#other-join-methods)

```ts filename="App.test.ts"
it("should connect into battle_room with options x, y, z", async () => {
    const client = await colyseus.sdk.joinOrCreate("battle_room", {
        a: "a",
        b: "b",
        c: "c"
    });
    assert.ok(client.sessionId);
});
```

### Wait for Next Patch

Wait for client state to be in sync with the server.

```ts {3} filename="App.test.ts"
it("should do xyz after receiving message 'x'", async () => {
    const client = await colyseus.sdk.joinOrCreate("battle_room");
    await client.waitForNextPatch();
    // perform assertions after client has received a message
});
```

### Wait for Message Type

Wait for a particular message `type` to arrive in the client.

```ts {5} filename="App.test.ts"
it("should do xyz after receiving message 'x'", async () => {
    const client = await colyseus.sdk.joinOrCreate("battle_room");
    client.send("ask-for-x");

    await client.waitForMessage("received-x");
    // perform assertions after client has received "received-x" message type.
});
```

### Wait for Next Message

Wait for any next message to arrive in the client.

```ts {5} filename="App.test.ts"
it("should do xyz after receiving message 'x'", async () => {
    const client = await colyseus.sdk.joinOrCreate("battle_room");
    client.send("ask-for-x");

    await client.waitForNextMessage();
    // perform assertions after client has received a message
});
```

## Testing HTTP Routes

The `@colyseus/testing` package also provides an HTTP client for testing your custom [HTTP routes](https://docs.colyseus.io/server/http-routes.md):

- `colyseus.http.get(url, opts)`
- `colyseus.http.post(url, opts)`
- `colyseus.http.patch(url, opts)`
- `colyseus.http.delete(url, opts)`
- `colyseus.http.put(url, opts)`

```ts filename="App.test.ts"
it("should get json data", async () => {
    const response = await colyseus.http.get("/");

    // "data" is the response body
    assert.deepStrictEqual({ success: true }, response.data);

    // access to response headers.
    assert.strictEqual('header value', response.headers['some-header']);
});
```

---
Source: https://docs.colyseus.io/tools/unit-testing