# Overview

> What IRT is, what it runs for your project, and how the parts fit together.

IRT hosts the whole multiplayer stack of a web game. You write the room
code and the client; IRT runs the rooms, serves the site, carries voice
between players and gives your backend, if you have one, an API and
webhooks.

IRT is in development and invite-only. These docs describe the first
release. Where something isn't settled yet, the page says so.

## What IRT runs for a project

**Rooms.** A room is one running game instance, addressed by a room ID.
Your room code runs in a room host, a Node process inside a Firecracker
VM that belongs to your tenant alone. A room host runs many rooms of the
same build, and each room starts, hibernates and stops on its own.

**State sync.** Rooms declare typed entities. Changes go to clients as
binary deltas, encoded once per tick, and interest keys decide which
entities each connection sees, so a voxel world or a map with many NPCs
sends each player only what is near them.

**Sites.** A build can include your web client. It's served from
`<project>.irt-serve.com` and goes live together with the room code it
was built against.

**Voice.** Rooms can get a voice server. Who hears whom comes from the
room: by default each listener hears the closest speakers it can see.

**Prediction.** The client SDK includes a prediction library built around
a step function shared with the room, for games that need responsive
movement, such as shooters.

## How the parts connect

```
browser ── WebTransport or WebSocket ──> router (eu.irt.io) ──> room host in a VM
   │                                                                   │
   └── site from <project>.irt-serve.com           room state in object storage
```

- Clients connect to the router of a region. The first region is `eu`,
  at `eu.irt.io`. WebTransport is tried first, with WebSocket as the
  fallback.
- The router authenticates the connection with a player token, or as a
  guest when the project allows guests, and forwards it to the room host
  that runs the room.
- When the last connection leaves, the room hibernates: its room state
  goes to object storage and it costs no room-hours. The next connection
  wakes it. See [How rooms hibernate and wake](/docs/hibernation).
- Your backend, if you have one, creates and deletes rooms, sends
  messages into them and reads their state through the
  [HTTP API](/docs/http-api), and hears about them through
  [webhooks](/docs/webhooks).

Games with no backend are a first-class case: project settings let
clients join as guests, create rooms, join by code and list public rooms.

## What you use

| Tool | For |
|---|---|
| The `irt` CLI | Logging in, running rooms and the site locally, testing, deploying, logs |
| The dashboard at `app.irt.io` | Projects, settings, keys, secrets, builds, rooms, logs, usage |
| The HTTP API at `api.irt.io/v1` | Everything the dashboard does, for backends and CI |
| `@irt/server` | Signing player tokens in your backend |
| `@irt/testing` | Running rooms in process in tests, with fake clients and a controlled clock |

## Next

- [Concepts](/docs/concepts) defines the words used everywhere in these
  docs.
- [Deploying with the CLI](/docs/cli) walks through a project from login
  to live.
- [Limits](/docs/limits) lists the numbers rooms work within.
- [Self-hosting](/docs/self-hosting) runs a build on your own machine
  with the open-source room host.
- [Building with a coding agent](/docs/guides/agents) is the whole
  integration on one page, for agents and people in a hurry.
- [Engines and frameworks](/docs/integrations/overview) shows the client
  in [Phaser](/docs/integrations/phaser), [PixiJS](/docs/integrations/pixi),
  [Three.js](/docs/integrations/three), [Babylon.js](/docs/integrations/babylon)
  and [React](/docs/integrations/react).
- Coming from another framework? There are migration guides from
  [Colyseus](/docs/migrate/colyseus), [Playroom Kit](/docs/migrate/playroom)
  and [Socket.IO](/docs/migrate/socket-io).

---

# Concepts

> The terms IRT uses for tenants, projects, rooms and the infrastructure that runs them.

IRT uses these words consistently in the docs, the dashboard, the API and
logs. Two rules matter most: **hibernate** and **wake** are things rooms
do, and a room's saved data is its **room state**.

## Your account

**Tenant.** Your account. Your rooms run in VMs that are never shared with
another tenant.

**Project.** One game or app, with its own settings, secrets, keys and
builds. A project has a slug, unique across IRT, used in URLs and in its
site's address: `my-game` is served at `my-game.irt-serve.com`. There are
no environments inside a project; use a separate project for staging.

**Build.** A deployable version of a project: its bundled room code and,
optionally, its site. One build is live at a time. Making a build live
switches the site at once and moves rooms to it according to the
project's `rooms.buildUpdate` setting.

**Site.** A project's static files, such as its web client, served from
`<project>.irt-serve.com`. Your content is never served from `irt.io`.

**Backend.** Your own server-side code outside rooms, if you have one. It
talks to IRT through the [HTTP API](/docs/http-api) and
[webhooks](/docs/webhooks), and signs [player tokens](/docs/player-tokens).

## Rooms

**Room.** One running game instance, addressed by a room ID that is 1 to
64 characters of `A-Z`, `a-z`, `0-9`, `_` and `-`, unique within the
project. Rooms are the unit of pricing.

**Room type.** One of the named room definitions a build declares in
`irt.config.ts`'s `rooms`, such as a `lobby` and a `match`, each with its
own room module, schema, room state version and migrations, so the
rooms of one project share its players and player data. A room's type is
set when it's created and never changes. A create, quick join or
connection that names no type gets the type named `default`, which a
project with `room` instead of `rooms` has as its only type; a build
without one needs a type named every time. A connection for another type
than its room's closes with 4015. A type can also be native, with no room
code of yours: a **native room** runs only IRT's compiled code, natively
on the host rather than in a VM. It sends each message on to the other
players and keeps presence and a leader, and with a schema whose entity
kinds declare rules, players spawn, own and write its entities. (Native
here means native to IRT, not a native, non-web client.) A type may set
its own room size, `maxPlayers` and retention.

**Room host.** A Node process inside a VM that runs one or more rooms of
the same build, of any of its standard room types. Rooms in a room host start, hibernate and stop
independently. An exception in one room stops only that room.

**Room size.** A room's class: standard, large or extra large. It sets
the room's connection limit, memory, CPU and price. Sizes are
provisional until launch.

**Room-hour.** The unit rooms are billed in: an hour of a room from the
start of a wake until it has hibernated or stopped, priced by room size.
It's counted outside the VM, by IRT's host daemon.

**Room state.** The serialized state of a room, kept in object storage
while it hibernates. Entities, `room.state` and private state are room
state, saved and restored without any code of yours.

**Managed store.** How the IRT SDK saves room state: each tick's changes
are streamed out of the VM as they happen, so a crashed room host
restarts its rooms with nothing lost.

**Checkpoint.** Saving room state while the room keeps running, for crash
safety.

**Hibernate.** A room saves its room state and is removed from its room
host. It happens 30 seconds after the last connection leaves, or when
the room asks. The room host keeps running its other rooms.

**Wake.** Starting a hibernated room again, in any room host of the same
build, and restoring its room state. A connection or an API call to a
hibernated room wakes it.

### Lifecycle

```
starting -> active -> hibernating -> hibernated -> waking -> active
                \                                              |
                 +------------------> stopped <----------------+
```

`stopped` means the room was deleted and its room state may be removed.
The API reports a room's `status` as `active`, `waking` or `hibernated`.
A room created through the API is `hibernated` until its first
connection, and that first start shows as `waking` to the client, though
it runs `onCreate`.

## Connections and sync

**Connection.** One client's WebTransport or WebSocket session with a
room. A player has one connection per room: connecting again closes the
older connection.

**Player token.** A short-lived JWT your backend signs to say who a player
is. Projects that allow guests can skip it. See
[Player tokens](/docs/player-tokens).

**Unreliable message.** A message that may be dropped or arrive out of
order, for data where only the newest value matters. Sent as a
WebTransport datagram, or over WebSocket in order with stale messages
dropped when the socket backs up.

**Tick.** One fixed-timestep step of a room's simulation, run by the IRT
SDK's tick scheduler.

**Entity.** A synced object of a declared kind in a room, with typed
fields such as `f32`, `u8`, `string` and `bytes`.

**State update.** A message from a room telling a client the simulation
state at a tick: which entities entered its view, which changed, which
left. A client applies each update atomically.

**Interest key.** A value, such as a grid cell, a team or a chunk, that
entities have and connections subscribe to. A connection sees the
entities that share a key with it.

**Stepper.** A simulation step shared by a room and its clients. The room
runs it every tick; the prediction library runs the same step on the
client to predict the local player.

## Infrastructure

**Region.** A geographic location with its own hosts and router. A room
runs in one region. The first region is `eu`.

**Router.** The edge clients connect to, at `eu.irt.io` for `eu`. It
authenticates connections, enforces limits, holds connections while a
room wakes and forwards them to the room host running the room.

**VM.** A Firecracker microVM. Each belongs to one tenant and runs many
rooms. VMs start from a base snapshot, and stop 5 minutes after their
last room hibernates.

**Voice server.** The part of a region that forwards audio between a
room's connections. It runs outside VMs and runs no tenant code.

---

# Quickstart

> Build, test and deploy a small multiplayer room and its web client from scratch.

This guide builds "dots": every player is a dot on a shared board, a
click moves your dot, the room counts everyone's moves, and each player
sees a count of their own. It uses the four packages a game needs:

| Package | Used in | What it is |
|---|---|---|
| `@irt/room` | room code | `defineRoom`, entities, interest, steppers |
| `@irt/client` | the web client | `connect`, the entity store, prediction |
| `@irt/testing` | tests | rooms in process with test clients and a test clock |
| `@irt/cli` | your shell | the `irt` command: `init`, `dev`, `test`, `deploy` |

You need Node 24 or later. The CLI is `@irt/cli` on npm; the name `irt`
there belongs to someone else, so run it with `npx @irt/cli`.

## 1. Create the project

```sh
npx @irt/cli login
npx @irt/cli init dots --project dots
cd dots
npm install
npx @irt/cli projects create dots
```

`irt login` opens `https://app.irt.io/device` and stores a token in
`~/.config/irt/credentials.json`. `irt init` writes the files below for
the project slug `dots`, and `irt projects create dots` creates the
project in your account. A slug is 3 to 40 lowercase letters, digits and
single hyphens, starting with a letter, and is never reused, so if `dots`
is taken, pick another and use it in both commands.

| File | Contents |
|---|---|
| `irt.config.ts` | The project's slug, room module, site and settings |
| `package.json` | The four packages, esbuild, and scripts for `irt dev`, `irt test`, `tsc --noEmit` (`typecheck`), `irt deploy` and `build:web` |
| `build-web.mjs` | Bundles and minifies `web/main.ts` into `dist/` with esbuild, splitting each dynamic `import()` into a chunk, with hashed file names that it writes into `dist/index.html`; `site.build` runs it as `npm run build:web` |
| `src/schema.ts` | The schema the room and the client share |
| `src/room.ts` | The room code |
| `src/room.test.ts` | A test with `@irt/testing` |
| `web/index.html`, `web/main.ts` | A web client with no framework |

```ts
// irt.config.ts
import { defineConfig } from "@irt/cli/config";

export default defineConfig({
  project: "dots",
  room: "src/room.ts",
  site: { dir: "dist", build: "npm run build:web", crossOriginIsolated: false },
});
```

The slug lives only here: the web client imports it from this file. The
rest of this guide replaces the files in `src/` and `web/main.ts` with
the dots game.

## 2. Declare the schema

The schema lists the room's entity kinds and its shared and private
state. The room and every client import the same module, so their schema
hashes match; a client built against a different schema is refused with
close code 4004.

```ts
// src/schema.ts
import { defineSchema, entity } from "@irt/room";

export const Player = entity("player", {
  owner: "string",
  x: "f32",
  y: "f32",
});

/** Shared state: every connection sees it. */
export const Board = entity("board", { moves: "u32" });

/** Private state: only its own player sees it, and it outlasts a visit. */
export const Mine = entity("mine", { moves: "u32" });

export const schema = defineSchema({ state: Board, private: Mine, entities: [Player] });
```

`@irt/client` exports the same `defineSchema` and `entity`, so the module
can import from either package.

## 3. Write the room

```ts
// src/room.ts
import { defineRoom, type RoomEntity } from "@irt/room";
import { Player, schema } from "./schema.js";

const SIZE = 100;
const clamp = (v: number) => Math.min(SIZE, Math.max(0, v));

export default defineRoom({
  schema,
  tickRate: 20,
  onJoin(room, conn) {
    // After a room host restart, the player's dot from before is still here.
    const existing = [...room.entities.all(Player)].find((p) => p.owner === conn.player);
    conn.data.player =
      existing ??
      room.entities.create(Player, {
        owner: conn.player,
        x: Math.random() * SIZE,
        y: Math.random() * SIZE,
      });
  },
  onMessage(room, conn, message) {
    const m = message as { type?: unknown; x?: unknown; y?: unknown };
    if (m.type !== "move" || typeof m.x !== "number" || typeof m.y !== "number") return;
    const player = conn.data.player as RoomEntity<typeof Player>;
    player.x = clamp(m.x);
    player.y = clamp(m.y);
    room.state.moves += 1;
    room.private(conn).moves += 1;
  },
  onPlayerLeave(room, player) {
    for (const e of room.entities.all(Player)) if (e.owner === player) room.entities.delete(e);
  },
});
```

The room module's default export is the result of `defineRoom`. Setting
an entity's field records the change; at the end of each tick the room
sends every client a state update with what changed.

Each piece of data here lasts as long as it should:

- A player's dot is an entity created in `onJoin` and deleted in
  `onLeave`, so it's on the board only while they're connected.
  `onLeave` runs whenever a connection closes, and for every open
  connection before the room hibernates.
- The board's move count is `room.state`, which every player sees.
- Each player's own count is private state, kept by player ID: it comes
  back when they rejoin, for up to 24 hours after they left by default.

Entities, `room.state` and private state are room state: they're saved
when the room hibernates and restored when it wakes, with no code of
yours. If the room host crashes, the room restarts from its room state
without running `onLeave`, and `onJoin` runs again as players reconnect,
which is why it looks for an existing dot. See
[Where player data lives](/docs/guides/state-sync#where-player-data-lives).

## 4. Test it

```ts
// src/room.test.ts
import { testRoom } from "@irt/testing";
import { expect, test } from "vitest";
import room from "./room.js";
import { Player } from "./schema.js";

test("a move reaches every player and is counted", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  const bob = await t.connect({ player: "bob" });

  alice.send({ type: "move", x: 10, y: 20 });
  await t.host.tick();

  expect(bob.view(Player).find((p) => p.owner === "alice")).toMatchObject({ x: 10, y: 20 });
  expect(t.live.state.moves).toBe(1);
  expect(alice.private.moves).toBe(1);
  expect(bob.private.moves).toBe(0);
});

test("the counts survive hibernation, and the dot doesn't", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  alice.send({ type: "move", x: 1, y: 1 });
  await t.host.tick();
  await alice.leave();
  await t.hibernate();

  const back = await t.connect({ player: "alice" });
  expect(back.client.state.moves).toBe(1);
  expect(back.private.moves).toBe(1);
  expect(back.view(Player)).toHaveLength(1);
});

test("a crash keeps the player's dot", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  alice.send({ type: "move", x: 5, y: 5 });
  await t.host.tick();
  await t.host.crash();
  await alice.reconnected();
  expect(alice.view(Player)).toMatchObject([{ owner: "alice", x: 5, y: 5 }]);
});
```

```sh
npx @irt/cli test
```

Time in a test room moves only when the test moves it: `t.host.tick()`
runs one tick. See [@irt/testing](/docs/reference/testing).

## 5. Write the client

```ts
// web/main.ts
import { connect } from "@irt/client";
import config from "../irt.config.js";
import { Player, schema } from "../src/schema.js";

// irt dev serves the site and the room host on one origin; deployed sites use the region's router.
const router = location.hostname.endsWith(".irt-serve.com") ? "wss://eu.irt.io" : location.origin;

const canvas = document.querySelector("canvas")!;
const ctx = canvas.getContext("2d")!;
const status = document.querySelector("#status")!;

const room = await connect({
  router,
  project: config.project,
  room: "main",
  schema,
  onWaking: () => (status.textContent = "Starting the room"),
});
status.textContent = `Connected as ${room.player}`;
room.on("disconnected", () => (status.textContent = "Reconnecting"));
room.on("restored", () => (status.textContent = `Connected as ${room.player}`));
room.on("closed", (error) => (status.textContent = error.message));

const positions = room.interpolate(Player, ["x", "y"]);

canvas.addEventListener("click", (ev) => {
  const scale = 100 / canvas.width;
  room.send({ type: "move", x: ev.offsetX * scale, y: ev.offsetY * scale });
});

function draw() {
  ctx.clearRect(0, 0, canvas.width, canvas.height);
  const scale = canvas.width / 100;
  for (const p of room.entities.all(Player)) {
    const { x, y } = positions.get(p);
    ctx.fillStyle = p.owner === room.player ? "crimson" : "steelblue";
    ctx.beginPath();
    ctx.arc(x * scale, y * scale, 6, 0, Math.PI * 2);
    ctx.fill();
  }
  ctx.fillStyle = "black";
  ctx.fillText(`moves: ${room.state.moves}, yours: ${room.private.moves}`, 8, 16);
  requestAnimationFrame(draw);
}
draw();
```

The router address is chosen the way the scaffolded client chooses it:
`irt dev` serves the site and the room host on one origin, so locally the
client connects to `location.origin`; on `<slug>.irt-serve.com` it
connects to the region's router, `wss://eu.irt.io`, which `irt deploy`
prints.

`await connect(...)` resolves once the client holds the room's full
state, so `room.state` and `room.private` are set from then on. Without
a `token`, the client joins as a guest; the guest token is kept in
`localStorage`, so a reload, another tab or a browser restart keeps the
same player ID and the same private state.

## 6. Run it locally

```sh
npx @irt/cli dev
```

`irt dev` builds the site with `npm run build:web`, runs a local room
host, and serves both on `http://127.0.0.1:7350` with the same headers
the hosted site gets. Open it, and open it again in a private window or
another browser, and click. Two tabs of one browser share a guest, so
they'd be the same player, and the newer tab would close the older one
with 4012. It rebuilds and restarts the room host when a file changes.

## 7. Deploy

```sh
npx @irt/cli deploy
```

This bundles the room and the site into a build, uploads it and makes it
live, then prints the site's address, `https://dots.irt-serve.com`, and
the router its client connects to, `wss://eu.irt.io`. The first client
to connect creates the room, as under `irt dev`, because
`players.createRooms` is on in `irt.config.ts`. With it off, connecting
to a room that was never created closes with 4002, and rooms are created
with `irt rooms create <id>` or by your backend; see
[Games without a backend](/docs/no-backend). See
[Builds and deploys](/docs/builds) for what a deploy does to clients
and rooms.

## Common mistakes

- **Importing the schema twice under different declarations.** The room
  and client must build the schema from the same module. Two copies
  that differ in a field name, type or order give different hashes, and
  the client fails with 4004.
- **Trusting message contents.** `onMessage` receives whatever the client
  sent. Check types and ranges as the room above does before writing
  them to entities.
- **Keeping a player's score on their entity.** The entity is deleted in
  `onLeave`, which also runs before the room hibernates. Keep it in
  private state or `room.state`.
- **Creating a second entity for a player in `onJoin`.** After a room
  host crash the old one is still there; find it first.
- **Writing a client entity.** Entities on the client are read-only; a
  write throws. Send a message, or use [prediction](/docs/guides/prediction)
  for the local player.
- **Calling `send` before `connect` resolves.** It throws. Await
  `connect` first.
- **Advancing nothing in a test.** State updates go out at the end of a
  tick, so assert after `await t.host.tick()`.

---

# Building with a coding agent

> The whole IRT integration on one page, sized for a coding agent's context: the room and client contract, state sync, ownership, prediction, calls, testing, deploying and the mistakes to avoid.

This page is the IRT integration in one place, for coding agents and for
people who want the short version. It's also served alone as
[/llms-small.txt](/llms-small.txt). Every section links to the full page.
For an agent working in a project, `npx irt skill install` writes these
rules as a Claude Code skill to `.claude/skills/irt/SKILL.md`, and
[`irt mcp`](/docs/reference/mcp) is an MCP server that lets the agent
search the docs and read the project's builds, rooms and logs.

## What IRT is

IRT hosts a web game's multiplayer: **rooms** (one running game instance
each, addressed by a room ID) run your TypeScript room code in Node on
IRT's machines, sync typed state to clients as binary deltas, hibernate
to object storage when empty and wake when someone connects. A build can
include the game's **site**, served at `https://<slug>.irt-serve.com`.

| Package | Where | What |
|---|---|---|
| `@irt/room` | room code, shared modules | `defineRoom`, `defineSchema`, `entity`, `json`, `defineStepper`, `grid`, `combine`, `CloseCode`, `DataError` |
| `@irt/client` | browser and Node clients | `connect`, `RoomClient`, `IrtError`, `createRoom`, `joinByCode`, `listPublic`, `dataClient`, `DataError`, and the same `defineSchema`, `entity`, `defineStepper` |
| `@irt/testing` | tests | `testRoom`, `createTestHost`, `RoomStoppedError` |
| `@irt/cli` | shell, `npx irt` | `init`, `dev`, `test`, `build`, `deploy`, `logs`, `rooms`, `secrets`, `projects`, `skill`, `mcp` |

Node 24 or later. The npm package is `@irt/cli`; inside a project that has
it as a devDependency, `npx irt <command>` runs it, and `npx @irt/cli` works
anywhere.

```sh
npx @irt/cli init my-game --project my-game   # scaffold
cd my-game && npm install
npx irt projects create my-game               # once, after npx irt login
npx irt dev                                   # room host and site on http://127.0.0.1:7350
npx irt test                                  # vitest
npx irt deploy                                # build, upload, make live
```

A project: `irt.config.ts` (slug, room module, site, settings),
`src/schema.ts` (shared by room and client), `src/room.ts` (default export
`defineRoom(...)`), `src/room.test.ts`, and `web/` for the client.

## Schema

All synced state is **entities** of declared kinds. The room and its
clients import one schema module; its hash must match exactly or the
client is closed with 4004.

```ts
// shared.ts
import { defineCalls, defineSchema, defineStepper, entity, json } from "@irt/room";

export const Runner = entity("runner", { owner: "string", x: "f32", y: "f32", score: "u16" });
export const Flag = entity("flag", { x: "f32", y: "f32" });
export const Aim = entity("aim", { angle: "f32" }, { writable: ["angle"] });
export const Match = entity("match", { round: "u16", endsAt: "u32", scores: json<Record<string, number>>() });
export const Mine = entity("mine", { coins: "u32", volume: "u8" }, { writable: ["volume"] });

export const schema = defineSchema({
  state: Match,
  private: Mine,
  entities: [Runner, Flag, Aim],
  // Typed calls: the room's handlers and the client's room.call() are checked against these.
  calls: defineCalls<{ buy(args: { price: number }): { coins: number } }>({
    buy(raw) {
      const price = (raw as { price?: unknown } | null)?.price;
      if (typeof price !== "number" || !Number.isInteger(price) || price < 0) throw new Error("price must be a whole number");
      return { price };
    },
  }),
});

export interface Input {
  dx: number;
  dy: number;
}

export const stepper = defineStepper<Input>({
  parseInput(raw) {
    const i = raw as Partial<Input>;
    if (typeof i.dx !== "number" || typeof i.dy !== "number" || Math.abs(i.dx) > 1 || Math.abs(i.dy) > 1) {
      throw new TypeError("input is { dx, dy } with each from -1 to 1");
    }
    return { dx: i.dx, dy: i.dy };
  },
  step(world, inputs, dt) {
    for (const r of world.all(Runner)) {
      const input = inputs.get(r.owner);
      if (!input) continue;
      r.x = Math.min(100, Math.max(0, r.x + input.dx * 20 * dt));
      r.y = Math.min(100, Math.max(0, r.y + input.dy * 20 * dt));
    }
  },
});
```

- Field types: `bool`, `u8`/`u16`/`u32`, `i8`/`i16`/`i32`, `f32`, `f64`,
  `string` (16 KB), `bytes` (`Uint8Array`, 48 KB), `json` (16 KB
  serialized). `json<T>()` types a json field; it starts `null`. An entity
  must fit in 61,376 bytes; split big data, such as worlds, into chunk
  entities with `bytes` and `entity.patch(field, offset, bytes)`.
- `state` is the shared state every connection sees (`room.state`).
  `private` is per player, seen only by that player (`room.private(conn)`),
  kept by player ID for 24 hours after they leave by default
  (`privateRetention` in `defineRoom`, milliseconds or `"forever"`). `entities` lists the
  entity kinds; their order is part of the hash.
- Field names `id`, `kind` and `patch`, and kind names starting with
  `irt_`, are reserved. Changing any field, type,
  writable list or the order of `entities` changes the hash.
- `{ writable: [...] }` lists fields the entity's **owner** may write
  from the client. The shared state can't have writable fields.

## The room

```ts
// room.ts
import { CallRejected, defineRoom, type RoomEntity } from "@irt/room";
import { Aim, Flag, Runner, schema, stepper } from "./shared.js";

const TICK_RATE = 20;

export default defineRoom({
  schema,
  tickRate: TICK_RATE,
  stepper,
  onCreate(room) {
    room.entities.create(Flag, { x: 50, y: 50 });
    room.state.scores = {};
    room.state.endsAt = 60 * TICK_RATE;
  },
  onJoin(room, conn) {
    // After a crash the player's entities still exist and onJoin runs again: reuse them.
    const existing = [...room.entities.all(Runner)].find((r) => r.owner === conn.player);
    conn.data.runner = existing ?? room.entities.create(Runner, { owner: conn.player, x: 10, y: 10 });
    if ([...room.entities.ownedBy(conn.player, Aim)].length === 0) room.entities.create(Aim, {}, { owner: conn.player });
    room.send(conn, { type: "hello", round: room.state.round });
  },
  onMessage(room, conn, message) {
    const m = message as { type?: unknown };
    if (m.type === "taunt") room.broadcast({ type: "taunt", from: conn.player }, { except: conn });
  },
  onWrite(room, conn, entity, next) {
    if (entity.kind === Aim) return { angle: ((next.angle as number) % 360 + 360) % 360 };
    return next;
  },
  onTick(room) {
    const flag = [...room.entities.all(Flag)][0]!;
    for (const r of room.entities.all(Runner)) {
      if (Math.hypot(r.x - flag.x, r.y - flag.y) > 3) continue;
      r.score += 1;
      room.state.scores = { ...room.state.scores, [r.owner]: (room.state.scores[r.owner] ?? 0) + 1 };
      flag.x = (flag.x + 37) % 100;
    }
    if (room.tick >= room.state.endsAt) {
      room.state.round += 1;
      room.state.endsAt = room.tick + 60 * TICK_RATE;
    }
  },
  onPlayerLeave(room, player) {
    for (const e of room.entities.all(Runner)) if (e.owner === player) room.entities.delete(e);
  },
  calls: {
    buy(room, conn, { price }) {
      const mine = room.private(conn);
      if (mine.coins < price) throw new CallRejected("not enough coins");
      mine.coins -= price;
      return { coins: mine.coins };
    },
  },
});
```

| Hook | Runs | If it throws |
|---|---|---|
| `onCreate(room)` | once, for a new room | room stops (4007) |
| `onWake(room, { elapsed })` | when the room starts from room state: after hibernating, or after a crash | room stops |
| `onJoin(room, conn)` | each connection, each reconnect included; again after a crash, with no `onLeave` before | that connection closes with 4006 |
| `onMessage(room, conn, message, { unreliable })` | each message, between ticks | logged, message dropped |
| `onWrite(room, conn, entity, next)` | each owner write, at the start of a tick; synchronous; return the fields to apply or `undefined` to reject | write rejected |
| `onTick(room, dt)` | each tick, after the stepper | room stops |
| `onLeave(room, conn)` | when a connection closes, a dropped network included, and for every connection before any hibernation; never after a crash | logged |
| `onHibernate(room)` | before the room saves and leaves its room host | room stops |
| `onRequest(room, message)` | a server API message; the return or resolved value is the reply | API gets a 422 error; logged as an error unless it's a `CallRejected` |
| `calls[name](room, conn, args)` | a client's `call(name, args)`; the return or resolved value is the reply | the client's call rejects with the message; logged as an error unless it's a `CallRejected` |

Tick order: `room.tick` increments, owner writes apply, the stepper runs
with this tick's inputs, `onTick`, then the state update goes out, then
input acks. Writes made between ticks go out with the next tick, or
sooner when a connection joins: a join's full state goes out as soon as
`onJoin` has run (or its promise settled), not at the next tick, and the
same update sends every other connection the changes since the last
tick.
`onCreate`, `onWake` and `onHibernate` may be async and are awaited;
other hooks aren't.

- `room`: `id`, `project`, `joinCode` (or null), `tick`, `tickRate`, `entities`, `state`,
  `private(conn)`, `private(player)` (undefined if none;
  `{ create: true }` creates it), `privatePlayers()`, `connections`, `data`,
  `send(conn, msg, { unreliable })`,
  `broadcast(msg, { unreliable, except })`, `kick(conn)` (4006),
  `requestHibernate()` (clients close with 4011), `rewind(history, tick)`.
- `conn`: `id`, `player` (the token's `sub`, or `guest:...`), `meta` (the
  token's `meta` claim, or null), `data` (yours, not saved), `viewTick`
  (the tick the player saw when sending this tick's input), `input`
  (that input, in `onTick`).
- `room.entities`: `create(kind, values?, { id?, owner? })`, `delete(e)`,
  `get(id)`, `all(kind)`, `count`, `setOwner(e, player | undefined)`,
  `ownerOf(e)`, `ownedBy(player, kind)`. IDs start at 2; `{ id }` sets one
  you compute, such as from chunk coordinates. `get` is a map lookup;
  `all` visits every entity of the kind.
- Messages are JSON, or binary for a `Uint8Array`, at most 64 KB. Clients
  may send 120 a second. `unreliable` uses datagrams where available.
- Writes: setting a field records it and the delta goes out at the end of
  the tick. Setting a `json` field to a deep-equal value records nothing,
  and mutating one in place records nothing: assign a new value.
- `room.data` (from `data: () => ({...})`) is per-room derived data, not
  saved; rebuild it in `onCreate` and `onWake`. Module-level variables
  are shared by every room in the room host: keep only constants there.

### Where data lives

| Data in | Leave and rejoin | Network drop | Crash | Hibernate and wake |
|---|---|---|---|---|
| An entity `onLeave` deletes | lost | lost | kept, `onJoin` runs again | lost |
| An entity the room keeps | kept | kept | kept | kept |
| `room.state` | kept | kept | kept | kept |
| `room.private(conn)` | kept 24 h by default | kept | kept | kept 24 h by default |
| `conn.data`, `room.data`, module variables | lost | lost | lost | lost |
| `room.playerData(player)`, collections, leaderboards | kept | kept | kept | kept, across every room of the project |

Room state (entities with owners, `room.state`, private state, the tick,
the stepper's `save`) streams out of the VM after every tick, so a crash
loses at most the tick in progress; it's written to object storage every
30 seconds and on hibernate. Limit 32 MB. Rooms hibernate 30 seconds
after their last connection closes. See [Room state](/docs/room-state).

## The client

```ts
// client.ts
import { CloseCode, connect, IrtError, reloadForNewBuild } from "@irt/client";
import { Aim, type Input, Runner, schema, stepper } from "./shared.js";

const router = location.hostname.endsWith(".irt-serve.com") ? "wss://eu.irt.io" : location.origin;

const keys = new Set<string>();
addEventListener("keydown", (e) => keys.add(e.key));
addEventListener("keyup", (e) => keys.delete(e.key));

async function start() {
  const room = await connect({ router, project: "my-game", room: "arena", schema, onWaking: () => console.log("waking") });

  room.on("message", (m) => console.log("message", m));
  room.on("disconnected", (code) => console.log("reconnecting", code));
  room.on("restored", () => console.log("back"));
  room.on("closed", (e) => {
    if (e.code === CloseCode.SchemaMismatch) reloadForNewBuild();
    else console.log(e.message);
  });

  const me = room.predict(stepper, {
    find: (r) => [...r.entities.all(Runner)].find((e) => e.owner === r.player),
    sample: (): Input => ({
      dx: (keys.has("ArrowRight") ? 1 : 0) - (keys.has("ArrowLeft") ? 1 : 0),
      dy: (keys.has("ArrowDown") ? 1 : 0) - (keys.has("ArrowUp") ? 1 : 0),
    }),
  });
  const others = room.interpolate(Runner, ["x", "y"]);

  addEventListener("pointermove", (e) => {
    for (const aim of room.entities.mine(Aim)) aim.angle = (Math.atan2(e.clientY, e.clientX) * 180) / Math.PI;
  });
  room.private.volume = 7;

  const { coins } = await room.call("buy", { price: 0 });
  console.log("coins", coins, "round", room.state.round);

  function frame() {
    const local = me.render(["x", "y"]);
    for (const r of room.entities.all(Runner)) {
      const at = r.owner === room.player ? local : others.get(r);
      console.log(r.owner, at.x, at.y);
    }
    requestAnimationFrame(frame);
  }
  frame();
}

start().catch((e) => {
  if (e instanceof IrtError && e.code === CloseCode.SchemaMismatch) reloadForNewBuild();
  else throw e;
});
```

- `connect({ router, project, room, token?, schema, onWaking?, timeout? })`
  resolves once the client holds the full state; `room.state` and
  `room.private` are set from then. It rejects with `IrtError`. After
  that, the client reconnects by itself, and on every reconnect or room
  restart all entities leave and enter again: don't hold entity objects
  across `restored`.
- `router`: `location.origin` under `irt dev`, the region's router, such as
  `wss://eu.irt.io`, when deployed; `irt deploy` prints it.
- Without `token` the client is a **guest**: `guest:<random>`, kept in
  `localStorage` for 30 days and renewed on each connect, so every tab of
  a browser is the same player.
- `room.entities`: `get`, `all(kind)`, `mine(kind)`, `ownerOf`, `count`,
  `onEnter`, `onChange(kind, (e, changed) => ...)`, `onLeave`,
  `onCorrect`, `onOwner`. Client entities are read-only except writable
  fields of entities the player owns.
- `room`: `send(msg, { unreliable })`, `call(name, args, { timeout })`,
  `leave()`, `on(event)`, `onTick`, `predict`, `interpolate`, `player`,
  `connection`, `tick`, `serverTick()`, `rtt`, `status`, `generation`.
  `send` and `call` throw before `connect` resolves.
- Events: `waking`, `disconnected`, `restored`, `closed`, `message`,
  `tick`, `peers`, `voice`.

### In an engine or framework

There are no adapters; the client works with any engine. Construct
`new RoomClient(opts)` and add `onEnter`, `onChange` and `onLeave`
listeners before `await room.ready`: `connect` resolves after the first
state is applied and `onEnter` doesn't replay it. Map entity IDs to
engine objects, and rebuild them on `restored`, when every entity leaves
and enters again as a new object. In the engine's frame loop, draw remote
entities at `interpolator.get(e)` and the local player at
`prediction.render(fields)`. On scene or component teardown: remove the
listeners, then `prediction.stop()`, `voice.disconnect()` and
`room.leave()`. In React, connect in an effect, never in `useMemo` or
render, and draw the world from a frame loop, not React state. See
[Engines and frameworks](/docs/integrations/overview) and the
[Phaser](/docs/integrations/phaser), [PixiJS](/docs/integrations/pixi),
[Three.js](/docs/integrations/three), [Babylon.js](/docs/integrations/babylon)
and [React](/docs/integrations/react) guides.

## Ownership

Every entity has an owner: the room, or a player ID. The owner writes the
kind's writable fields on the client, `entity.field = value`, sent at
most once per tick; the room checks each in `onWrite` and wins. When the
room's value differs from the owner's, the owner gets a **correction**
(`onCorrect`). Clients can't create or delete entities or change owners.
A player always sees what it owns, and owns its private state. Use it for
cursors, aim, drag-and-drop and settings, not for anything the stepper
moves. See [Ownership](/docs/guides/ownership).

## Presence

Every room has presence: one entry per player in the room, `{ player,
name, status, connected }`, synced to every connection whatever interest
says. The runtime adds it before `onJoin` and removes it 10 seconds after
the player's last connection closes (`connected` is false meanwhile), so
a reconnect doesn't read as leave and join. Don't declare a player-list
kind or write join and leave code for one.

```ts
// client
for (const p of room.presence) list.add(p.player, p.name);
room.presence.onJoin((p) => list.add(p.player, p.name));
room.presence.onChange((p, changed) => list.update(p.player, p));
room.presence.onLeave((p) => list.remove(p.player));
room.presence.setStatus({ typing: true });   // JSON, 1 KB at most; an owner write

// room
room.presence.set(conn.player, { name: "Alice" });   // or the token meta's `name`
room.presence.get(player)?.status;
```

The status is the player's claim and skips `onWrite`; the room corrects
it with `presence.set`. Presence isn't room state: it's empty after a
wake until players reconnect, so keep lasting per-player data in private
state. See [Presence](/docs/guides/presence).

## Prediction

A **stepper** is a step function shared by room and client:
`step(world, inputs, dt, tick)`, where `inputs` maps player IDs to this tick's
input. The room runs it every tick with each player's input; the client
runs it in `room.predict(stepper, { find, sample })` for the local
player, sends each input tagged with its tick, and replays unacknowledged
inputs when the room's state arrives. `sample` runs once per room tick.
Draw `prediction.render(fields)`, use `prediction.entity` for logic,
`settled` to know it agrees with the room. Interpolate everyone else with
`room.interpolate(kind, fields)`.

- The stepper must depend only on `world`, `inputs` and `dt`: no
  `Math.random`, `Date.now` or module state.
- `parseInput` validates the client's JSON on the room; throw to drop it.
- Don't move the predicted entity in `onTick`; every such move is a
  correction.
- Inputs more than 32 ticks ahead, or for past ticks, are dropped.

See [Client prediction](/docs/guides/prediction).

## Physics

`@irt/physics/rapier2d` and `/rapier3d` are steppers on Rapier; install
`@dimforge/rapier2d-compat` or `-3d-compat` beside it. `physics({ gravity,
bodies: [body(Kind, { type, colliders, player, control })] })` gives each
entity of a kind a body posed by its fields: `x`, `y`, (`z`), and
optionally `angle` (3D `qx`..`qw`) and, for dynamic bodies, `vx`, `vy`.
Types are `dynamic`, `fixed`, `kinematic` and `character`; a character's
`control(c, input, dt)` calls `c.move(dx, dy)`, which returns whether it's
grounded. The entities are the truth: writing a pose in room code
teleports the body. Pass the stepper to `defineRoom` and `room.predict`;
the client predicts its own body against the rest as kinematic proxies.
Drive movement with inputs, not writable fields; pose fields can't be
writable. Use capsule characters spawned above the ground. Colliders
are made once unless the kind gives a `shapeKey`, such as a chunk's edit
count, which makes them again (or `reshape` updates them) when it
changes. `stepper.bodyOf(world, entity)` and `entityOf(world, collider)`
map between entities and bodies. See [Physics](/docs/guides/physics).

## Lag compensation

To check a shot against where the shooter saw the target, record the
fields a hit check reads and rewind them:
`const poses = defineHistory(Player, ["x", "y"])` (number and bool fields
only), `defineRoom({ history: [poses], ... })`. Put the shot in the
input, ignore it in the stepper, and check it in `onTick`:
`conn.input` is this tick's parsed input (undefined without one), and
`room.rewind(poses, conn.viewTick)` is a `ReadonlyMap` of ID to frozen
`{ id, x, y }` as that tick's state update sent them, without entities
that didn't exist then. Fire from the shooter's present position. Steppers
can't rewind: they also run on the client. The room keeps 250 ms plus two
ticks, 8 bytes per field per tick per entity, at most 8 MB a room, in
memory only: it's empty after a wake. With physics, `castRay(ray, maxToi,
targets, shape)` from `@irt/physics/rapier2d` or `/rapier3d` casts against
rewound poses with Rapier shapes and no world. See
[Lag compensation](/docs/guides/lag-compensation).

## Calls

Declare calls once in the schema with `defineCalls`, as above: the
room's `calls` handlers and the client's `room.call(name, args)` are typed
from it, and an optional `parse` per call checks the untrusted args before
the handler (a parse that throws rejects the call). Without `parse`, args
are unchecked JSON. See [Calls](/docs/guides/calls).

`room.call(name, args)` runs `calls[name]` in the room and resolves to its
return value. When the handler changed room state, the reply waits for
the next tick, which saves the change outside the VM first, so a reply
means the change survives a room host crash; in `@irt/testing`, tick
before awaiting it. It rejects with an `IrtError` with code 0 when the handler
throws (`call buy failed in the room: not enough coins`), there's no such
handler, 10 seconds pass, or the connection drops or the room restarts
first. Throw `new CallRejected(message)` for an expected rejection, such
as a game rule: the client gets the message and the room doesn't log it,
where any other error is logged with its stack. A failed call may or may
not have run and is never retried: make
state-changing calls safe to repeat. Use calls for request and reply,
messages for fire-and-forget, state sync for anything continuous.

## Interest

Without `interest`, every connection sees every entity. With it, a
connection sees entities that share a key with it:

```ts
interest: grid({ cellSize: 50, range: 120, dims: "xy", around: (_room, conn) => conn.data.runner })
```

`grid` places entities by their `x`/`y`/`z` (or `position`); entities
with no position are seen by everyone. `range` is a distance in world
units, `radius` a number of cells. `combine(gridA, gridB, custom)` joins
parts; `limit: { max, priority }` caps a view. Caps: 4,096 keys and
16,384 entities per connection. See [State sync and interest](/docs/guides/state-sync).

## Testing

`@irt/testing` runs the room in process with real clients and a clock
the test controls:

```ts
// room.test.ts
import { testRoom } from "@irt/testing";
import { expect, test } from "vitest";
import room from "./room.js";
import { Aim, Runner, stepper } from "./shared.js";

test("players see each other, keep coins and get corrected aim", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  const bob = await t.connect({ player: "bob" });
  alice.expectMessage({ type: "hello" });

  await expect(alice.client.call("buy", { price: 5 })).rejects.toThrow("not enough coins");
  t.live.private([...t.live.connections.values()].find((c) => c.player === "alice")!).coins = 9;
  // A call that changed room state replies once a tick has saved it.
  const bought = alice.client.call("buy", { price: 5 });
  await t.host.tick();
  await expect(bought).resolves.toEqual({ coins: 4 });

  const [aim] = alice.mine(Aim);
  aim!.angle = 400;
  await t.host.tick(2);
  alice.expectCorrected(aim!.id, "angle");
  expect(bob.view(Aim).find((a) => a.id === aim!.id)).toMatchObject({ angle: 40 });
  expect(bob.view(Runner).map((r) => r.owner).sort()).toEqual(["alice", "bob"]);
});

test("a crash keeps one runner per player; hibernation keeps private state", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  await t.host.crash();
  await alice.reconnected();
  expect(alice.view(Runner)).toHaveLength(1);

  alice.private.volume = 3;
  await t.host.tick(2);
  await t.hibernate();
  expect(alice.closedWith).toBe(4011);
  const back = await t.connect({ player: "alice" });
  expect(back.private.volume).toBe(3);
  expect(back.view(Runner)).toHaveLength(1);
});

test("the stepper moves a predicted runner and the room agrees", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  const me = alice.predict(stepper, {
    find: (r) => [...r.entities.all(Runner)].find((e) => e.owner === r.player),
    sample: () => ({ dx: 1, dy: 0 }),
  });
  await t.host.tick(40);
  expect(me.entity!.x).toBeGreaterThan(10);
});
```

- `testRoom(def, { settings? })` is one room; `createTestHost(def)` holds
  several. `t.connect({ player?, meta? })`, `t.live` (the running room),
  `t.stored()` (saved room state), `t.wake()`, `t.hibernate()`,
  `t.request(msg)` (`onRequest`), `t.host.tick(n)`, `t.host.advance(ms)`,
  `t.host.crash()`, `t.host.createRoom/joinByCode/listPublic`.
- A test client: `client` (the real `RoomClient`), `view(kind)`,
  `private`, `mine(kind)`, `messages`, `events`, `closedWith`,
  `send`, `predict`, `drop()`, `reconnected()`, `leave()`, `expectSees`,
  `expectNotSees`, `expectMessage`, `expectCorrected`, `lastUpdate`.
- `tick` and `advance` throw `RoomStoppedError` if a room's code threw
  where that stops it.
- `t.connect` rejects with `IrtError` and the close code when the room
  refuses it. `reconnected()` resolves at once if the client already
  reconnected since its last drop or crash.
- Assert after `await t.host.tick()`. Room code's own timers and
  `Date.now()` don't follow the test clock: time things in ticks. Ticks
  run for 30 s after the last player leaves, then stop while hibernated;
  see [Timers across hibernation](/docs/hibernation#timers-across-hibernation).

See [Testing rooms](/docs/guides/testing).

### Simulating players

`npx irt simulate --players 20` runs the room locally with 20 bots on
real client connections and checks invariants every tick: visibility
leaks (a client holding an entity the room's interest excludes),
mispredictions, owned writes lost without a correction, errors
the room logs, room state limits, and what reconnects restore. Add
`--drops 4` to exercise reconnects and `--rtt 120 --jitter 20 --loss
0.02` for a slow network. It exits 1 on a failure and writes
`.irt/simulate/trace.jsonl`; its last line has the verdict and the first
failure's tick, players and entity values on the room and the client.

For scenarios, write `irt.sim.ts`:

```ts
import { chat, defineSimulation, walk } from "@irt/simulate";
import room from "./src/room.js";

export default defineSimulation(room, {
  players: 16,
  drops: 2,
  behaviour: [walk(), chat()],
  async run(sim) {
    await sim.wait(100);
    await sim.crash();
  },
  invariants: {
    "score never negative": ({ room }) => room.state.score >= 0 || `score is ${room.state.score}`,
  },
});
```

Bots have `send`, typed `call`, `write` (checked owned writes),
`predict`, `wait(ticks)`, `until(test)`, `drop()` and `leave()`. A run
is deterministic for `--seed`. See
[Simulating players](/docs/guides/simulate).

## Deploying

```ts
// irt.config.ts
import { defineConfig } from "@irt/cli/config";

export default defineConfig({
  project: "my-game",
  room: "src/room.ts",
  site: { dir: "dist", build: "npm run build:web", crossOriginIsolated: false },
  settings: {
    players: { guests: true, createRooms: true, listPublic: true },
    rooms: { size: "standard", retention: "7d", buildUpdate: "hibernate" },
  },
});
```

- `npx irt deploy` bundles the room, runs `site.build`, uploads the build
  and makes it live: the site and room code go live together. `limits`
  and `webhookUrl` can't be set from code.
- **Schema hash.** Clients must match the hash of their room's build
  exactly, or they close with 4004. A room still on an older build
  refuses the new site's clients until it hibernates and moves. Sites deploy with their builds, so a web client
  handles 4004 by reloading. Bots and other clients must be rebuilt.
- **Rooms move** to a new build when they next hibernate.
- **Rooms are created on first connect only with `players.createRooms`
  on**, deployed and under `irt dev` alike. With it off, a connection to
  a room that doesn't exist closes with 4002; use `irt rooms create <id>`
  or `POST /projects/{p}/rooms`.
- **Migrations.** A change old room state doesn't fit (renaming or
  removing a field or kind, changing a type) needs `version: n + 1` and
  `migrations: { [n + 1]: (data) => data' }` on plain `RoomData`. Adding
  fields or kinds doesn't. Rolling back past a version bump stops migrated
  rooms. See [Builds and deploys](/docs/builds).
- CI: `npx irt test`, then `npx irt deploy` with `IRT_TOKEN` set to a
  project API key.
- Other commands: `irt logs [--follow]`, `irt rooms list|create|delete|send`,
  `irt secrets list|set|unset` (secrets reach room code as environment
  variables), `irt build`.
- **Dev tools.** While `irt dev` runs, `http://127.0.0.1:7350/v1/dev/`
  shows each room's connections, `room.state`, private state, entities
  with owners, the last 200 messages and calls, and a tick profile (p50,
  p95 and max per second for `tick`, `stepper`, `onTick`, `flush`, owner
  writes and each hook); `GET /v1/dev/rooms/{project}/{id}` returns it as
  JSON. `simulateNetwork({ rttMs, jitterMs, loss })` from `@irt/client/dev`
  is a `dial` for `connect` that adds latency and drops unreliable
  messages, against local routers only. See [Dev tools](/docs/dev-tools).

## Games without a backend

Guests, `createRoom({ router, project, public?, joinCode?, meta? })` →
`{ id, joinCode }`, `joinByCode({ router, project, code })` → room ID, and
`listPublic({ router, project })` → active public rooms, gated by
`players.guests`, `players.createRooms` and `players.listPublic`. They
reject with `IrtError` whose code is the HTTP status (403 setting off,
404 unknown code, 409 ID taken, 429 limited). See
[Games without a backend](/docs/no-backend). Don't write the room screens
yourself: the [UI kit](/docs/ui-kit), `@irt/client/ui` or one entry per
element such as `@irt/client/ui/room-panel`, has framework-free custom
elements sharing one theme (`--irt-bg`, `--irt-fg`, `--irt-accent` and
the rest on `:root`). `<irt-room-panel router project>` creates, joins by
code and quick joins, fires `room-join` with `{ room, joinCode }` for the
project to connect and set `panel.client`, and shows an `<irt-invite>`
(join code, share link with `?code=`, joined by itself when opened, a QR
code with the `qr` attribute), the status and the players; the name the
player types goes in their presence status as `name`.
`<irt-room-browser router project type>` lists public rooms with
players out of `maxPlayers`; `<irt-lobby>` is a lobby with an invite;
`<irt-voice-settings>` and `<irt-voice-chat>` take a `voice`;
`<irt-network>` and `<irt-join-loader>` take a `client`. Any of them
renders as a modal dialog with the `dialog` attribute and `show()`, or
`open("irt-room-browser", { router, project })`. Games with accounts sign
[player tokens](/docs/player-tokens) (HS256 JWT: `sub`, `prj`, `iat`,
`exp` at most 24 h later, optional `room` and `meta`) on their backend.

## Player data and leaderboards

Data that outlives rooms, per project: **player data** (keys per
player, JSON or bytes up to 64 KB, 256 keys and 1 MB a player, each with
a `version`), **collections** of entries (`id`, value, flat `meta`
filtered on, `score` sorted on, `owner`) and **leaderboards** (one score
per player per period). Declare collections in `irt.config.ts`:

```ts
settings: {
  data: {
    player: { clientWrite: ["settings"] },                        // keys clients may write; default none
    collections: {
      levels: { clientRead: true, clientWrite: "own", maxOwn: 50 },
      highscores: { clientRead: true, leaderboard: { order: "desc", keep: "best", periods: ["all", "week"] } },
    },
  },
},
```

- Room code: `room.playerData(p)`: `get(key)` → `{ value, version }` or
  undefined, `set(key, v, { version? })`, `increment(key, by)` → number,
  `delete`, `list`, `refresh`. `room.collection(name)`: `get(id)`,
  `put({ id?, value, meta?, score?, owner?, version? })` → `{ id,
  version }` (replaces the whole entry), `list({ where, owner, order:
  "-score", limit, after })` → `{ entries, next }` without values,
  `delete`. `room.leaderboard(name)`: `submit(player, score, { meta })`,
  `top({ period: "week", limit })`, `around(player, { count })`.
- `version: 0` means must not exist; a mismatch is `E_VERSION`. Calls
  reject with `DataError` (`code` `E_INVALID`, `E_FORBIDDEN`,
  `E_UNKNOWN`, `E_VERSION`, `E_TYPE`, `E_QUOTA`, `E_LIMIT`, `E_SPENDING`,
  `E_UNAVAILABLE`).
- The room caches: a `get` within 5 s of its last read or write of that
  key or entry needs no call; its own writes show at once, others'
  within 5 s; `refresh()` drops it. `list`, `top`, `around` are calls
  every time. Load a player's data in `onJoin`, keep it in `conn.data` or
  private state and write it back on change; never `list` or `top` per
  tick.
- After `E_UNAVAILABLE` a write may or may not have happened (5 s
  deadline, nothing queued): retry it with `version`. `increment` can't
  be retried safely.
- Clients: `dataClient({ router, project, token? })`, or
  `room.playerData` on a `RoomClient`, has the same calls for its own
  player over HTTP, no room needed; a guest is one player in rooms and
  data calls. Clients read their own data and write `clientWrite` keys;
  `clientRead` lets them read a collection; `clientWrite: "own"` lets
  them write their own entries, with `owner` forced to them.
- Authorship is `owner`, never `meta`. A score a client submits can be
  faked: submit scores from room code.
- Tests: `host.playerData(p)`, `host.collection(n)`,
  `host.leaderboard(n)` seed and read an in-memory store; pass
  `settings: { data }` to `createTestHost`.

See [Player data, collections and leaderboards](/docs/guides/player-data).

## Porting from another framework

There's no compatibility layer for Colyseus, Playroom Kit or Socket.IO;
port the room code to `defineRoom` and the client to `@irt/client`.
Their handlers become `onMessage`, their acks and RPCs with replies
become calls, data keyed by session or socket ID is keyed by
`conn.player`, and state that was broadcast by hand becomes entities. Playroom's host-player logic
moves into the room. Matchmaking beyond `quickJoin` and anything that
crosses rooms goes to a backend: rooms don't message each other. See
the guides for [Colyseus](/docs/migrate/colyseus),
[Playroom Kit](/docs/migrate/playroom) and [Socket.IO](/docs/migrate/socket-io).

## Close codes

| Code | Meaning | Client SDK |
|---|---|---|
| 4000 | Protocol version | fails; update `@irt/client` |
| 4001 | Token invalid or expired, or guests off | fails; get a new token |
| 4002 | Room not found, and `players.createRooms` off | fails; create it first |
| 4003 | Room full | fails |
| 4004 | Schema hash differs from the room's build | fails; reload the site |
| 4005 | Rate or size limit | reconnects after backoff |
| 4006 | Kicked, or `onJoin` threw | fails |
| 4007 | Room stopped from an error | fails; read `irt logs` |
| 4008 | Room moved or restarted | reconnects at once |
| 4009 | Spending limit | fails |
| 4010 | Wake timed out | reconnects after backoff |
| 4011 | Room hibernated by `requestHibernate` | fails; offer a rejoin |
| 4012 | Same player connected again elsewhere | fails |

Anything else reconnects with backoff. See [Errors and close codes](/docs/reference/errors).

## Common mistakes

1. Creating a second entity for a player in `onJoin`; after a crash the
   old one exists. Find it first, by `owner` or `ownedBy`.
2. Keeping a score or inventory on an entity `onLeave` deletes; `onLeave`
   runs before every hibernation too. Use private state or `room.state`.
3. Keeping game state in module variables, `room.data` or `conn.data`.
   None is saved, and module variables are shared by every room in the
   room host.
4. Mutating a `json` field in place. Assign a new value.
5. Trusting client input. Validate every message, call argument, input
   (`parseInput`) and owner write (`onWrite`).
6. A non-deterministic stepper, or moving the predicted entity outside
   it: constant mispredictions.
7. Making stepper-driven fields writable. The room overwrites them every
   tick.
8. Two copies of the schema. Import one module in room and client, or get
   4004.
9. Connecting to a fixed room ID that was never created with
   `players.createRooms` off: 4002.
10. Reconnecting by hand on `closed`, or reloading on anything but 4004.
11. Testing two players in two tabs of one browser: one guest, and 4012.
12. Asserting in a test before `await t.host.tick()`.
13. Slow work in `onTick`: rooms in a room host share one event loop, and
    a 5-second block kills the room host.
14. Renaming or removing a field without a migration: rooms stop on wake.
15. Retrying a failed `call` that isn't safe to repeat.
16. Hard-coding `http://127.0.0.1:7350` as the router in the site.
17. Building a player list from entities and `onJoin`/`onLeave`; use
    `room.presence`.
18. Keeping progress that should outlive the room in private state; use
    `room.playerData`. Calling `get` or `top` every tick instead of
    keeping the data in memory.
19. Trusting a leaderboard clients submit to, or `meta` as the author
    of an entry; use room-code submits and `owner`.

## Limits

Tick rate 1 to 120, default 20. Messages 64 KB, 120 a second per
connection. Room state 32 MB. Private state kept 24 hours by default. Rooms
hibernate 30 seconds after the last connection. Wake timeout 10 s. One
connection per player per room. Player tokens at most 24 hours; guest
tokens 30 days. Room IDs 1 to 64 of `A-Z a-z 0-9 _ -`. Data calls 200 a
second per room, 10 a second per client. See [Limits](/docs/limits).

---

# How rooms hibernate and wake

> When a room hibernates, what is saved, what happens when a player connects to a hibernated room, and what it costs.

Rooms on IRT don't need to run when nobody is in them. An empty room
hibernates: its room state goes to object storage and it leaves its room
host. When a player connects again, the room wakes with its state as it
was. Your code doesn't save or load anything for this to work.

## When a room hibernates

- 30 seconds after its last connection closes, unless its alarm is due
  within 2 minutes; then it stays active until the alarm has run.
- When the room asks to, with `room.requestHibernate()`. Its open
  connections run `onLeave` and close with 4011, and their clients don't
  reconnect by themselves; the game can offer to rejoin.
- When its room host drains, for example to move rooms to a new build.
  A room whose definition has `sleep` goes to sleep instead, so its
  players stay connected.
- When it goes to sleep, with its players still connected; see
  [Sleeping rooms](#sleeping-rooms).

Hibernating runs the room's `onHibernate` hook, serializes the room and
writes its room state to object storage. A hibernated room costs no
room-hours. A room can stay hibernated indefinitely; only deleting it
removes its room state.

## What is saved

Everything the SDK tracks is room state:

- the room's entities, `room.state` and each player's private state,
- the room's tick,
- its alarm, from `room.setAlarm`,
- the state of a stepper that declares `save` and `load`.

Writes don't wait for hibernation. As a room runs, its changes stream out
of the VM to IRT's host daemon after each tick, and the host daemon
writes the whole room state to object storage every 30 seconds when it
has changed, and again on hibernate. Because the changes are already
outside the VM:

- a room host that crashes, or that the watchdog kills for blocking its
  event loop, restarts its rooms with nothing lost;
- a host, or IRT's host daemon on it, that fails loses the changes since
  the last write to object storage: at most 30 seconds, unless object
  storage can't be reached.

Anything you keep outside the SDK, in plain variables, isn't saved.
Rebuild it in `onWake`. [Room state and the managed store](/docs/room-state)
has the details: what's saved, the log and base it's written as, and its
32 MB limit.

## How a room wakes

A room wakes when a client connects to it, when the API sends it a
message or reads its state, or when its alarm is due. A room woken for
its alarm runs `onAlarm` straight after `onWake`, and with no one
connected hibernates again as soon as it's done. See
[Alarms](/docs/reference/room-sdk#alarms).

A room's first start goes the same way. A room created through the API,
with `irt rooms create` or by connecting to a new ID, is `hibernated`
until its first connection or API call, and its client sees `waking`
then too. The difference is only that it has no room state, so
`onCreate` runs instead of `onWake`.

`irt rooms list` shows only active rooms; `irt rooms list --all` shows
hibernated ones too.

1. The router sees a connection for a room that isn't active. It holds
   the connection and tells the client the room is waking. The client
   SDK emits a `waking` event, so you can show it.
2. The router picks where the room runs: a VM of your tenant that already
   runs the room's build and has room to spare, or a new VM.
3. The room's state is read from object storage and the room starts in a
   room host. `onWake` runs.
4. The router sends the client its welcome, and every connection held
   while the room woke joins. `connect` resolves once the client holds
   the full state; a client that was reconnecting emits `restored`.

However many players connect at once, a room wakes once.

### How fast

What a wake costs depends on where it lands:

- **In a room host that is already running.** Most wakes. Starting a room
  inside a running room host takes microseconds; what remains is reading
  the room state.
- **In a VM that has to start.** VMs restore from a base snapshot. In our
  measurements, a VM restores and its room host answers in about 35 ms.
- **In the first room host of a build.** The first room to start or
  wake on a build, such as the first after a deploy, starts that build's
  room host, which loads the room runtime and your bundle before the
  room starts. In our measurements that added about 70 to 200 ms, and
  more for a large bundle, for code that does work when its module
  loads, or on a busy host. Later rooms of the build reuse the room
  host.

End-to-end wake times, including reading room state from object storage,
haven't been measured yet and will be published when they are.

If a room hasn't woken after 10 seconds, the router closes held
connections with close code 4010 and the client SDK reconnects after a
backoff. The wake isn't cancelled, so a slow wake loses nothing.

## Sleeping rooms

A room whose players stay connected but rarely act, such as a board
game, a chat or a lobby waiting for players, can sleep: it hibernates
while the router holds its players' connections, and the next thing one
of them does wakes it. Nobody leaves, and time asleep costs no
room-hours.

```ts
import { defineCalls, defineRoom, defineSchema, entity } from "@irt/room";

const Board = entity("board", { turn: "u32" });
const schema = defineSchema({ state: Board, calls: defineCalls<{ move(): number }>() });

export default defineRoom({
  schema,
  sleep: { after: 30_000 },
  calls: {
    // A call made while the room sleeps wakes it, and is answered once it has.
    move(room) {
      room.state.turn += 1;
      return room.state.turn;
    },
  },
});
```

With `sleep.after`, the room sleeps once it has been quiet that long:
no message from any client but a ping, nothing sent or stored, no call
or server API request in flight. `room.sleep()` sleeps it at once.
Presence and each connection's `data` are saved with the room state, so
when a message, call or close from a held connection, a new connection,
the alarm or an API call wakes it, `onWake` runs with `slept: true` and
the connections are back, without `onJoin`. A held connection that
closed meanwhile gets `onLeave` then. Clients see `room.asleep` and the
`sleep` and `wake` events, and their calls are answered after the wake.

Opting in promises that the room keeps every deadline in its
[alarm](/docs/reference/room-sdk#alarms) rather than in timers or by
counting ticks, since nothing ticks while it sleeps. See
[Sleeping rooms](/docs/reference/room-sdk#sleeping-rooms) for the
details and limits. A wake is billed at least 10 seconds, so set
`sleep.after` long enough that a conversation doesn't wake the room
for every message.

A room whose definition has `sleep` also sleeps, rather than closing
its players' connections, when the server it runs on is taken out of
service, and wakes on another one when a player next acts. Players
whose connection drops while their room sleeps, such as when IRT
restarts the router they're connected to, reconnect to the sleeping
room without waking it, as long as their client still holds the room's
state from before the sleep.

## Timers across hibernation

Store deadlines in ticks, as `endsAt = room.tick + seconds * tickRate`
in room state, and compare in `onTick`. Ticks keep running for the 30
seconds between the last connection closing and the room hibernating,
then stop until it wakes, and `room.tick` carries on from where it
stopped. Left alone, a turn or round timer therefore runs for those 30
seconds with nobody there, then freezes: a round left 20 seconds before
its end expires unwatched, and one left 40 seconds before resumes with
10 left. Bots and AI turns driven from `onTick` play on in that window
too. Pick one of two behaviours instead.

**Freeze while empty.** The room is empty when `onLeave` sees
`room.connections.size === 0`, and occupied again when `onJoin` sees
`room.connections.size === 1`: the connection map already lacks the
leaving connection in `onLeave` and holds the joining one in `onJoin`.
Move what's left of the timer into room state there, and back on the
first join. `onLeave` runs for every open connection before any
hibernation but a sleep, so this covers `requestHibernate` and drains
too. Gate bots
the same way, or on `room.connections.size > 0` in `onTick`.

```ts
// round-timer.ts
import { defineRoom, defineSchema, entity } from "@irt/room";

export const Round = entity("round", { endsAt: "u32", pausedLeft: "u32" });
export const schema = defineSchema({ state: Round });

const ROUND_SECONDS = 60;

export default defineRoom({
  schema,
  onCreate(room) {
    room.state.endsAt = room.tick + ROUND_SECONDS * room.tickRate;
  },
  onJoin(room) {
    if (room.connections.size === 1 && room.state.pausedLeft > 0) {
      room.state.endsAt = room.tick + room.state.pausedLeft;
      room.state.pausedLeft = 0;
    }
  },
  onLeave(room) {
    if (room.connections.size === 0 && room.state.endsAt > room.tick) {
      room.state.pausedLeft = room.state.endsAt - room.tick;
      room.state.endsAt = 0;
    }
  },
  onTick(room) {
    if (room.state.endsAt !== 0 && room.tick >= room.state.endsAt) {
      room.state.endsAt = 0;
      room.broadcast({ type: "round-over" });
    }
  },
});
```

```ts
// round-timer.test.ts
import { testRoom } from "@irt/testing";
import { expect, it } from "vitest";
import room from "./round-timer.js";

it("freezes the round while the room is empty", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  await t.host.tick(50 * 20);
  await alice.leave();
  await t.host.advance(31_000);
  expect(t.status).toBe("hibernated");

  const back = await t.connect({ player: "alice" });
  await t.host.tick(5 * 20);
  expect(back.messages).toEqual([]);
  await t.host.tick(6 * 20);
  back.expectMessage({ type: "round-over" });
});
```

**Catch up with wall time.** Let the timer run through the idle window,
and on wake move each deadline back by the time the room spent
hibernated, which `onWake` gets as `elapsed` milliseconds. A long
absence can reset the game instead:

```ts
// catch-up.ts
import { defineRoom, defineSchema, entity } from "@irt/room";

const Round = entity("round", { endsAt: "u32", lobby: "bool" });

export default defineRoom({
  schema: defineSchema({ state: Round }),
  onWake(room, { elapsed }) {
    if (elapsed > 30 * 60_000) {
      room.state.lobby = true;
      room.state.endsAt = 0;
    } else if (room.state.endsAt !== 0) {
      room.state.endsAt = Math.max(room.tick, room.state.endsAt - Math.round((elapsed / 1000) * room.tickRate));
    }
  },
});
```

Room code's own timers, such as `setTimeout`, are neither: they don't
survive hibernation and don't follow the test clock.

## Offline progress

An idle or incremental game keeps producing while nobody is there, and
the room hibernates then, so nothing ticks. Don't add up production per
tick. Store each amount with the wall time it's valid at, and compute it
in closed form at any later time:

```ts
// colony.ts
import { defineRoom, defineSchema, entity } from "@irt/room";

const Colony = entity("colony", { food: "f64", rate: "f64", cap: "f64", at: "f64" });

const foodAt = (c: { food: number; rate: number; cap: number; at: number }, now: number) =>
  Math.min(c.cap, c.food + (c.rate * (now - c.at)) / 1000);

export default defineRoom({
  tickRate: 1,
  schema: defineSchema({ state: Colony }),
  onCreate(room) {
    Object.assign(room.state, { food: 0, rate: 0.5, cap: 1000, at: room.now() });
  },
  onMessage(room, _conn, msg) {
    if ((msg as { type?: string }).type !== "spend") return;
    // Settle the amount only when it changes, so nothing is written per tick.
    const now = room.now();
    room.state.food = foodAt(room.state, now) - 10;
    room.state.at = now;
  },
});
```

- `room.now()` is wall-clock milliseconds, the same as `Date.now()` once
  deployed (each VM's clock is set from its host's when it boots), but
  it also follows `@irt/testing`'s clock, so a test can move it by days.
  Use it rather than `Date.now()` for anything timed in real time, and
  rather than a clock built from `room.tick`, which stops while the room
  is hibernated and changes meaning when a build changes `tickRate`.
- Clients compute the same function from `at` to show live amounts, so
  nothing has to tick for the display either.
- Events on a wall-clock schedule, such as something every 4 hours of
  UTC or a reset at midnight, are counted between the stored time and
  now: `Math.floor(now / period) - Math.floor(at / period)`.
- `onWake` gets `{ elapsed, savedAt, reason }`: `savedAt` is the wall time room
  state was last written, at the room's last tick with changes or its
  hibernation, and `elapsed` the milliseconds from then to the wake,
  never negative. A game that computes from `at` needs neither, but
  they suit a "while you were away" summary.

## Retention

`rooms.retention` in [`irt.config.ts`](/docs/cli#irtconfigts) sets how
long a room is kept after it hibernates:

| Value | Meaning |
|---|---|
| `"none"` | The room is deleted, not hibernated, when its idle timeout passes with no connections. Its room state is still saved while it's active, so a crashed host loses nothing. |
| `"<n>h"`, `"<n>d"` | The room is deleted after it has been hibernated that long without waking, up to `"365d"`. A wake restarts the clock at its next hibernation. |
| `"forever"` | The room is never deleted except through the API. |

The default is `"7d"`. A deleted room's ID can be created again; a
client connecting to a deleted room gets close code 4002, or creates it
again as a new room when `players.createRooms` is on, and webhooks get
`room.deleted` with reason `expired`.

A room created through the [HTTP API](/docs/http-api#rooms) or
`irt rooms create --retention` can have a retention of its own, which
wins over the project's; rooms clients create use the project's.

## Generations

Each wake gives the room a new generation. A client drops all its
entities and prediction state on a change of generation and on any
reconnect, then receives a full state update. Your client code sees
entities leave and enter again.

## New builds

When a build is made live, the project's `rooms.buildUpdate` setting decides
what running rooms do:

- `hibernate` (the default): rooms stay on their build until they next
  hibernate, and wake on the new one.
- `restart`: rooms hibernate, saving their room state, and wake on the
  new build straight away. Clients reconnect automatically, with close
  code 4008. Each host moves 20 rooms a second, so a project with many
  rooms finishes over a minute or so rather than all at once. A room with
  no connections wakes on the new build when something next connects.

When a build changes the shape of room state, it provides an up migration,
which runs when a room wakes on it. The room state from before the
migration is kept for 7 days, so a rollback can restore it.

A rollback makes an older build live again. A room whose room state is
at a newer version than the build's wakes from its room state from
before the migration, losing progress since then, and the project gets
a `room.restored` webhook. A room with none kept, because it was created
on the newer build or its kept state is over 7 days old, fails to wake,
with the reason in `irt logs`, until a build at its version is live
again. See [`irt rollback`](/docs/cli#irt-rollback-build-id). See also
[Builds and deploys](/docs/builds).

## What it costs

A room is billed in room-hours by room size, from the start of a wake
until hibernation completes. Many rooms share a room host, and many room
hosts share a VM, so an idle room doesn't hold a process or a VM of its
own. A VM stops 5 minutes after its last room hibernates.

This is what makes per-room pricing cheap: you pay for rooms while
players are in them, not for servers that wait for players.

---

# Room state and the managed store

> What IRT saves for a room, when it's written, what a crash or a failed host loses, and the limits on room state.

**Room state** is everything IRT saves for a room so it can hibernate,
wake in another room host, and survive crashes. The SDK's **managed
store** writes it for you: room code never saves or loads anything. This
page says what's in it and when it's written; [How rooms hibernate and
wake](/docs/hibernation) says when rooms sleep and wake.

## What's saved

| Saved | Not saved |
|---|---|
| Every entity, hidden ones included: its ID, kind, fields and owner | `room.data`, rebuilt by `data()` on each start and wake |
| `room.state` | `conn.data` |
| Each player's private state, by player ID, and when the player was last connected | Variables at module level, which every room in the room host shares |
| `room.tick`, and the next automatic entity ID | Connections; clients reconnect and `onJoin` runs again |
| What the stepper's `save` returned, as bytes or JSON | Timers, promises, pending calls and messages in flight |
| The room state version and the declarations it was written with | |

So game state that must outlast a hibernation, a crash or a deploy lives
in entities, `room.state` or private state. State no client may see,
such as a deck's order, lives in entities of a
[hidden kind](/docs/guides/state-sync#hidden-entities), not in
`room.data`. Anything else is rebuilt in
`onWake`; see [Where player data lives](/docs/guides/state-sync#where-player-data-lives)
for which of the three suits which data.

Private state is kept for the room definition's `privateRetention` of
wall-clock time after the player was last connected, hibernated time
included: 24 hours by default (`PRIVATE_RETENTION` in `@irt/room`). It's
checked when the room wakes and every 30 seconds, and a player who comes
back within it gets theirs back. Room state as a whole is kept until the
room is deleted: after `rooms.retention` passes with the room
hibernated, 7 days by default, or through the API.

So by default a player's private state can expire long before the room
does. A room players come back to over days, such as a saved dungeon run
whose inventories are the progress, sets a longer retention, or
`"forever"` to keep it as long as the room:

```ts
export default defineRoom({
  schema,
  privateRetention: 30 * 24 * 3600 * 1000, // 30 days
});
```

The default keeps a bound for a reason: a room many players pass
through, such as a public lobby, would otherwise keep the private state
of every player who ever joined, and its room state would only grow.

## When it's written

Room state is written as a **log** of changes on top of a **base**, a
full copy:

1. After each tick that changed anything, the room host sends that
   tick's changes, as the same binary deltas clients get, to IRT's host
   daemon, outside the VM. Changes made between ticks, in `onMessage`,
   `onJoin` or a call, go out with the next tick's, or with a join's
   update when a connection joins first.
2. Every 30 seconds, and when the log grows past 4 MB or 4,096 ticks, the
   room host sends a new base, which replaces the base and log the host
   daemon holds. The stepper's `save` runs then, and only then.
3. The host daemon writes the room state to object storage every 30
   seconds when it has changed, and always when the room hibernates and
   when its room host drains.

The host daemon holds each room's room state in memory as it arrives, so
room code that crashes, hangs or runs out of memory can't lose it:

| What fails | What the room loses |
|---|---|
| Room code throws where that stops the room | Nothing before the tick that threw. Clients close with 4007, and the next connection wakes the room from its room state |
| The room host crashes, or the watchdog kills it after 5 seconds of blocked event loop | Nothing already sent: at most the tick in progress. Its rooms restart in a new room host and clients reconnect with 4008 |
| The VM crashes | The same as a room host crash |
| The host machine, or IRT's host daemon on it, fails | Up to the last 30 seconds, since the last write to object storage, and more while object storage can't be reached. Player and project data writes are kept, so see [Writes that may have happened](/docs/guides/player-data#writes-that-may-or-may-not-have-happened) |

After any restart, the room starts from room state with `onWake`, not
`onCreate`, and `onLeave` doesn't run for the connections that were
open. See [Hooks](/docs/reference/room-sdk#hooks).

## Steppers

A stepper's `save` and `load` let it keep state of its own, such as a
physics engine's world, in room state. [`@irt/physics`](/docs/guides/physics)
saves its Rapier world this way when the world has dynamic bodies.

```ts
interface Stepper<I> {
  save?(world: World): Uint8Array | unknown;     // bytes, or anything JSON can encode
  load?(saved: Uint8Array | unknown, world: World): void;
  release?(world: World): void;
}
```

- `save` runs whenever a base is written: every 30 seconds, on hibernate
  and on drain. Never per tick.
- A `Uint8Array` is stored as bytes; anything else with `JSON.stringify`.
  `load` gets back the same: a `Uint8Array`, or the parsed JSON.
- `load` runs on wake, before `onWake`, with `undefined` when nothing was
  saved. It doesn't run for a new room.
- What `save` returns counts toward the room state limit.
- `release` runs when the room leaves its room host: after the save on
  hibernate, and when it stops. It's for caches the garbage collector
  can't free promptly, such as WebAssembly memory.

One stepper object serves every room in a room host, so `save` and
`load` get the room's `world`: the same object `step` gets for that room,
from its wake until it hibernates. Keep per-room caches in a `WeakMap`
keyed by `world`; a cache goes away with its room. `load` runs before
the room's first step after a wake, so `step` finds the cache `load`
made:

```ts
// physics-stepper.ts
import { defineSchema, defineStepper, entity, type World } from "@irt/room";

export const Ball = entity("ball", { x: "f32", y: "f32", vx: "f32", vy: "f32" });
export const schema = defineSchema({ entities: [Ball] });

interface Cache {
  spins: Record<number, number>;
}
const caches = new WeakMap<World, Cache>();

function cacheOf(world: World): Cache {
  let cache = caches.get(world);
  if (!cache) caches.set(world, (cache = { spins: {} }));
  return cache;
}

export const stepper = defineStepper<{ kick?: boolean }>({
  step(world, _inputs, dt) {
    const { spins } = cacheOf(world);
    for (const b of world.all(Ball)) {
      spins[b.id] = (spins[b.id] ?? 0) + Math.hypot(b.vx, b.vy) * dt;
      b.x += b.vx * dt;
      b.y += b.vy * dt;
    }
  },
  save: (world) => cacheOf(world).spins,
  load(saved, world) {
    if (saved) cacheOf(world).spins = saved as Record<number, number>;
  },
});
```

On a client, prediction never calls `save` or `load`. Its world is one
object for the life of the prediction, so a cache keyed by it lasts
across steps there too; see
[The prediction world](/docs/guides/prediction#the-prediction-world).

## Limits

Room state is at most 32 MB, the base plus its log. A room that grows
past it stops with `room state is 33.0 MB; the limit is 32 MB` and its
clients close with 4007. Past 24 MB, the project's logs say so once, as
`room <id>: room state is 24.1 MB; the room stops at 32 MB`, and
`irt rooms show <id>` prints a room's size as last saved. In tests,
`t.stored()` has the room state itself. Each entity must fit in 61,376 bytes, and
fields have their own caps; see [Limits](/docs/limits#state-sync).

Big rooms are usually big because of a few kinds of data:

- **Worlds.** Split them into chunk entities with `bytes` fields, start
  empty chunks as empty bytes, and `patch` them, so the log carries only
  edits.
- **Private state of players long gone.** It's dropped after
  `privateRetention`, 24 hours by default; don't copy it into
  `room.state`, and keep `"forever"` for rooms with a bounded set of
  players.
- **Histories.** A chat log or move list in a `json` field is rewritten
  whole on each change and grows forever. Cap it, or keep it in your
  backend.

## Reading room state

- In tests, `t.stored()` returns what a wake would start from, decoded as
  `RoomData`; see [Testing rooms](/docs/guides/testing#hibernation-and-crashes).
- Your backend can read a room's `room.state` with
  `GET /projects/{p}/rooms/{id}/state`, or ask room code for anything else
  through `onRequest`; see the [HTTP API](/docs/http-api#rooms). Both wake
  a hibernated room.
- Under `irt dev`, room state is in `.irt/data`, so it survives restarts
  of `irt dev`. Delete the directory to start every room fresh.

## Changing its shape

A build that changes the declarations in a way old room state doesn't
fit, such as renaming or removing a field, bumps `version` and adds a
migration. See [Room state versions](/docs/builds#room-state-versions).

## Common mistakes

- **Saving by hand.** There's nothing to call; every write to an entity,
  `room.state` or private state is saved.
- **Keeping game state in `room.data` or module variables.** It's gone
  after a hibernate or a crash. Rebuild derived data in `onWake`.
- **Expecting `onLeave` before a crash.** It doesn't run; the room wakes
  with every entity as it was.
- **Storing per-room data in a stepper's closure.** Every room in the room
  host shares it; key it by `world`.
- **Growing a `json` field without bound.** It's rewritten whole on every
  change and counts toward 32 MB.

---

# State sync and interest

> Declare entities, sync them as binary deltas, look them up by ID, and send each connection only what it should see.

All synced state is typed **entities** of kinds the room declares. Each
tick, every changed entity is encoded once as a binary delta, and each
connection gets the deltas of the entities it sees. With no interest
set, every connection sees every entity.

## Declaring kinds

```ts
// schema.ts
import { defineSchema, entity } from "@irt/room";

export const Player = entity("player", {
  owner: "string",
  x: "f32",
  y: "f32",
  z: "f32",
  hp: "u8",
});

export const Chunk = entity("chunk", {
  cx: "i32",
  cy: "i32",
  cz: "i32",
  blocks: "bytes",
});

export const Match = entity("match", { round: "u16", phase: "string" });
export const Hand = entity("hand", { cards: "json" });

export const schema = defineSchema({
  state: Match,
  private: Hand,
  entities: [Player, Chunk],
});
```

`entity(name, fields)` takes a name matching `[A-Za-z_][A-Za-z0-9_]{0,63}`
and up to 255 fields. Field names `id`, `kind` and `patch` are reserved,
since entity objects have properties of those names; using one is a type
error at the `entity()` call, and an error when the module loads. Kind
names starting with `irt_` are reserved too: every schema ends with the
built-in `irt_presence` kind of [presence](/docs/guides/presence), so the
schema hash covers it the same way for every room.

| Type | Holds | Size |
|---|---|---|
| `bool` | `true` or `false` | 1 byte |
| `u8`, `u16`, `u32` | unsigned integers | 1, 2, 4 bytes |
| `i8`, `i16`, `i32` | signed integers | 1, 2, 4 bytes |
| `f32` | numbers, rounded with `Math.fround` | 4 bytes |
| `f64` | numbers | 8 bytes |
| `string` | UTF-8 text | at most 16 KB |
| `bytes` | `Uint8Array` | at most 48 KB |
| `json` | anything JSON can encode, replaced whole when set | at most 16 KB serialized |

A `json` field declared as `"json"` reads as `unknown`. Declare it with
`json<T>()` to give it a type, so room and client code reads it without
casts:

```ts
// scores.ts
import { defineSchema, entity, json } from "@irt/room";

export const Match = entity("match", {
  round: "u16",
  scores: json<Record<string, number>>(),
});
export const schema = defineSchema({ state: Match });

export function addPoint(state: { scores: Record<string, number> }, player: string) {
  state.scores = { ...state.scores, [player]: (state.scores[player] ?? 0) + 1 };
}
```

`json<T>()` is the string `"json"` at runtime: it changes nothing on the
wire, and a kind declared with it has the same schema hash as one
declared with `"json"`. The type isn't checked when the field is set,
and like any `json` field it holds `null` until it's first set, so set it
in `onCreate` or declare `json<T | null>()`.

An entity with every field encoded must fit in 61,376 bytes (60 KB minus
64), so it can enter a view within one state update part. A write that
would make it bigger throws a `RangeError` naming the entity and field;
split large data across several entities, as chunks do.

`defineSchema({ state?, private?, entities? })` returns the room's
`Schema`. The order of `entities` is part of the schema hash: reordering
them is a schema change.

## Shared, private and entity state

| In room code | Who sees it | Kept by |
|---|---|---|
| `room.state` | every connection | the room |
| `room.private(conn)` | that connection's player only | player ID, so it survives reconnects |
| `room.entities` | connections whose interest includes it | entity ID |
| `room.entities` of a hidden kind | no connection | entity ID |

```ts
// match-room.ts
import { defineRoom, type RoomEntity } from "@irt/room";
import { Chunk, Player, schema } from "./schema.js";

export default defineRoom({
  schema,
  onCreate(room) {
    room.state.phase = "lobby";
    for (let cx = -2; cx <= 2; cx++) {
      room.entities.create(Chunk, { cx, cy: 0, cz: 0, blocks: new Uint8Array(32 * 32 * 32) });
    }
  },
  onJoin(room, conn) {
    // After a room host restart the player's entity is still there; see below.
    const existing = [...room.entities.all(Player)].find((p) => p.owner === conn.player);
    conn.data.player = existing ?? room.entities.create(Player, { owner: conn.player, hp: 100 });
    room.private(conn).cards = ["ace", "king"];
  },
  onMessage(room, conn, message) {
    const m = message as { dig?: [number, number] };
    if (!m.dig) return;
    const [cx, index] = m.dig;
    const chunk = [...room.entities.all(Chunk)].find((c) => c.cx === cx);
    if (!chunk || !Number.isInteger(index) || index < 0 || index >= 32 * 32 * 32) return;
    // A block edit sends three bytes and the offset, not the chunk.
    chunk.patch("blocks", index, new Uint8Array([0]));
    const player = conn.data.player as RoomEntity<typeof Player>;
    player.hp = Math.max(0, player.hp - 1);
  },
  onPlayerLeave(room, player) {
    for (const e of room.entities.all(Player)) if (e.owner === player) room.entities.delete(e);
  },
});
```

How writes are tracked:

- Setting a field records it; the delta goes out at the end of the tick.
  There's no diff of the whole state.
- Within a tick the last write to a field wins, and a replace after a
  patch wins.
- Setting a field to its current value records nothing. For `json`, a
  deep-equal value records nothing; mutating a `json` value in place
  records nothing until you set the field again.
- `entity.patch(field, offset, bytes)` writes into a `bytes` field and
  sends only the range. It grows the field when it writes past the end,
  filling the gap with zeros, so empty bytes is a fine starting value for
  data that's mostly blank, such as an all-air chunk.
- Read a `bytes` field from the entity again after a patch. A patch that
  grows it replaces the `Uint8Array`, so an array you held from before is
  the old, shorter one; on the client every change is a new array.
- Writes to `f32` fields go through `Math.fround` in the room and on the
  client, so both hold the same number.
- Writing a deleted entity throws.

## Where player data lives

A player's data can live in three places, and they last differently.
What decides it is when `onLeave` and `onPlayerLeave` run. `onLeave`
runs when a connection closes, which includes a dropped network before
the client reconnects. `onPlayerLeave` runs when the player's presence
ends, 10 seconds after its last connection closed with no new one. Both
run before the room hibernates, whatever the reason, and neither when a
room host crashes.

| Data in | Leave and rejoin | Dropped network, reconnect | Room host crash | Hibernate and wake |
|---|---|---|---|---|
| An entity `onPlayerLeave` deletes | lost | kept, within 10 s | kept, and `onJoin` runs again | lost |
| An entity `onLeave` deletes | lost | lost | kept, and `onJoin` runs again | lost |
| An entity the room keeps | kept | kept | kept | kept |
| A [hidden entity](#hidden-entities) | kept | kept | kept | kept |
| `room.state`, such as a `json` map by player ID | kept | kept | kept | kept |
| `room.private(conn)` | kept for `privateRetention`, 24 hours by default | kept | kept | kept for `privateRetention` |
| `conn.data`, `room.data`, module variables | lost | lost | lost | lost |
| A presence status | kept for 10 s | kept for 10 s | lost | lost |

- **Entities** are the room's synced objects, seen through interest. A
  player's avatar is usually an entity created in `onJoin` and deleted in
  `onPlayerLeave`, so it's on screen while the player is in the room and
  survives a dropped network.
  Anything stored on it goes with it: don't keep a score there that
  should outlive a visit.
- **`room.state`** is one entity every connection sees. Keep standings
  every player sees here, such as `scores: json<Record<string, number>>()`
  keyed by player ID.
- **Private state** is kept by player ID and only that player sees it.
  It's created empty at a player's first join, comes back when they
  rejoin, and is dropped once the player has been away for the room's
  `privateRetention` of wall-clock time, hibernated time included: 24
  hours by default, so it can expire before the room does. Set
  `privateRetention` in `defineRoom`, in milliseconds or `"forever"`,
  when players come back over days; see
  [Room state](/docs/room-state#whats-saved). Keep a player's own data
  here, such as a hand of cards or an inventory. Room code reaches any
  player's private state by player ID, `room.private("alice")`, connected
  or not; it's `undefined` for a player with none, and
  `room.private("alice", { create: true })` creates it.
  `room.privatePlayers()` lists the players that have it.
- **A rejoining player's first state is their last session's private
  state.** Their client gets it as it was when they left, before any
  async work in `onJoin` has finished. A field that describes the
  session rather than the player, such as `loaded` set once a backend
  answers, still holds the old session's value. Reset such fields in
  `onJoin` before it awaits anything: what `onJoin` sets synchronously
  is in the player's first state update. Reset them in `onLeave` too,
  which runs before every hibernation, so private state is never kept
  with them set.
- **Hidden entities** are entities no connection ever sees, such as a
  deck's order. They're room state like any entity; see
  [Hidden entities](#hidden-entities).
- **`conn.data`** is the room's own scratch space for one connection,
  such as a reference to its avatar entity. It isn't room state.
- **`room.data`** is the same for the whole room, for data derived from
  its entities, such as a lookup table. Module variables are shared by
  every room in the room host, so don't keep one room's data in them;
  see [Room data and module scope](/docs/reference/room-sdk#room-data-and-module-scope).
- **[Presence](/docs/guides/presence)** is who's connected now: an
  entry per player with a name and a small status, which every
  connection sees. The runtime keeps it, and it isn't room state.

After a room host crash, the room wakes from its room state with every
entity as it was, clients reconnect and `onJoin` runs for each of them
again, with no `onLeave` before it. A room that creates an avatar in
`onJoin` finds the one from before instead, as the room above does:

```ts
const existing = [...room.entities.all(Player)].find((p) => p.owner === conn.player);
conn.data.player = existing ?? room.entities.create(Player, { owner: conn.player });
```

An avatar whose player doesn't come back after a crash stays in the
room, and in its room state, until room code deletes it. A room that
cares can delete, in `onTick`, avatars whose owner has had no connection
for a few seconds. `onWake` is too early: it runs before any client has
reconnected.

## Hidden entities

Some room state must reach no client at all: a deck's order, a puzzle's
answer, a bot's plan. `room.data` isn't room state, so it's gone after a
wake, and hiding an entity with `interest` is easy to get wrong: without
an interest every connection sees every entity, and an interest that
gives the entity `EVERYWHERE` or a key some connection subscribes to
shows it too. Declare the kind hidden instead:

```ts
// cards.ts
import { defineRoom, defineSchema, entity, json } from "@irt/room";

export const Table = entity("table", { drawPile: "u8" });
export const Hand = entity("hand", { cards: json<string[]>() });
export const Deck = entity("deck", { order: json<string[]>() }, { hidden: true });
export const schema = defineSchema({ state: Table, private: Hand, entities: [Deck] });

function shuffled(cards: string[]): string[] {
  const out = [...cards];
  for (let i = out.length - 1; i > 0; i--) {
    const j = crypto.getRandomValues(new Uint32Array(1))[0]! % (i + 1);
    [out[i], out[j]] = [out[j]!, out[i]!];
  }
  return out;
}

export default defineRoom({
  schema,
  onCreate(room) {
    const deck = room.entities.create(Deck, { order: shuffled(["1a", "2a", "3a", "1b", "2b", "3b"]) });
    room.state.drawPile = deck.order.length;
  },
  onJoin(room, conn) {
    room.private(conn).cards ??= [];
  },
  onMessage(room, conn, message) {
    if ((message as { type?: unknown }).type !== "draw") return;
    const deck = [...room.entities.all(Deck)][0]!;
    const [card, ...rest] = deck.order;
    if (card === undefined) return;
    deck.order = rest;
    const hand = room.private(conn);
    hand.cards = [...hand.cards, card];
    room.state.drawPile = rest.length;
  },
});
```

- A hidden entity is room state like any other: it's saved, restored
  on wake and kept across a room host crash, and hooks and calls read
  and write it through `room.entities`.
- Don't read hidden entities in a stepper. The client runs the same
  `step` to predict, on a world that never holds them, so a step that
  depends on them predicts something other than what the room does.
  The room's `world` is `room.entities`, so it does hold them; nothing
  stops a stepper reading them, and nothing warns when prediction
  drifts.
- The room never sends it to a connection. It gets no interest keys, so
  `keysOf` isn't called for it, whatever `interest` is; voice's default
  rule doesn't see it; and creating, changing or deleting it sends
  nothing. The inspector in `irt dev` shows it, marked hidden, since
  it's for you and not for players.
- A hidden kind can't have writable fields, so no player can own one of
  its entities.
- The kind's declaration is in the schema, so it's in the client's
  bundle and the schema hash; its values never leave the room.

What the room sends is still yours to check. Data reaches clients in
other ways than entities:

- **What you copy out.** A card moved into a hand, `room.state`, a
  message, a call's reply or error, and presence all reach clients.
- **Entity IDs.** Automatic IDs count up for every entity, hidden ones
  included, so a gap between two IDs a client sees says how many
  entities were created in between. Give visible entities `{ id }` of
  your own where that matters.
- **Counts and timing.** A `drawPile` count, how long a reply takes, or
  which tick a change lands in can say what a hidden value is.

In a test with `@irt/testing`, `client.view(Deck)` stays empty however
the game goes, and `room.stored()` shows the deck in room state.

## Entity IDs and lookups

An entity's ID is assigned from 2 by default. Pass `{ id }` to choose
it, so the room and its clients can compute it: a chunk's ID from its
chunk coordinates, a tile's from its row and column. Then a stepper, a
hook or a client finds static data with `world.get(id)` instead of
searching.

```ts
// voxel-room.ts
import { defineRoom, defineStepper, type Entity, type RoomEntity, type World } from "@irt/room";
import { Chunk, Player, schema } from "./schema.js";

const SIZE = 16;
const N = 8;

/** A chunk's entity ID, from its chunk coordinates; the world is N × N × N chunks. */
export const chunkId = (cx: number, cy: number, cz: number) => 2 + cx + cz * N + cy * N * N;

/** Where a block is in its chunk's `blocks`, for whole block coordinates from 0. */
const indexOf = (x: number, y: number, z: number) => (x % SIZE) + (z % SIZE) * SIZE + (y % SIZE) * SIZE * SIZE;

export function blockAt(world: World, x: number, y: number, z: number): number {
  const bx = Math.floor(x);
  const by = Math.floor(y);
  const bz = Math.floor(z);
  if (Math.min(bx, by, bz) < 0 || Math.max(bx, by, bz) >= N * SIZE) return 0;
  const chunk = world.get(chunkId(Math.floor(bx / SIZE), Math.floor(by / SIZE), Math.floor(bz / SIZE)));
  // Blocks start empty above the ground; reading past the end gives air.
  return (chunk as Entity<typeof Chunk> | undefined)?.blocks[indexOf(bx, by, bz)] ?? 0;
}

export const fall = defineStepper<{ jump: boolean }>({
  step(world, inputs, dt) {
    for (const p of world.all(Player)) {
      if (blockAt(world, p.x, p.y - 0.01, p.z) === 0) p.y -= 10 * dt;
      else if (inputs.get(p.owner)?.jump) p.y += 1;
    }
  },
});

export default defineRoom({
  schema,
  stepper: fall,
  onCreate(room) {
    for (let cy = 0; cy < N; cy++) {
      for (let cz = 0; cz < N; cz++) {
        for (let cx = 0; cx < N; cx++) {
          const blocks = cy === 0 ? new Uint8Array(SIZE ** 3).fill(1) : new Uint8Array(0);
          room.entities.create(Chunk, { cx, cy, cz, blocks }, { id: chunkId(cx, cy, cz) });
        }
      }
    }
  },
  onJoin(room, conn) {
    const existing = [...room.entities.all(Player)].find((p) => p.owner === conn.player);
    conn.data.player = existing ?? room.entities.create(Player, { owner: conn.player, x: 8, y: 20, z: 8 });
  },
  onMessage(room, conn, message) {
    const m = message as { place?: [number, number, number] };
    if (!m.place || !m.place.every((v) => Number.isInteger(v) && v >= 0 && v < N * SIZE)) return;
    const [x, y, z] = m.place;
    const chunk = room.entities.get(chunkId(Math.floor(x / SIZE), Math.floor(y / SIZE), Math.floor(z / SIZE)));
    // Grows an empty chunk's blocks as far as this block.
    (chunk as RoomEntity<typeof Chunk>).patch("blocks", indexOf(x, y, z), new Uint8Array([1]));
  },
});
```

- An explicit ID is an integer from 2 that no live entity has; `create`
  throws otherwise, naming the entity that has it. A deleted entity's ID
  can be used again, even in the same tick.
- Automatic IDs are always above the highest ID the room has used, so
  they never take an explicit one. An explicit ID can still meet an
  automatic one created earlier, so create the entities with computed
  IDs first, in `onCreate`, as this room does.
- IDs are kept in room state, so they're the same after a wake.

What lookups cost, in a stepper or anywhere else:

- `world.get(id)` is one map lookup, in the room and on the client.
- `world.all(kind)` visits every entity of that kind each time it's
  called: in the room, every one the room has; on the client, every one
  the client sees. A stepper runs every tick in the room, and on the
  client again for each input it replays, so a stepper that searches
  `all(Chunk)` for each player does chunks × players work every time.
  Loop over the few entities that move with `all`, and reach static data
  by ID.

## Interest

A connection sees an entity when they share an **interest key**. Keys
are strings or numbers your room assigns.

```ts
interface Interest<R = Room> {
  keysOf(room: R, entity: RoomEntity): Iterable<InterestKey>;
  subscriptionsOf(room: R, connection: Connection): Iterable<InterestKey>;
  sees?(room: R, connection: Connection, entity: RoomEntity): boolean;
  limit?: { max: number; priority(room: R, connection: Connection, entity: RoomEntity): number };
}
```

Each function gets the room first, as hooks do, so a rule can read the
room's own state, such as a player's block list. At the end of each tick the room calls `keysOf` for entities that
changed and `subscriptionsOf` for every connection. An entity that newly
shares a key with a connection enters its view with all its fields; one
that no longer shares any leaves it. `sees`, when given, narrows that
further: it runs each tick for every connection and entity that share a
key, and the connection sees the entity only when it returns `true`.
`limit` applies last.

### The grid

```ts
function grid(opts: {
  cellSize: number;
  dims: "xy" | "xz" | "xyz";
  position?: (room: Room, entity: RoomEntity) => [x: number, y: number, z?: number] | undefined;
  around(room: Room, connection: Connection): RoomEntity | [x: number, y: number, z?: number] | undefined;
  prefix?: string;
  kinds?: Kind[];
} & ({ range: number } | { radius: number })): InterestPart;

type InterestPart = Pick<Interest, "keysOf" | "subscriptionsOf" | "sees">;
```

- An entity's key is the cell at `position(entity)`; by default its `x`,
  `y` and `z` fields. `dims` picks the axes: `"xz"` for a 3D world split
  on the ground plane.
- When `around` returns an entity, the grid places it with `position`
  too. A `position` written for chunk fields gives a player no position,
  and its connection then subscribes only to `EVERYWHERE`; have `around`
  return the player's point, `[p.x, p.y, p.z]`, or make `position`
  handle both kinds.
- `kinds` limits the grid to entities of those kinds: others get no key
  from it, rather than `EVERYWHERE`, and its `sees` lets them through.
- `prefix` starts every key the grid gives, `EVERYWHERE` included, so
  `grid({ ..., prefix: "p:" })` gives `"p:3,-1"` and `"p:*"`.
- The key format is `cellKey(...cell)`: the cell coordinates joined by
  commas, such as `"3,-1"` or `"3,-1,0"`, where a cell coordinate is
  `Math.floor(position / cellSize)`.
- Entities with no position on those axes get `EVERYWHERE` (`"*"`),
  which every connection subscribes to, so every connection sees them.
- While `around(connection)` returns `undefined`, the connection
  subscribes only to `EVERYWHERE`.

Give the grid either a `range` or a `radius`:

- **`range`**, in world units: a connection sees the entities within
  that straight-line distance of `around(connection)` on the chosen axes,
  a circle for `"xy"` and `"xz"` and a sphere for `"xyz"`. The grid
  subscribes it to the cells that overlap that circle, and its `sees`
  drops the entities in those cells that are further away. Visibility is
  exact: an entity at distance `range` is seen and one a little past it
  isn't, wherever either stands in its cell.
- **`radius`**, a whole number of cells: a connection subscribes to its
  own cell and every cell within `radius` cells of it on each axis, a
  square of (2 × radius + 1)² cells, or a cube for `"xyz"`. It sees
  every entity in them, so how far it sees depends on where it stands in
  its cell: at least `radius × cellSize` along an axis, up to
  `(radius + 1) × cellSize`, and further across the corners. `sees` is
  undefined. Use it when cells, such as voxel chunks, are what matters.

### Combining grids and keys

`combine(...parts)` joins grids, and parts with keys of your own, into
one interest. A connection sees an entity when, in at least one part,
they share a key and that part's `sees`, if it has one, returns `true`.
So each grid keeps its own semantics: a `radius` grid shows its whole
cells, and a `range` grid's distance check applies only to what it
placed, not to what another part shows.

```ts
function combine(...parts: InterestPart[]): Required<InterestPart>;
```

Give each grid the `kinds` it places, or every grid also places the
other grids' entities, as `EVERYWHERE` when they have no position on its
axes, which shows them to everyone. Give each grid a `prefix` too, so
cells of different sizes don't share keys; `combine` stays exact without
one, but entities in a cell with the same key as one of another grid
are then checked by `sees` for nothing. Put `limit` beside it:

```ts
// world-room.ts
import { combine, defineRoom, grid, type Connection, type Room, type RoomEntity } from "@irt/room";
import { Chunk, Player, schema } from "./schema.js";

type P = RoomEntity<typeof Player>;
const CHUNK = 32;
const at = (p: P | undefined) => (p ? ([p.x, p.y, p.z] as const) : undefined);

// Chunks within 2 chunks on each axis, placed by chunk coordinates.
const chunks = grid({
  cellSize: CHUNK,
  radius: 2,
  dims: "xyz",
  kinds: [Chunk],
  prefix: "c:",
  position: (_room, e) => {
    const c = e as RoomEntity<typeof Chunk>;
    return [c.cx * CHUNK, c.cy * CHUNK, c.cz * CHUNK];
  },
  // A point, since `position` above reads chunk fields.
  around: (_room, conn) => at(conn.data.player),
});

// Players within 80 units, by their x, y and z.
const players = grid({ cellSize: 32, range: 80, dims: "xyz", kinds: [Player], prefix: "p:", around: (_room, conn) => conn.data.player });

// Every player sees its own entity, however far it is from where `around` says.
const self = {
  keysOf: (_room: Room, e: RoomEntity) => (e.kind === Player ? [`me:${(e as P).owner}`] : []),
  subscriptionsOf: (_room: Room, conn: Connection) => [`me:${conn.player}`],
};

export default defineRoom({
  schema,
  interest: {
    ...combine(chunks, players, self),
    limit: {
      max: 500,
      // Chunks rank first, players by distance.
      priority: (_room, conn, e) => {
        const me = conn.data.player as P | undefined;
        if (!me || e.kind !== Player) return Infinity;
        const p = e as P;
        return -Math.hypot(p.x - me.x, p.y - me.y, p.z - me.z);
      },
    },
  },
  onJoin(room, conn) {
    const existing = [...room.entities.all(Player)].find((p) => p.owner === conn.player);
    conn.data.player = existing ?? room.entities.create(Player, { owner: conn.player });
  },
});
```

The same goes for a `range` grid and keys of your own: with `combine`,
what the keys show isn't dropped by the grid's distance check.

```ts
// near-room.ts
import { combine, defineRoom, defineSchema, entity, grid, type Connection, type Room, type RoomEntity } from "@irt/room";

const Soldier = entity("soldier", { team: "string", x: "f32", y: "f32", z: "f32" });
const teamOf = (c: Connection) => (c.meta as { team: string }).team;

// Teammates are seen at any distance, everyone else within 600 units.
const near = grid({ cellSize: 100, range: 600, dims: "xz", around: (_room, c) => c.data.soldier });
const team = {
  keysOf: (_room: Room, e: RoomEntity) => [`team:${(e as RoomEntity<typeof Soldier>).team}`],
  subscriptionsOf: (_room: Room, c: Connection) => [`team:${teamOf(c)}`],
};

export default defineRoom({
  schema: defineSchema({ entities: [Soldier] }),
  interest: combine(near, team),
  onJoin(room, conn) {
    conn.data.soldier = room.entities.create(Soldier, { team: teamOf(conn) });
  },
});
```

Writing `keysOf`, `subscriptionsOf` and `sees` by hand works too. Then
give the grids prefixes, and remember that an interest's `sees` applies
to every entity, so it must let through what other keys show:
`sees: (room, c, e) => isTeammate(c, e) || near.sees!(room, c, e)`.

### Custom keys

Interest isn't tied to coordinates. Teams, zones and levels are keys too:

```ts
// team-room.ts
import { defineRoom, defineSchema, entity } from "@irt/room";

const Unit = entity("unit", { team: "string", level: "u8" });

export default defineRoom({
  schema: defineSchema({ entities: [Unit] }),
  interest: {
    keysOf: (_room, e) => [`team:${e.team as string}`, `level:${e.level as number}`],
    subscriptionsOf: (_room, conn) => [`team:${(conn.meta as { team: string }).team}`],
  },
});
```

### Limits and hysteresis

`limit: { max, priority }` keeps the `max` entities with the highest
priority in each connection's view. A visible entity stays until it
ranks below `max` plus 10%, so entities near the cut don't enter and
leave every tick.

### Caps

| Cap | Value | Over it |
|---|---|---|
| Interest keys a connection subscribes to | 4,096 | an error in the room's log; the extra keys are left out |
| Entities a connection sees | 16,384 | an error in the room's log; the extra entities are left out |

## On the client

```ts
// client.ts
import { connect } from "@irt/client";
import { Chunk, Player, schema } from "./schema.js";

const room = await connect({ router: "wss://eu.irt.io", project: "my-game", room: "forest-7", schema });

room.entities.onEnter(Chunk, (chunk) => console.log("mesh chunk", chunk.cx, chunk.blocks.length));
room.entities.onChange(Chunk, (chunk, changed) => {
  if (changed.includes("blocks")) console.log("remesh", chunk.id);
});
room.entities.onLeave(Chunk, (chunk) => console.log("drop", chunk.id));
room.onTick((tick) => console.log("applied tick", tick, room.state.phase, room.private.cards));

const players = room.interpolate(Player, ["x", "y", "z"]);
for (const p of room.entities.all(Player)) console.log(p.owner, players.get(p));
```

- A tick's state update is applied at once, then the `onEnter`,
  `onChange` and `onLeave` callbacks run, then `onTick`. A client never
  sees a change before an enter.
- A big tick, such as a new player entering a hundred chunks, spans
  several messages; the client applies them together. The room
  compresses messages of 1 KB or more with DEFLATE, which shrinks voxel
  chunks about 17 times, and the client inflates them; nothing in the
  game changes for it, `patch` included.
- On a reconnect to the same room generation the client resumes: it
  tells the room what it holds, and the room sends only what it doesn't
  hold or what changed since, and a `leave` for what it no longer sees.
  Entities that didn't change keep their objects, and the client emits
  `restored`. On a change of the room's generation, or a reconnect the
  room can't resume, such as after a room host restart, the client gets
  a full update: every entity leaves and enters again.
- `interpolate(kind, fields)` draws numeric fields of remote entities a
  little behind the room's clock (two ticks or 100 ms, whichever is
  longer), between the last two states.

## Common mistakes

- **Expecting `room.state` changes to be seen at once.** Changes go out
  at the end of the tick. Messages sent with `room.send` in the same
  handler arrive before the state update.
- **Mutating a `json` field in place.** Set the field again after
  changing the value, or the change isn't sent.
- **Keeping a score on an entity `onLeave` deletes.** It's gone when the
  player leaves, drops off the network or the room hibernates. Keep it in
  `room.state` or private state; see
  [Where player data lives](#where-player-data-lives).
- **Expecting `radius` to be a distance.** It counts cells, in a square.
  Use `range` for "everything within 600 units".
- **Putting a whole world in one entity.** An entity must fit in 61,376
  bytes. Split worlds into chunk entities.
- **Using a `string` for big data.** Strings are capped at 16 KB; use
  `bytes` (48 KB) and patch it.
- **Grid entities without a position.** They get `EVERYWHERE` and every
  connection sees them; pass `position` when your coordinates aren't
  called `x`, `y` and `z`, and `kinds` when the grid shouldn't place
  them at all.
- **Merging two grids' keys by hand without prefixes.** Their cell keys
  and `EVERYWHERE` collide, and a `range` grid's `sees` drops what the
  other grid shows. Use `combine`.
- **A `position` for chunks with an `around` that returns the player.**
  The grid places that entity with `position` too; return a point
  instead.
- **Searching `all(kind)` in a stepper for static data.** It visits every
  entity of the kind on every call. Give the data computed IDs and use
  `world.get`; see [Entity IDs and lookups](#entity-ids-and-lookups).
- **Assuming `subscriptionsOf` runs only on change.** It runs for every
  connection every tick; keep it cheap.
- **Hiding data with `interest`.** Without an interest every
  connection sees every entity, and one key in common shows it. Declare
  the kind `{ hidden: true }`; see [Hidden entities](#hidden-entities).
- **Writing entities on the client.** They are read-only and a write
  throws, except the writable fields of entities the player owns; see
  [Ownership](/docs/guides/ownership).

---

# Calls

> Ask the room to do something and get its answer, with names, args and replies typed from one declaration.

A **call** is a request from one client that the room answers: buy an
item, claim a seat, look something up. The client awaits the reply, or
the error the room threw. Use calls for actions that need an answer;
for changes everyone sees, the answer can be the state itself, and for
fire-and-forget events, send a message.

## Declaring calls

Calls are declared once, in the schema module the room and its clients
both import. `defineCalls` takes the calls' signatures as a type, each
with at most one argument and its reply:

```ts
// schema.ts
import { defineCalls, defineSchema, entity } from "@irt/room";

export const prices = { sword: 50, shield: 30 };
export type Item = keyof typeof prices;

export const Wallet = entity("wallet", { coins: "u32" });

export const schema = defineSchema({
  private: Wallet,
  calls: defineCalls<{
    buy(args: { item: Item }): { coins: number };
    balance(): number;
  }>({
    buy(raw) {
      const item = (raw as { item?: unknown } | null)?.item;
      if (typeof item !== "string" || !Object.hasOwn(prices, item)) throw new Error("unknown item");
      return { item: item as Item };
    },
  }),
});
```

The object passed to `defineCalls` is optional and holds a `parse`
function for any call that needs one. The types are only types: args
come from the client, and a modified client can send anything. A
`parse` function runs on the room before the handler, gets the decoded
JSON, or the bytes, and returns the args or throws. Without one, the
handler gets the decoded JSON unchecked, so a call without one must
not trust its args; `balance` above takes none.

## In the room

The room's `calls` has a handler for each declared call. TypeScript
checks that none is missing, that `args` has the declared type, and that
the handler returns, or resolves to, the declared reply.

```ts
// room.ts
import { CallRejected, defineRoom } from "@irt/room";
import { prices, schema } from "./schema.js";

export default defineRoom({
  schema,
  onJoin(room, conn) {
    const wallet = room.private(conn);
    if (wallet.coins === 0) wallet.coins = 100;
  },
  calls: {
    buy(room, conn, { item }) {
      const wallet = room.private(conn);
      if (wallet.coins < prices[item]) throw new CallRejected("not enough coins");
      wallet.coins -= prices[item];
      return { coins: wallet.coins };
    },
    balance: (room, conn) => room.private(conn).coins,
  },
});
```

- What a handler throws becomes the client's error, with its message,
  and the room keeps running.
- Throw `CallRejected` for a rejection that's part of the game, such as
  "not enough coins" or "the stairs are sealed": the client gets its
  message and the room logs nothing. Any other error is logged at error
  level with the room, player, tick and stack, because it's taken for a
  bug. A `parse` that throws rejects the call without logging too.
- A handler may be async; the reply goes out when its promise settles.
- Handlers run as calls arrive, between ticks. A call that changed room
  state (shared or private state, entities, ownership, bans) replies
  after the next tick has saved the change and sent its state update,
  up to a tick later: a reply means the change is saved outside the VM
  and a room host crash can't lose it, and the client already has it.
  A call that changed nothing replies at once, unless another change
  is waiting for the same tick. Errors go out at once. What isn't room
  state, such as `room.data` or a stepper's own state, isn't covered.
- A call that changes room state just as the room hibernates fails
  rather than replies, as any call in flight when the connection drops
  does.

## On the client

```ts
// client.ts
import { connect, IrtError } from "@irt/client";
import { schema } from "./schema.js";

const room = await connect({ router: "wss://eu.irt.io", project: "my-game", room: "shop-1", schema });

try {
  const { coins } = await room.call("buy", { item: "sword" });
  console.log("coins left", coins);
} catch (e) {
  if (e instanceof IrtError) console.log("couldn't buy:", e.message);
  else throw e;
}

const balance: number = await room.call("balance");
console.log(balance);
```

`call` takes only declared names, with their args, and resolves to the
declared reply. It rejects with an `IrtError` when the room throws,
after a timeout of 10 seconds by default
(`room.call("balance", undefined, { timeout: 2000 })`), and when the
connection drops or the room restarts before the reply. In those last
cases the call may or may not have run, and the SDK doesn't retry it.
The error's `code` is 422 when the room answered with an error, such as
a `CallRejected`, and 0 when no answer came; see
[Errors](/docs/reference/errors#call).

## Common mistakes

- **Rejecting with a plain `Error`.** It works, but every rejection is
  logged as an error with a stack, which buries real bugs in normal
  traffic. Use `CallRejected` for expected outcomes.
- **Trusting args without `parse`.** The declared type is a promise the
  client makes, not one the room can rely on. Check anything that
  indexes, loops or spends.
- **Retrying a call that changes state.** After a dropped connection the
  room may already have run it. Check with another call, such as
  `balance`, or make the call safe to repeat.
- **Waiting on a call for state everyone sees.** Change the entity in
  the handler and let every client get it from the state update; reply
  with what only the caller needs.

---

# Ownership

> Let players write the values they control, such as a cursor or a dragged card, while the room decides what everyone sees.

Every entity has an **owner**: the room, or a player. The room owns
everything unless it gives an entity to a player, and the owner of an
entity may write the fields its kind declares **writable** straight from
the client, with no round trip. The room still checks each write and
always has the last word.

Use ownership for values a player sets directly: a cursor, aim, a camera,
a piece being dragged, per-player settings. Movement the room simulates
stays room-owned and goes through [prediction](/docs/guides/prediction).
Scores, hit results and anything else that decides the game stay
room-owned too.

## Declaring writable fields

```ts
// schema.ts
import { defineSchema, entity } from "@irt/room";

export const Cursor = entity("cursor", {
  x: "f32",
  y: "f32",
  color: "u8",
}, { writable: ["x", "y"] });

export const Settings = entity("settings", { volume: "u8", coins: "u32" }, { writable: ["volume"] });

export const schema = defineSchema({ private: Settings, entities: [Cursor] });
```

- Only the listed fields can be written by the owner. The rest are the
  room's, even on an entity a player owns, so `color` above is set by the
  room alone.
- Any kind that isn't [hidden](/docs/guides/state-sync#hidden-entities)
  can be given to a player, with or without writable fields. The owner
  of a kind with none can't write it, but the entity is always in its
  view, it's listed by `ownedBy` and `mine`, and its owner-only fields
  reach it.
- `ownerOnly` lists fields only the owner's connections are sent; every
  other connection holds their defaults and gets no changes to them. A
  predicted car's velocity, which only its driver's replay reads, is one:
  `entity("car", { x: "f32", y: "f32", vx: "f32", vy: "f32" }, { ownerOnly: ["vx", "vy"] })`.
  A new owner gets them right after the ownership change; the previous
  owner keeps the values it had. They save bandwidth, and hide only
  values a player never owned. Room state saves them as any field, and
  they're part of the schema hash.
- The shared state, `room.state`, is always the room's and can't have
  writable fields.
- A player owns its own private state, so it can write the private kind's
  writable fields.
- Writable fields are part of the schema hash: a client built with
  different writable fields fails to connect with 4004.

## In the room

```ts
// room.ts
import { defineRoom } from "@irt/room";
import { Cursor, schema } from "./schema.js";

export default defineRoom({
  schema,
  onJoin(room, conn) {
    if ([...room.entities.ownedBy(conn.player, Cursor)].length > 0) return;
    room.entities.create(Cursor, { color: conn.player.length % 8 }, { owner: conn.player });
  },
  onWrite(room, conn, entity, next) {
    if (entity.kind !== Cursor) return next;
    const x = next.x as number | undefined;
    if (x !== undefined && (x < 0 || x > 800)) return { ...next, x: Math.min(Math.max(x, 0), 800) };
    return next;
  },
});
```

- `create(kind, values, { owner })` gives a new entity to a player.
  `room.entities.setOwner(entity, player)` moves one, and
  `setOwner(entity, undefined)` gives it back to the room.
  `ownerOf(entity)` returns the player, or `undefined` for the room, and
  `ownedBy(player, kind)` iterates what a player owns.
- Owners are player IDs, not connections. Ownership survives reconnects
  and is saved in room state, so it survives hibernation. Leaving
  releases nothing; call `setOwner` in `onLeave` if the game needs that.
- The room may write any field of any entity, including fields a player
  owns.

### onWrite

`onWrite(room, connection, entity, next)` runs for each owner write at
the start of the tick, before the stepper. `next` holds the fields
written. Return:

| Return | Applies |
|---|---|
| `next` | the write as sent |
| other values | those values, such as `next` clamped to the board |
| `undefined` | nothing; the write is rejected |

`onWrite` must be synchronous. If it throws, the error is logged and the
write is rejected. Without `onWrite`, writes apply as sent: a writable
field is then a claim the room accepts from the player.

Before `onWrite` runs, the room drops writes to entities the player
doesn't own, to fields that aren't writable, and values of the wrong
type.

## On the client

```ts
// client.ts
import { connect } from "@irt/client";
import { Cursor, schema } from "./schema.js";

const room = await connect({ router: "wss://eu.irt.io", project: "my-game", room: "board-1", schema });

addEventListener("pointermove", (e) => {
  for (const cursor of room.entities.mine(Cursor)) {
    cursor.x = e.clientX;
    cursor.y = e.clientY;
  }
});

room.private.volume = 5;

room.entities.onCorrect(Cursor, (cursor, fields) => console.log("the room moved", cursor.id, fields));
room.entities.onOwner(Cursor, (cursor) => console.log(cursor.id, "is now", room.entities.ownerOf(cursor) ?? "the room's"));
```

- `room.entities.mine(kind)` iterates the entities of a kind the local
  player owns. Setting a writable field changes the client's copy at
  once; writing any other field, or an entity the player doesn't own,
  throws a `TypeError`.
- The client sends its writes at most once per room tick. Within that
  time the last write to a field wins.
- Clients can't create or delete entities, or change an owner. Send the
  room a message and let it decide.

## Corrections

The room wins. A client keeps its own values for the writable fields it
owns and ignores the room's ordinary changes to them. When the room's
value differs from what the owner wrote, because `onWrite` clamped or
rejected it or room code wrote the field, the owner gets a
**correction** with the room's value:

- It overwrites the client's copy and drops the client's unsent writes to
  those fields.
- `onChange` runs for the fields, then `onCorrect`, where a game can snap
  or smooth.
- Every other client only ever sees the room's value.

A correction arrives with the rest of its tick's state update. On a
reconnect or a change of generation, unsent writes are dropped and the
full state update brings the room's values.

## Interest

A player always sees the entities it owns, whatever the room's interest
says. They count toward the cap on entities a connection sees.

## Common mistakes

- **Making fields the stepper writes writable.** The room overwrites the
  owner's value every tick and sends a correction each time. Keep
  simulated movement room-owned and use prediction.
- **Trusting writable fields without `onWrite`.** A modified client can
  write any value of the field's type. Bound what's possible, such as a
  speed or the board's edges.
- **Writing in `onEnter` before the owner op arrives.** An entity given
  to a player mid-game becomes writable when its owner change is applied;
  use `onOwner` or `mine` rather than assuming.

---

# Client prediction

> Make movement feel instant with a stepper shared by the room and the client.

The room is the authority, so a client that waits for the room to move
its player feels a round trip of lag. Prediction runs the room's own
simulation step on the client for the local player, sends the input it
used, and reconciles when the room's state arrives. Everything else on
screen is [interpolated](/docs/guides/state-sync#on-the-client).

## The stepper

A **stepper** is a simulation step the room and its clients share, in a
module both import:

```ts
function defineStepper<I>(stepper: {
  step(world: World, inputs: ReadonlyMap<string, I>, dt: number, tick: number): void;
  parseInput?(raw: unknown): I;
  save?(world: World): unknown;
  load?(saved: unknown, world: World): void;
  release?(world: World): void;
}): Stepper<I>;

interface World {
  all<K extends Kind>(kind: K): Iterable<Entity<K>>;
  get(id: number): Entity | undefined;
  readonly predicted?: Entity;   // on a client's prediction world only
  readonly stateTick?: number;   // on a client's prediction world only
}
```

- `world` is the room's entities, read and written in place; on the
  client it's the client's view. `world.get(id)` is a map lookup;
  `world.all(kind)` visits every entity of the kind on each call, so
  reach static data, such as voxel chunks, by computed IDs; see
  [Entity IDs and lookups](/docs/guides/state-sync#entity-ids-and-lookups).
  The shared state is in it on both sides, as `world.get(SHARED_ID)`
  (0) and in `world.all(schema.state)`, so a stepper can read a race's
  start tick from it. Private state isn't: the room has one per player.
- `inputs` maps player IDs to this tick's input. On the room it holds
  every player that sent one for this tick; on the client only the local
  player's.
- `dt` is the fixed timestep in seconds, `1 / tickRate`.
- `tick` is the room tick being stepped: `room.tick` on the room, and
  on the client the tick of the input being stepped, which is the tick
  the room runs that input at. A rule that depends on time, such as
  holding cars on the grid until `tick` reaches the start, predicts
  exactly.
- `world.predicted` is the predicted entity on a client and undefined on
  the room, for a stepper that simulates only that entity on the client.
- `world.stateTick` is the room tick of the state the client holds, and
  undefined on the room.
- `parseInput` runs on the room only. Inputs arrive as JSON from the
  client, or as the schema's input kind's fields (see
  [Compact inputs](#compact-inputs)); without `parseInput` the room
  passes the decoded input as is, so validate it here and throw to drop
  a bad one.
- `save` and `load` are for caches of the stepper's own, such as a
  physics engine's world. They run on the room only, on hibernate, at
  checkpoints and on wake, never per tick. One stepper serves every room
  in a room host, so they get the room's `world`, the object `step` gets;
  key caches by it. See [Steppers](/docs/room-state#steppers).
- `release` frees what a stepper keeps for a `world` that's gone: on the
  room when the room leaves its room host, and on the client when the
  prediction stops. Only caches the garbage collector can't free
  promptly need it, such as a physics engine's WebAssembly memory.
- For rigid bodies and characters, [`@irt/physics`](/docs/guides/physics)
  is a stepper built on Rapier.

```ts
// shared.ts
import { defineSchema, defineStepper, entity } from "@irt/room";

export const Runner = entity("runner", { owner: "string", x: "f32", y: "f32" });
export const schema = defineSchema({ entities: [Runner] });

export interface Input {
  dx: number;
  dy: number;
}

const SPEED = 6;

export const stepper = defineStepper<Input>({
  parseInput(raw) {
    const i = raw as Partial<Input>;
    if (typeof i.dx !== "number" || typeof i.dy !== "number" || Math.abs(i.dx) > 1 || Math.abs(i.dy) > 1) {
      throw new TypeError("input is { dx, dy } with each from -1 to 1");
    }
    return { dx: i.dx, dy: i.dy };
  },
  step(world, inputs, dt) {
    for (const r of world.all(Runner)) {
      const input = inputs.get(r.owner);
      if (!input) continue;
      r.x += input.dx * SPEED * dt;
      r.y += input.dy * SPEED * dt;
    }
  },
});
```

## The room

```ts
// room.ts
import { defineRoom } from "@irt/room";
import { Runner, schema, stepper } from "./shared.js";

export default defineRoom({
  schema,
  tickRate: 30,
  stepper,
  onJoin(room, conn) {
    // After a crash or a wake the player's runner is still here, and onJoin runs again.
    const existing = [...room.entities.all(Runner)].find((r) => r.owner === conn.player);
    conn.data.runner = existing ?? room.entities.create(Runner, { owner: conn.player });
  },
  onTick(room) {
    // Rules only the room knows; the client reconciles with them.
    for (const r of room.entities.all(Runner)) r.x = Math.min(r.x, 50);
  },
  onPlayerLeave(room, player) {
    for (const r of room.entities.all(Runner)) if (r.owner === player) room.entities.delete(r);
  },
});
```

`onJoin` reuses the player's runner rather than creating one each time:
after a room host crash it runs again with no `onLeave` or
`onPlayerLeave` first. The runner goes in `onPlayerLeave`, which runs
10 seconds after the player's last connection closed with no new one,
so a dropped network and a reconnect keep it, and before every
hibernation; see [State sync](/docs/guides/state-sync).

Each tick the room runs the stepper with each player's input for that
tick, then `onTick`, then sends the state update, then acknowledges the
inputs it applied.

## The client

```ts
// client.ts
import { connect } from "@irt/client";
import { type Input, Runner, schema, stepper } from "./shared.js";

const room = await connect({ router: "wss://eu.irt.io", project: "runners", room: "track-1", schema });

const keys = new Set<string>();
addEventListener("keydown", (e) => keys.add(e.key));
addEventListener("keyup", (e) => keys.delete(e.key));

const me = room.predict(stepper, {
  find: (r) => [...r.entities.all(Runner)].find((e) => e.owner === r.player),
  sample: (): Input => ({
    dx: (keys.has("ArrowRight") ? 1 : 0) - (keys.has("ArrowLeft") ? 1 : 0),
    dy: (keys.has("ArrowDown") ? 1 : 0) - (keys.has("ArrowUp") ? 1 : 0),
  }),
});
const others = room.interpolate(Runner, ["x", "y"]);

function frame() {
  const local = me.render(["x", "y"]);
  for (const r of room.entities.all(Runner)) {
    const at = r.owner === room.player ? local : others.get(r);
    console.log(r.owner, at.x, at.y);
  }
  requestAnimationFrame(frame);
}
frame();
```

`room.predict(stepper, { find, sample })` returns a `Prediction`, typed
by the kind `find` returns:

| Member | Meaning |
|---|---|
| `entity` | The predicted entity: the room's last state plus the inputs it hasn't acknowledged, or `undefined` until `find` finds it. Use it for game logic. |
| `render(fields, opts?)` | The predicted numeric fields plus a decaying share of recent mispredictions, as `Record<field, number>`. Before the first input it's the room's state of the entity, and `NaN` for each field while `find` finds nothing. Use it for drawing. With `{ snapDistance }`, a misprediction of these fields longer than that is dropped instead of smoothed; see [Respawns and teleports](#respawns-and-teleports). |
| `snap()` | Drops every misprediction `render` is smoothing, so it draws `entity` as it is |
| `pending` | Ticks stepped ahead of the room's state: inputs sent and not yet acknowledged, and [idle](#idle-inputs) ticks not sent. With `sample` this stays at about 2 plus half the round trip in ticks, never 0, because inputs are sent ahead of the room's clock |
| `settled` | `true` when the prediction agrees with the room: `entity` equals the room's last state, so the pending inputs move nothing. `render` may still be smoothing away an earlier misprediction |
| `mispredictions` | How many replays found the room's state different from the prediction in a field the stepper writes |
| `onMispredict(fn)` | Calls `fn({ tick, fields, delta })` after each such replay: the room tick it replayed from, the fields that differed, and for numeric ones the prediction's value less the replayed one, which `render` smooths away. Returns an unsubscribe |
| `push(input)` | Sends an input for the next tick and steps the prediction. Only without `sample`. |
| `stop()` | Stops sampling |

How it works:

1. Once per room tick, by the client's estimate of the room's clock, the
   prediction calls `sample()`, steps the predicted entity with the
   input and sends it tagged with the room tick it is for. `sample`
   receives the `Prediction` it belongs to, so it can steer by
   `entity`, which is set before each call whenever `find` finds the
   entity. It's undefined only while `find` finds nothing: before the
   entity enters the client's view, while the room has deleted it, and
   after a reconnect until the full state arrives, so read it as
   `p.entity?.x ?? 0`. The first call is at the next room tick after
   `predict` returns, never during it. After the
   page was paused it calls `sample` up to 4 times at once to catch up
   and skips the rest. It aims 2 ticks ahead of the room, plus half the
   round trip, so the input arrives in time. Each message repeats the
   last 4 inputs, so a lost one costs nothing; see
   [Compact inputs](#compact-inputs) for what that costs.
2. The room holds each input until the tick it names and applies it
   then. An input for a tick that already ran is dropped, and so is one
   more than 32 ticks ahead (`INPUT_WINDOW`). One input per player per
   tick: a later one for the same tick replaces the earlier.
3. After each tick's state update the room sends an ack with the highest
   input it applied or dropped. The client resets the predicted entity
   to the room's state and replays the inputs after the ack. A field
   that a step has written and that came out different is a
   misprediction, and the difference goes into what `render` smooths
   away, 20% per tick. A field no step writes, such as a lap counter
   only `onTick` sets, is the room's: its changes are taken as they
   come, never counted or smoothed.
4. On a reconnect or a new room generation, prediction state is dropped
   and starts again from the room's state.

### Compact inputs

Inputs are JSON unless the schema declares their fields. Each message
repeats the last 4 inputs, so JSON inputs can cost more upstream than
the state a client receives: a shooter's
`{"mx":1,"my":0,"aim":0.1234567,"fire":true,"rocket":false}` is 200
to 300 bytes a message, 6 to 9 KB/s at 30 ticks a second. Declare the input as
a kind, with `entity`, and pass it to `defineSchema` as `input`; inputs
then go as binary, each field encoded as in a state update, with the
repeats' ticks as differences:

```ts
// compact.ts
import { defineSchema, defineStepper, entity, type ValuesOf } from "@irt/room";

export const Ship = entity("ship", { owner: "string", x: "f32", aim: "f32" });
export const ShipInput = entity("input", { mx: "i8", aim: "f32", fire: "bool" });
export type ShipInput = ValuesOf<typeof ShipInput>;
export const compactSchema = defineSchema({ entities: [Ship], input: ShipInput });

export const shipStepper = defineStepper<ShipInput>({
  parseInput(raw) {
    const i = raw as ShipInput;
    if (Math.abs(i.mx) > 1) throw new RangeError("mx is -1, 0 or 1");
    return i;
  },
  step(world, inputs, dt) {
    for (const s of world.all(Ship)) {
      const input = inputs.get(s.owner);
      if (!input) continue;
      s.x += input.mx * 100 * dt;
      s.aim = input.aim;
    }
  },
});
```

That shooter's input is then 48 bytes a message, about 1.4 KB/s. `sample`
returns the same object as before. Fields it returns that the kind
doesn't declare are dropped, on the client as on the room. An input
that isn't an object, or with a field missing or of the wrong type,
throws a `TypeError` naming the field and stops the prediction, as
`stop()` does; call `predict` again once `sample` is fixed. `f32` fields are
rounded with `Math.fround` before the client steps with them, as the
room will see them, so the prediction stays exact. `parseInput` gets an
object of the kind's fields with their types, so check ranges and
leave types to the encoding. The input kind is part of the schema hash,
so a site built with a different input layout fails to connect with
4004, as for any other schema change. `room.stats.sent` shows what
inputs cost, under `typedInput` for these and `input` for JSON ones.

### Idle inputs

A predicting client sends an input message every tick, even standing
still. Pass `idle` to say which inputs mean the same as none:

```ts
const me = room.predict(stepper, { find, sample, idle: (i) => i.dx === 0 && i.dy === 0 });
```

Once the room has acknowledged every input that wasn't idle, an idle
input isn't sent, and both sides step that tick with no input: the room
because none arrived, the client because it skipped it. That holds only
if the stepper treats a missing input as the idle one, as the runner's
`if (!input) continue` does. While an earlier input awaits its ack,
idle inputs are still sent, so the repeats in each message carry the
inputs from just before the player stopped past a lost message. A
standing player then sends only pings.

### Respawns and teleports

A respawn or a teleport that room code does in `onTick` is a rule the
stepper can't predict, so it arrives as a misprediction, and `render`
would slide the player from the old spot to the new one over half a
second. Pass a `snapDistance` to `render`, longer than any misprediction
of ordinary play, and one longer than that is drawn at once:

```ts
const local = me.render(["x", "y"], { snapDistance: 64 });
```

Where the entity itself says it jumped, call `me.snap()` instead; it
drops whatever `render` is smoothing. The misprediction lands when the
room's ack arrives, after the tick's state update and any message the
room sent in that tick, so watch a field the room sets with the jump,
such as a `spawns` counter, and snap in the frame where `me.entity`
shows the new value:

```ts
if (me.entity && me.entity.spawns !== lastSpawns) {
  lastSpawns = me.entity.spawns;
  me.snap();
}
```

### The prediction world

On the client the stepper runs on a prediction world. The predicted
entity is writable. Every other entity is a copy whose writes last
until the prediction next replays from the room's state, at the next
ack, so a step's effect on another entity holds exactly as long as the
input that caused it is unacknowledged; once the room acks it, the
room's state has the effect, or doesn't if the room rejected it. Don't
mutate a `bytes` value in place in a stepper; on the client it's the
client's own copy of room state. Use `entity.patch(field, offset,
bytes)`, which works on both sides.

The prediction world is one object for the life of the `Prediction`,
so a cache a stepper keys by `world` lasts across its steps and replays.
A replay starts from the room's state, but such a cache doesn't rewind
with it, so keep only data derived from static entities in it, such as
a voxel chunk's collision shapes, never state a step advances.
`@irt/physics` keeps its Rapier world this way, and makes a body's
colliders again when its kind's
[`shapeKey`](/docs/guides/physics#shapes-that-change) changes.

### Predicting edits

An edit the player makes next to its own entity, such as digging the
block under its feet, mispredicts if it goes as a message: the room
applies it when it arrives, while the prediction has already stepped
past with the old blocks. Send it as fields of the input instead, and
apply it in the stepper:

```ts
const DigInput = entity("input", { dx: "i8", edit: "u8", ex: "i16", ey: "u8", ez: "i16", eb: "u8" });

step(world, inputs) {
  for (const p of world.all(Player)) {
    const i = inputs.get(p.owner);
    if (i?.edit && inReach(p, i) && p.editsLeft > 0) {
      chunkAt(world, i.ex, i.ez)?.patch("blocks", blockIndex(i.ex, i.ey, i.ez), new Uint8Array([i.eb]));
      p.editsLeft--;
    }
    // ...movement, which now sees the edited block.
  }
}
```

The room applies the edit at the input's tick and the client predicts
it at the same tick, so an edit the room accepts mispredicts nothing.
Checks the room makes, such as reach and a rate limit, go in the
stepper too, with the rate limit's state in an entity field, as
`editsLeft` is, so the client predicts it.

Inputs are best-effort, unlike messages. The room drops an input that
arrives after its tick has run or more than 32 ticks ahead, and
acknowledges it as handled; each message repeats only the last 4
inputs; and the client keeps at most 64 unacknowledged ones. Under lag
or loss an edit sent as an input can be lost without an error, and the
player sees the block come back when the prediction replays. A message
arrives in order or the connection drops. Use inputs for edits a player
makes while moving next to them, where a lost edit costs a retry, and
messages or calls for edits that must land: rare or costly ones, ones
not tied to the player's movement, and anything the game records, such
as a build placed from an inventory.

## Shooting and lag compensation

A player aims at remote players drawn by
[`interpolate`](/docs/guides/state-sync#on-the-client), which shows them
a little in the past, while the room resolves the shot at its own
current tick. Checking the shot against where targets are now misses
anything that moves. Rewind the targets to what the shooter saw, as
[Lag compensation](/docs/guides/lag-compensation) shows with
`defineHistory` and `room.rewind`. The ticks involved:

- **Values at tick T** are an entity's fields at the end of tick T,
  after the stepper and `onTick`: what the state update for tick T
  carries, and what `room.rewind(history, T)` returns.
- **`interpolate`** draws remote entities at render time
  `serverTick() - max(2 ticks, 100 ms)`, between the updates for the
  tick before that time and the tick after it.
- **`conn.viewTick`** is that render time, rounded down to a tick and
  never past the last update the client has, when the client sampled
  the input the room applies this tick. During the stepper and
  `onTick` it's the view tick of this tick's input, or of the last one
  applied, and at most `MAX_REWIND_MS` (250 ms) behind the room. The
  shooter saw targets between their values at `viewTick` and
  `viewTick + 1`, so allow a tick of their movement in the hit test.
- Don't rewind the shooter. Its input moved it in this tick's step, as
  its prediction did on its screen.
- On a link slower one way than the other, the client's estimate of
  the room's tick is off by half the difference, so `viewTick` is too.
  See [how accurate `serverTick()` is](/docs/reference/client-sdk#roomclient).

## Testing it

`TestClient.predict` samples once per room tick as the test moves the
clock. Since `pending` never reaches 0 while sampling, wait for `settled`
to know the prediction has caught up with the room:

```ts
// prediction.test.ts
import { testRoom } from "@irt/testing";
import { expect, test } from "vitest";
import room from "./room.js";
import { Runner, stepper } from "./shared.js";

test("the client's prediction converges on the room's wall", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  let dx = 1;
  const me = alice.predict(stepper, {
    find: (r) => [...r.entities.all(Runner)].find((e) => e.owner === r.player),
    sample: () => ({ dx, dy: 0 }),
  });
  await t.host.tick(300);
  expect(me.settled).toBe(false);
  dx = 0;
  await t.host.tick(30);
  expect(me.mispredictions).toBeGreaterThan(0);
  expect(me.settled).toBe(true);
  expect(me.entity!.x).toBe(50);
  // render is still smoothing the last misprediction away, by 20% a tick.
  expect(me.render(["x"]).x).toBeCloseTo(50, 1);
});

test("sample can steer by the prediction it belongs to", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  const me = alice.predict(stepper, {
    find: (r) => [...r.entities.all(Runner)].find((e) => e.owner === r.player),
    sample: (p) => ({ dx: (p.entity?.x ?? 0) < 10 ? 1 : 0, dy: 0 }),
  });
  await t.host.tick(120);
  expect(me.settled).toBe(true);
  expect(me.entity!.x).toBeGreaterThanOrEqual(10);
});
```

## Common mistakes

- **Steppers that depend on anything but `world`, `inputs`, `dt` and
  `tick`.** `Math.random()`, `Date.now()` or module state make the
  client's replay differ from the room, and every tick becomes a
  misprediction.
- **Moving the predicted entity outside the stepper.** Room code in
  `onTick` that moves it produces a misprediction each tick; put movement in
  the stepper and keep `onTick` for rules the client can't predict.
- **Calling `push` and passing `sample`.** With `sample` the prediction
  pushes for you; pushing as well sends two inputs per tick.
- **Waiting for `pending` to reach 0 in a test.** With `sample` it
  doesn't; assert on `settled`.
- **Drawing `entity` instead of `render(...)`.** `entity` jumps on a
  misprediction; `render` smooths it.
- **Trusting inputs in the room.** Without `parseInput`, `step` receives
  whatever the client sent: any JSON, or with an input kind any value
  its field types hold.
- **Predicting other players.** Interpolate them; only the local player's
  entity is predicted. Others in the prediction world are where the
  client last saw them, or with [`@irt/physics`](/docs/guides/physics),
  dynamic bodies are extrapolated to the tick being predicted.

---

# Lag compensation

> Check a shot against where the target was on the shooter's screen, by rewinding recent entity positions on the room.

A player aims at what their screen shows, and that is the past: other
players are drawn with [interpolation](/docs/guides/prediction#the-client),
a little behind the room's clock, and the shot takes half a round trip
to reach the room. By the time the room sees the shot, the target has
moved on, so a check against where the target is now misses a shot that
was on target.

Lag compensation fixes this on the room. Each input carries the tick of
the state the player was looking at, `connection.viewTick`. The room
records where the entities you choose were at each recent tick, and
`room.rewind` hands back those positions at the view tick to check the
shot against.

## Recording a history

`defineHistory(kind, fields)` declares which fields of a kind the room
records, and the room's `history` lists the declarations:

```ts
export const poses = defineHistory(Player, ["x", "y"]);

export default defineRoom({ schema, stepper, history: [poses] /* ... */ });
```

After each tick's state update, the room copies those fields of every
entity of the kind into a ring of recent ticks. Only `bool` and number
fields can be recorded. Record what a hit check reads, usually the
position and maybe a rotation, and not the rest: each field costs memory
for every entity of the kind.

`room.rewind(history, tick)` returns the entities as that tick's state
update sent them, as a `ReadonlyMap` from entity ID to a frozen object
holding `id` and the recorded fields:

- An entity created after `tick`, or deleted at or before it, is
  absent. An ID that was deleted and created again gives whichever
  entity had it at `tick`.
- A tick older than the oldest the room kept is clamped to the oldest.
- A tick the room hasn't recorded yet gives the entities as they are
  now. In `onTick` that includes `room.tick` itself, since the tick is
  recorded once its state update goes out.
- A history the room's `history` doesn't list throws.

## Checking a shot

The shot travels in the player's input, so the room knows which tick the
player was looking at when they fired. The stepper moves players, and
`onTick`, which runs right after it, checks shots: `connection.input` is
the input applied this tick, after `parseInput`, and `connection.viewTick`
is the tick the player saw when sending it.

A stepper can't rewind, and shouldn't decide hits. It also runs on the
client to predict the local player, and a client keeps no history of the
room; a hit is the room's call. Keep the shot in the input, ignore it in
the stepper, and handle it in `onTick`.

A top-down arena, where a shot is a ray from the shooter that hits the
first other player it passes within half a unit of:

```ts
// shared.ts
import { defineHistory, defineSchema, defineStepper, entity } from "@irt/room";

export const Player = entity("player", { owner: "string", x: "f32", y: "f32", hp: "u8" });
export const schema = defineSchema({ entities: [Player] });
export const poses = defineHistory(Player, ["x", "y"]);

export interface Input {
  dx: number;
  dy: number;
  /** The direction of a shot fired this tick. */
  fire?: { x: number; y: number };
}

const SPEED = 8;
const finite = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v);

export const stepper = defineStepper<Input>({
  parseInput(raw) {
    const { dx, dy, fire } = raw as { dx?: unknown; dy?: unknown; fire?: { x?: unknown; y?: unknown } };
    if (!finite(dx) || !finite(dy) || Math.hypot(dx, dy) > 1.0001) throw new TypeError("input is { dx, dy, fire? }");
    if (fire === undefined) return { dx, dy };
    if (!finite(fire.x) || !finite(fire.y) || (fire.x === 0 && fire.y === 0)) throw new TypeError("fire is a direction { x, y }");
    return { dx, dy, fire: { x: fire.x, y: fire.y } };
  },
  step(world, inputs, dt) {
    for (const p of world.all(Player)) {
      const input = inputs.get(p.owner);
      if (!input) continue;
      p.x += input.dx * SPEED * dt;
      p.y += input.dy * SPEED * dt;
    }
  },
});
```

```ts
// room.ts
import { defineRoom, type RoomEntity } from "@irt/room";
import { type Input, Player, poses, schema, stepper } from "./shared.js";

const RADIUS = 0.5;
const RANGE = 40;
const SPAWNS = [
  { x: -8, y: 0 },
  { x: 0, y: 10 },
];

type Point = { x: number; y: number };

/** How far along the shot it passes within RADIUS of `p`, or undefined if it doesn't. */
function along(from: Point, dir: Point, p: Point): number | undefined {
  const len = Math.hypot(dir.x, dir.y);
  const t = ((p.x - from.x) * dir.x + (p.y - from.y) * dir.y) / len;
  if (t < 0 || t > RANGE) return undefined;
  const miss = Math.hypot(from.x + (dir.x / len) * t - p.x, from.y + (dir.y / len) * t - p.y);
  return miss <= RADIUS ? t : undefined;
}

export default defineRoom({
  schema,
  stepper,
  history: [poses],
  onJoin(room, conn) {
    const spawn = SPAWNS[(room.connections.size - 1) % SPAWNS.length]!;
    conn.data.player = [...room.entities.all(Player)].find((e) => e.owner === conn.player) ?? room.entities.create(Player, { owner: conn.player, ...spawn, hp: 100 });
  },
  onPlayerLeave(room, player) {
    for (const e of room.entities.all(Player)) if (e.owner === player) room.entities.delete(e);
  },
  onTick(room) {
    for (const conn of room.connections.values()) {
      const fire = (conn.input as Input | undefined)?.fire;
      const shooter: RoomEntity<typeof Player> = conn.data.player;
      if (!fire) continue;
      // The shot leaves from where the shooter is now, and hits others where the shooter saw them.
      let nearest: { id: number; t: number } | undefined;
      for (const target of room.rewind(poses, conn.viewTick).values()) {
        if (target.id === shooter.id) continue;
        const t = along(shooter, fire, target);
        if (t !== undefined && (!nearest || t < nearest.t)) nearest = { id: target.id, t };
      }
      // The target may have left since the tick the shooter saw.
      const hit = nearest && (room.entities.get(nearest.id) as RoomEntity<typeof Player> | undefined);
      if (!hit) continue;
      hit.hp = Math.max(0, hit.hp - 25);
      room.broadcast({ type: "hit", shooter: conn.player, target: hit.owner });
    }
  },
});
```

The client draws other players with `room.interpolate`, which is what
the view tick describes, and fires toward a click:

```ts
// client.ts
import { connect } from "@irt/client";
import { type Input, Player, schema, stepper } from "./shared.js";

const room = await connect({ router: "wss://eu.irt.io", project: "arena", room: "pit-1", schema });
const UNIT = 32;

const keys = new Set<string>();
addEventListener("keydown", (e) => keys.add(e.key));
addEventListener("keyup", (e) => keys.delete(e.key));
let clicked: { x: number; y: number } | undefined;
addEventListener("pointerdown", (e) => (clicked = { x: e.clientX / UNIT, y: e.clientY / UNIT }));

const me = room.predict(stepper, {
  find: (r) => [...r.entities.all(Player)].find((p) => p.owner === r.player),
  sample: (prediction): Input => {
    const input: Input = {
      dx: (keys.has("ArrowRight") ? 1 : 0) - (keys.has("ArrowLeft") ? 1 : 0),
      dy: (keys.has("ArrowDown") ? 1 : 0) - (keys.has("ArrowUp") ? 1 : 0),
    };
    const at = prediction.entity;
    if (clicked && at && (clicked.x !== at.x || clicked.y !== at.y)) input.fire = { x: clicked.x - at.x, y: clicked.y - at.y };
    clicked = undefined;
    return input;
  },
});
const others = room.interpolate(Player, ["x", "y"]);
room.on("message", (m) => console.log(m));

function frame() {
  const local = me.render(["x", "y"]);
  for (const p of room.entities.all(Player)) {
    const at = p.owner === room.player ? local : others.get(p);
    console.log(p.owner, p.hp, at.x * UNIT, at.y * UNIT);
  }
  requestAnimationFrame(frame);
}
frame();
```

The test has the target run past while the shooter fires at it as the
shooter's client draws it. By the time the room checks the shot, the
target is more than a unit further on, three times the hit radius:

```ts
// arena.test.ts
import type { RoomClient } from "@irt/client";
import { testRoom } from "@irt/testing";
import { expect, test } from "vitest";
import room from "./room.js";
import { type Input, Player, stepper } from "./shared.js";

/** Fires once at the target as the shooter's client draws it, `offset` units along x; returns the target's hp. */
async function arena(offset: number) {
  const t = testRoom(room);
  const target = await t.connect({ player: "target" });
  const shooter = await t.connect({ player: "shooter" });
  const drawn = shooter.client.interpolate(Player, ["x", "y"]);
  const find = (r: RoomClient) => [...r.entities.all(Player)].find((p) => p.owner === r.player);
  target.predict(stepper, { find, sample: () => ({ dx: 1, dy: 0 }) });
  let shots = 0;
  shooter.predict(stepper, {
    find,
    sample: (prediction): Input => {
      const me = prediction.entity;
      const other = [...shooter.client.entities.all(Player)].find((p) => p.owner === "target");
      if (t.live.tick < 20 || shots > 0 || !me || !other) return { dx: 0, dy: 0 };
      shots++;
      const at = drawn.get(other);
      return { dx: 0, dy: 0, fire: { x: at.x + offset - me.x, y: at.y - me.y } };
    },
  });
  await t.host.tick(30);
  return [...t.live.entities.all(Player)].find((p) => p.owner === "target")!.hp;
}

test("a shot at the target where the shooter saw it hits, though it has moved on", async () => {
  expect(await arena(0)).toBe(75);
});

test("a shot that missed on the shooter's screen misses", async () => {
  expect(await arena(-1)).toBe(100);
});
```

The shooter's own position is the present one: its client predicts it,
so the room's present position is what the shooter saw of itself.

## With physics

A Rapier world holds the present, and rebuilding one for a past tick
costs too much for a hit check. `@irt/physics` instead offers
`castRay(ray, maxToi, targets, shape)`, which casts a ray against
targets placed at their poses with Rapier shapes, with no world. Record
the pose fields in a history, rewind, and cast against the result:

```ts
// soldiers.ts
import { defineHistory, defineRoom, defineSchema, entity, type RoomEntity } from "@irt/room";
import { body, castRay, physics, RAPIER } from "@irt/physics/rapier3d";

const Soldier = entity("soldier", { owner: "string", x: "f32", y: "f32", z: "f32", vy: "f32" });
const poses = defineHistory(Soldier, ["x", "y", "z"]);
const capsule = new RAPIER.Capsule(0.5, 0.3);

type Input = { dx: number; dz: number; fire?: { x: number; y: number; z: number } };

const stepper = physics<Input>({
  gravity: { x: 0, y: -9.81, z: 0 },
  bodies: [
    body(Soldier, {
      type: "character",
      colliders: () => RAPIER.ColliderDesc.capsule(0.5, 0.3),
      player: (s) => s.owner,
      control({ entity: s, move }, input, dt) {
        s.vy -= 9.81 * dt;
        if (move((input?.dx ?? 0) * 6 * dt, s.vy * dt, (input?.dz ?? 0) * 6 * dt) && s.vy < 0) s.vy = 0;
      },
    }),
  ],
});

export default defineRoom({
  schema: defineSchema({ entities: [Soldier] }),
  stepper,
  history: [poses],
  onJoin(room, conn) {
    conn.data.soldier = room.entities.create(Soldier, { owner: conn.player, y: 1 });
  },
  onTick(room) {
    for (const conn of room.connections.values()) {
      const fire = (conn.input as Input | undefined)?.fire;
      const me: RoomEntity<typeof Soldier> = conn.data.soldier;
      if (!fire) continue;
      const others = [...room.rewind(poses, conn.viewTick).values()].filter((s) => s.id !== me.id);
      const ray = new RAPIER.Ray({ x: me.x, y: me.y + 0.6, z: me.z }, fire);
      const hit = castRay(ray, 100, others, () => capsule);
      if (hit) room.broadcast({ type: "hit", target: hit.target.id, distance: hit.toi });
    }
  },
});
```

Walls and other fixed bodies don't move, so their present is their
past: to stop shots at walls, cast against the room's own world with
`stepper.rapierWorld(room.entities)!.castRay(ray, maxToi, true)` and
count a player hit only if it's nearer than the wall. In 2D, `castRay`
takes poses of `x`, `y` and an optional `angle`, as the
[physics reference](/docs/reference/physics#castray) shows.

## What the room keeps

- **How far back.** A view tick is never more than `MAX_REWIND_MS`
  (250 ms) behind the room; the room clamps it. A history keeps that
  many ticks plus two: 7 ticks at 20 ticks a second, 17 at 60, 32 at 120.
- **Memory.** Each recorded entity costs 8 bytes per field per kept
  tick, plus about 128 bytes. Three fields at 60 ticks a second is 536
  bytes an entity, so 1,000 players take about half a megabyte. A room's
  histories together are capped at 8 MB (`MAX_HISTORY`). Over it, the
  room logs an error once and new entities aren't recorded, so they're
  absent from `room.rewind`, until deleted entities leave the window and
  free their share.
- **Not room state.** The history is in the room host's memory only. It
  isn't saved, isn't checkpointed, and starts empty when the room wakes
  or its room host restarts; until the room has run a tick again,
  `room.rewind` gives the present.

## Common mistakes

- **Checking hits in the stepper.** The stepper runs on the client too,
  and has no history or view tick there. Check hits in `onTick`.
- **Sending shots as messages.** A message carries no view tick, and
  `connection.viewTick` is that of the last input, which may be from
  another tick. Put the shot in the input.
- **Rewinding the shooter.** Its client predicts it, so it saw itself
  where the room has it now. Fire from the present position.
- **Recording every field.** Each field costs 8 bytes per tick for every
  entity of the kind. Record what the hit check reads.
- **Drawing others without interpolation.** The view tick is what
  `room.interpolate` draws. A client that draws the latest state shows
  entities about two ticks ahead of its view tick, and shots there land
  behind the target.
- **Trusting a rewound hit absolutely.** Rewinding favours the shooter:
  a target that just ran behind a wall can still be hit, by up to the
  shooter's lag. The 250 ms cap bounds it.

---

# Physics

> Rigid bodies and characters with Rapier 2D or 3D, stepped by the room and predicted on the client.

`@irt/physics` runs [Rapier](https://rapier.rs) as a
[stepper](/docs/guides/prediction#the-stepper): the room steps a Rapier
world each tick and writes each body's pose into its entity's fields,
and the client runs the same stepper to predict the local player. The
entity fields are the synced state. The Rapier world is a cache the
stepper rebuilds from them, or restores from room state on wake.

Install the package and the one engine your game uses:

```sh
npm install @irt/physics @dimforge/rapier2d-compat   # or @dimforge/rapier3d-compat
```

Import `@irt/physics/rapier2d` or `@irt/physics/rapier3d`. Each loads
only its own engine, and games that don't import either ship none of it.
Rapier is compiled to WebAssembly and inlined in the package, so it works
in any bundler and in the room host with no setup, but it adds over a
megabyte, gzipped, to a client that imports it. The import finishes
loading Rapier before your code runs.

## Bodies

`physics({ gravity, bodies })` returns a stepper. Each `body(kind, ...)`
gives entities of a kind a body, posed by fields with fixed names:

| | 2D | 3D |
|---|---|---|
| Position, required | `x`, `y` | `x`, `y`, `z` |
| Rotation | `angle` | `qx`, `qy`, `qz`, `qw` |
| Velocity, dynamic bodies only | `vx`, `vy` | `vx`, `vy`, `vz` |
| Angular velocity, dynamic bodies only | `spin` | `wx`, `wy`, `wz` |

The fields must be `f32` or `f64`. A kind without rotation fields gets a
body that doesn't rotate. A dynamic body's velocity is kept in the
Rapier world and saved with it, so declare velocity fields only when
clients need them, such as to predict a dynamic body; they add bytes to
every state update while the body moves. On other body types those
names are free for game state, such as a character's vertical speed.

Body types:

- `dynamic`: moved by gravity, collisions, forces and impulses.
- `fixed`: never moves; walls, floors and terrain.
- `kinematic`: moved only by your `control`, with
  `body.setNextKinematicTranslation`; moving platforms.
- `character`: a kinematic body moved by Rapier's character controller
  through `move`, which slides along walls and slopes and says whether
  it ends on the ground.

`colliders(entity)` returns the shapes attached to an entity's body,
made when the body is. A shape that changes, such as a voxel chunk's,
needs a `shapeKey`; see [shapes that change](#shapes-that-change).
`body(desc, entity)` adjusts the body before it's made: damping, CCD,
gravity scale.

## A 2D example

```ts
// shared.ts
import { defineSchema, entity } from "@irt/room";
import { body, physics, RAPIER } from "@irt/physics/rapier2d";

export const Crate = entity("crate", { x: "f32", y: "f32", angle: "f32" });
export const Platform = entity("platform", { x: "f32", y: "f32", w: "f32", h: "f32" });
export const Hero = entity("hero", { owner: "string", x: "f32", y: "f32", vy: "f32", grounded: "bool" });
export const schema = defineSchema({ entities: [Crate, Platform, Hero] });

export interface Input {
  dx: number;
  jump: boolean;
}

export const stepper = physics<Input>({
  gravity: { x: 0, y: -20 },
  parseInput(raw) {
    const i = raw as Partial<Input>;
    if (typeof i.dx !== "number" || Math.abs(i.dx) > 1 || typeof i.jump !== "boolean") {
      throw new TypeError("input is { dx, jump }");
    }
    return { dx: i.dx, jump: i.jump };
  },
  bodies: [
    body(Crate, { type: "dynamic", colliders: () => RAPIER.ColliderDesc.cuboid(0.5, 0.5) }),
    body(Platform, { type: "fixed", colliders: (p) => RAPIER.ColliderDesc.cuboid(p.w / 2, p.h / 2) }),
    body(Hero, {
      type: "character",
      colliders: () => RAPIER.ColliderDesc.capsule(0.3, 0.4),
      player: (h) => h.owner,
      character: (c) => c.enableSnapToGround(0.1),
      control({ entity: hero, move }, input, dt) {
        if (!input) return;
        hero.vy = input.jump && hero.grounded ? 9 : hero.vy - 20 * dt;
        hero.grounded = move(input.dx * 6 * dt, hero.vy * dt);
        if (hero.grounded && hero.vy < 0) hero.vy = 0;
      },
    }),
  ],
});
```

```ts
// room.ts
import { defineRoom } from "@irt/room";
import { Crate, Hero, Platform, schema, stepper } from "./shared.js";

export default defineRoom({
  schema,
  tickRate: 30,
  stepper,
  onCreate(room) {
    room.entities.create(Platform, { x: 0, y: -0.5, w: 60, h: 1 });
    for (let i = 0; i < 5; i++) room.entities.create(Crate, { x: 8, y: 1 + i * 1.2 });
  },
  onJoin(room, conn) {
    conn.data.hero = [...room.entities.all(Hero)].find((e) => e.owner === conn.player) ?? room.entities.create(Hero, { owner: conn.player, x: 0, y: 1 });
  },
  onPlayerLeave(room, player) {
    for (const e of room.entities.all(Hero)) if (e.owner === player) room.entities.delete(e);
  },
});
```

```ts
// client.ts
import { connect } from "@irt/client";
import { Crate, Hero, type Input, schema, stepper } from "./shared.js";

const room = await connect({ router: "wss://eu.irt.io", project: "crates", room: "yard-1", schema });

const keys = new Set<string>();
addEventListener("keydown", (e) => keys.add(e.key));
addEventListener("keyup", (e) => keys.delete(e.key));

const me = room.predict(stepper, {
  find: (r) => [...r.entities.all(Hero)].find((h) => h.owner === r.player),
  sample: (): Input => ({
    dx: (keys.has("ArrowRight") ? 1 : 0) - (keys.has("ArrowLeft") ? 1 : 0),
    jump: keys.has(" "),
  }),
});
const heroes = room.interpolate(Hero, ["x", "y"]);
const crates = room.interpolate(Crate, ["x", "y", "angle"]);

function frame() {
  const local = me.render(["x", "y"]);
  for (const h of room.entities.all(Hero)) {
    const at = h.owner === room.player ? local : heroes.get(h);
    console.log("hero", h.owner, at.x, at.y);
  }
  for (const c of room.entities.all(Crate)) {
    const at = crates.get(c);
    console.log("crate", c.id, at.x, at.y, at.angle);
  }
  requestAnimationFrame(frame);
}
frame();
```

```ts
// physics.test.ts
import { testRoom } from "@irt/testing";
import { expect, test } from "vitest";
import room from "./room.js";
import { Crate, Hero, stepper } from "./shared.js";

test("crates fall and stack, and the hero's prediction agrees with the room", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  let jumps = 0;
  const me = alice.predict(stepper, {
    find: (r) => [...r.entities.all(Hero)].find((h) => h.owner === r.player),
    sample: () => ({ dx: 0, jump: jumps++ < 3 }),
  });
  await t.host.tick(150);

  const ys = [...t.live.entities.all(Crate)].map((c) => c.y).sort((a, b) => a - b);
  expect(ys[0]).toBeCloseTo(0.5, 1);
  expect(ys[4]).toBeCloseTo(4.5, 0);
  expect(me.mispredictions).toBe(0);
  expect(me.settled).toBe(true);
});
```

## How a tick runs

Each tick, on the room, the stepper:

1. Makes a body for each new entity of a declared kind, removes the
   bodies of deleted ones, and moves each body whose fields were written
   by something else, such as `onJoin` or `onTick`. Writing `x` in room
   code teleports the body; that's how to respawn or place something.
   It updates the colliders of each body whose `shapeKey` changed.
2. Runs `control` for each body of a kind that has one, with its player's
   input for the tick. `input` is undefined when the player sent none or
   the kind has no `player`.
3. Steps the Rapier world, unless every body sleeps and nothing was
   moved or woken, so a settled pile of crates costs almost nothing.
4. Writes the pose, and the velocity fields if declared, of every body
   that moved into its entity. Writing a field its current value records
   nothing, so sleeping bodies send nothing.

`onTick` runs after the stepper, so it sees this tick's poses. For ray
casts and other queries, `stepper.rapierWorld(room.entities)` returns
the room's Rapier world. `stepper.entityOf(room.entities, hit.collider)`
says which entity a ray hit, and `stepper.bodyOf(room.entities, entity)`
returns an entity's body. A body is made again when, for example, its
entity leaves a client's view and comes back, so look it up each time
rather than keeping it. To check a shot against where the shooter saw
its target, cast against rewound poses with `castRay`; see
[Lag compensation](/docs/guides/lag-compensation#with-physics).

## Shapes that change

Colliders are made from `colliders(entity)` when a body is made, and
changing the fields it reads changes nothing by itself. Give the kind a
`shapeKey`: a value that changes whenever `colliders` would return
different shapes, such as an edit count. Each tick, on the room and in
every client's prediction, the stepper compares it with the value the
colliders were made with, and when it differs it makes them again.
Bodies resting on the changed shape wake up, so a crate on a removed
block falls.

Making a collider again costs about as much as making it the first
time, roughly 0.4 ms for a 16 x 32 x 16 voxel chunk. Where an edit
changes little, `reshape` updates the colliders in place instead. It
gets the body's colliders, the entity, and `before`, a copy of the
entity's values when its colliders were last made or reshaped, so it
can find what changed:

```ts
import { defineSchema, entity } from "@irt/room";
import { body, physics, RAPIER } from "@irt/physics/rapier3d";

const SIZE = 16;
// Blocks by x, then z, then y, one byte each; 0 is air.
export const Chunk = entity("chunk", { x: "f32", y: "f32", z: "f32", rev: "u32", blocks: "bytes" });
export const schema = defineSchema({ entities: [Chunk] });

const voxel = (i: number): [number, number, number] => [i % SIZE, Math.floor(i / (SIZE * SIZE)), Math.floor(i / SIZE) % SIZE];

function voxels(blocks: Uint8Array): RAPIER.ColliderDesc {
  const coords: number[] = [];
  for (let i = 0; i < blocks.length; i++) if (blocks[i]) coords.push(...voxel(i));
  return RAPIER.ColliderDesc.voxels(new Int32Array(coords), { x: 1, y: 1, z: 1 });
}

export const stepper = physics({
  gravity: { x: 0, y: -28, z: 0 },
  bodies: [
    body(Chunk, {
      type: "fixed",
      colliders: (c) => voxels(c.blocks),
      // The room adds 1 to rev with every edit to blocks.
      shapeKey: (c) => c.rev,
      reshape([collider], c, before) {
        const n = Math.max(c.blocks.length, before.blocks.length);
        for (let i = 0; i < n; i++) {
          const solid = (c.blocks[i] ?? 0) !== 0;
          if (solid !== ((before.blocks[i] ?? 0) !== 0)) collider!.setVoxel(...voxel(i), solid);
        }
      },
    }),
  ],
});
```

`reshape` mustn't add or remove colliders. Colliders restored from a
saved world are made again if their key isn't a number, string or
boolean, since what they were made from isn't known then.

Two costs come with changing shapes. With `reshape`, the stepper keeps a
copy of each body's entity, bytes fields included, from when its
colliders were made: about 2 MB for a world of 256 voxel chunks, on the
room and again in every client's prediction. And after a fixed body's
colliders are made or changed, the stepper takes a step of no time before
`control` runs, so the character controller sees the new shape that
tick. That step moves nothing, but it runs Rapier's contact solver, so a
predicted dynamic body already in contact can come out of it with a
slightly different velocity than the room's, and get a small
correction.

## Players: inputs and prediction

Drive players with inputs, as above: `control` reads the player's input
and moves a `character` with `move`, or pushes a `dynamic` body with
`body.applyImpulse`. The room validates each input with `parseInput`, and
the client predicts its own body with
[`room.predict`](/docs/guides/prediction), so movement responds at once.

On the client the stepper keeps a Rapier world for the prediction:

- The predicted entity gets its real body type and runs `control`.
- Every other body of a `dynamic` kind is a dynamic proxy, posed before
  each step where it would be at the tick being predicted: its last pose
  the client received, carried on at the velocity between its last two
  poses, and at rest when its last update didn't move it. In 2D its
  angle is extrapolated too; in 3D its rotation isn't. A hit shares
  momentum as on the room, and what the step does to the proxy is
  discarded.
- Every other `character` or `kinematic` body is a kinematic proxy at
  the pose the client last received, moved there over a step when a new
  one arrives, so the solver sees its velocity. Fixed bodies stay fixed.
- When the room's state arrives and the prediction replays, the
  predicted body is moved back to the room's pose first.
- `control` gets `tick`, the room tick being stepped, the same on the
  room and in a replay.

This is prediction of the local player against everything else, not
rollback of the whole world. Contact with other dynamic bodies agrees
with the room as long as they keep their course; a rival's steering, or
a hit on a third body, shows up as a misprediction. Other characters
and kinematic bodies are where the client last saw them, a few ticks
behind, which costs little at walking speed. A predicted dynamic body
agrees exactly while it touches nothing, rotation included: after each
step the stepper rebuilds a body's rotation from its fields, as a replay
does. Around a dynamic body's impacts with a wall, expect small
mispredictions, a few centimetres: Rapier's contact solver starts each
step from the impulses of the last one, which live in the Rapier world,
and a replay from the room's pose doesn't have the room's. Assert a
bound on mispredictions in such tests rather than `settled`. A predicted
`dynamic` body needs velocity fields, or the replay starts from a stale
velocity.

### Ownership instead of inputs

A kind can declare a [writable field](/docs/guides/ownership), such as
a thrust or an aim angle, and `control` can read it from `entity` instead
of reading `input`. It works, and the room applies owner writes before
the stepper, but it isn't tied to ticks the way inputs are, so the client
can't replay it exactly. Use inputs for movement, and writable fields for
values the body only follows, such as where a turret points. Pose fields
can't be writable; `physics` throws if one is.

## Saving across hibernation

When the world has dynamic bodies, `save` returns it as bytes, which the
room state keeps; it runs on hibernate and at checkpoints, never per
tick. On wake, `load` restores the world, so bodies keep their
velocities, contacts and sleep state. Then it reconciles the world with
the entities, which are the truth: a body whose entity is gone is
removed, an entity with no body gets one, and a body whose entity's
fields differ, as after a crash restart from changes newer than the last
checkpoint, is moved to them.

A world without dynamic bodies, such as characters walking on fixed
terrain, keeps all its state in its entities, so `save` returns nothing
and `load` makes every body from its entity. That keeps colliders out of
room state, where a voxel chunk's takes about 4.5 KB, and costs the time
to make them on wake: about 100 ms for 256 voxel chunks of 16 x 32 x 16
on one core. A saved world includes the colliders of fixed bodies too,
so a voxel world with even one dynamic body saves them all; their shape
keys are saved with them, so a wake keeps the colliders whose key still
matches.

A restored world keeps the colliders of the build that saved it. A
build that changes a kind's shapes can drop the saved world in a
[migration](/docs/reference/room-sdk#room-state-and-migrations), with
`stepper: undefined`, and the stepper rebuilds every body from its
entity, losing only velocities.

## Memory

Rapier's WebAssembly memory grows as worlds need it and never shrinks.
When a room hibernates or stops, the room host calls the stepper's
`release`, which frees the room's world for the next room to reuse, but
the room host keeps the memory of its busiest moment until it exits. A
room with thousands of bodies raises the memory of every room in its
room host for that room host's lifetime.

## 3D

The 3D entry is the same API with a third axis and quaternions:

```ts
// arena.ts
import { defineRoom, defineSchema, entity } from "@irt/room";
import { body, physics, RAPIER } from "@irt/physics/rapier3d";

export const Ball = entity("ball", {
  x: "f32", y: "f32", z: "f32",
  qx: "f32", qy: "f32", qz: "f32", qw: "f32",
});
export const Floor = entity("floor", { x: "f32", y: "f32", z: "f32" });
export const Walker = entity("walker", { owner: "string", x: "f32", y: "f32", z: "f32", vy: "f32" });

export const stepper = physics<{ dx: number; dz: number }>({
  gravity: { x: 0, y: -9.81, z: 0 },
  parseInput(raw) {
    const { dx, dz } = raw as { dx: unknown; dz: unknown };
    if (typeof dx !== "number" || typeof dz !== "number" || Math.hypot(dx, dz) > 1) throw new TypeError("input is { dx, dz }");
    return { dx, dz };
  },
  bodies: [
    body(Ball, {
      type: "dynamic",
      colliders: () => RAPIER.ColliderDesc.ball(0.5).setRestitution(0.6),
      body: (desc) => desc.setLinearDamping(0.2),
    }),
    body(Floor, { type: "fixed", colliders: () => RAPIER.ColliderDesc.cuboid(50, 0.5, 50) }),
    body(Walker, {
      type: "character",
      colliders: () => RAPIER.ColliderDesc.capsule(0.5, 0.3),
      player: (w) => w.owner,
      control({ entity: w, move }, input, dt) {
        if (!input) return;
        w.vy -= 9.81 * dt;
        if (move(input.dx * 4 * dt, w.vy * dt, input.dz * 4 * dt) && w.vy < 0) w.vy = 0;
      },
    }),
  ],
});

export default defineRoom({
  schema: defineSchema({ entities: [Ball, Floor, Walker] }),
  tickRate: 30,
  stepper,
  onCreate(room) {
    room.entities.create(Floor, { y: -0.5 });
    for (let i = 0; i < 10; i++) room.entities.create(Ball, { x: i - 5, y: 3 + i, qw: 1 });
  },
  onJoin(room, conn) {
    room.entities.create(Walker, { owner: conn.player, y: 1.5 });
  },
  onTick(room) {
    for (const b of room.entities.all(Ball)) {
      // Writing a pose teleports the body: balls that roll off the floor drop in again.
      if (b.y < -10) {
        b.x = 0;
        b.y = 5;
        b.z = 0;
      }
    }
  },
});
```

## Common mistakes

- **Writable pose fields.** The stepper writes them every tick, so the
  owner would be corrected every tick; `physics` throws.
- **Spawning a character touching the ground.** Rapier's character
  controller can slip through a collider it starts exactly in contact
  with. Spawn characters a little above the ground.
- **Changing a shape without a `shapeKey`.** Colliders are made once
  from `colliders`, so editing the fields it reads does nothing in
  Rapier, on the room or in prediction.
- **Keeping a body or collider across ticks.** Bodies are made again,
  as when an entity leaves a client's view and comes back, and an old
  handle then points at nothing. Look bodies up with `bodyOf`.
- **Randomness or clocks in `control`.** As with any stepper, the client's
  replay then differs from the room.
- **Moving the predicted body in `onTick`.** It teleports the body and
  makes a correction every tick; move it in `control`.
- **Expecting the client to simulate other bodies.** They're proxies at
  their last received pose; draw them with `room.interpolate`.

---

# Bots

> Players the room drives itself, which take seats, appear in presence, and give their seat to a person who joins a full room.

A **bot** is a player that your room's code drives instead of a person:
an opponent for someone playing alone, or a seat filled so a game can
start. A bot is in presence like anyone else, owns entities, and sends
input to your stepper, but it has no connection. It runs inside the
room, so it costs no traffic and doesn't keep the room awake.

A creature or hazard that isn't a player doesn't need a bot. Make it an
entity the room owns and move it in `onTick`.

```ts
// src/room.ts
import { defineRoom, defineSchema, defineStepper, entity } from "@irt/room";

const Car = entity("car", { owner: "string", x: "f32" });

export default defineRoom({
  schema: defineSchema({ entities: [Car] }),
  stepper: defineStepper<number>({
    step(world, inputs) {
      for (const car of world.all(Car)) car.x += inputs.get(car.owner) ?? 0;
    },
  }),
  bots: {
    racer: {
      start(room, bot) {
        if (![...room.entities.all(Car)].some((c) => c.owner === bot.player)) room.entities.create(Car, { owner: bot.player, x: 0 });
      },
      tick(room, bot) {
        bot.input = bot.data.fast ? 2 : 1;
      },
    },
  },
  onCreate(room) {
    room.bots.add("racer", { name: "Rival", data: { fast: true } });
  },
  onJoin(room, conn) {
    room.entities.create(Car, { owner: conn.player, x: 0 });
  },
  onPlayerLeave(room, player) {
    for (const car of room.entities.all(Car)) if (car.owner === player) room.entities.delete(car);
  },
});
```

## A bot

- **Its player ID** is `bot:` and a number the room gives out in order,
  never reused while the room exists. No player token can have a `sub`
  starting with `bot:`, so nobody can pose as a bot. `isBot(player)`,
  from `@irt/client` or `@irt/room`, tells them apart.
- **Behaviours** are declared by name in `bots` in `defineRoom`, and
  `room.bots.add(name, { name?, status?, data? })` adds a bot running
  one. `start` runs when the bot is added and again after each wake;
  `tick` runs every tick before the stepper, in the order the bots were
  added. Both must be synchronous.
- **Input.** With a stepper, `tick` sets `bot.input` and the stepper
  gets it under the bot's player ID, so a bot's car moves by the same
  `step` as a person's, and clients predict and interpolate it like any
  other player's. The room doesn't run `parseInput` on it, since it's
  your own code. Without a stepper, a behaviour changes entities itself.
- **`bot.data`** is the behaviour's own JSON, at most 4 KB
  (`MAX_BOT_DATA`), saved in room state.
- **Ownership and private state** work by player ID, as for people.
  `onWrite` doesn't run for a bot's entities: the room writes them
  directly.
- **`room.bots.remove(bot)`** ends the bot's presence and runs
  `onPlayerLeave` for it before returning, so code that cleans up after a
  player cleans up after bots too. Bots never cause `onJoin` or
  `onLeave`, which take a connection.
- **A behaviour that throws,** or returns a promise, has the error logged
  and its bot removed, and the room keeps running. So does a bot whose
  `data` stops being JSON or grows over 4 KB.
- **Limits.** A room holds at most 64 bots (`MAX_BOTS`). Bots count
  toward presence's 1,024 entries. The tick profile shows their `tick`s
  as `bots`.
- **No player data.** Bots have no player data, own no collection
  entries and submit no scores, since those outlast the room.
  `room.playerData` throws for a bot, and the data service answers a
  bot's ID with `E_INVALID`. Voice leaves bots out.

## Seats

`room.maxPlayers` is the room's seat limit: its `maxPlayers`, or its room
size's connection limit. People and bots together fill at most that
many, and `room.bots.add` throws when they already do.

A person can always take a bot's seat. When a person joins a room that
people and bots fill, the room removes the bot added last in the join
itself: `onPlayerLeave` runs for the bot, then `onJoin` for the person,
before the person's first state update. Give the bot's entities to the
person in `onJoin` if the game should carry on from where the bot was.

The router counts only people, so the room list and quick join see a
room with one person and three bots as having one player. Quick join
still prefers rooms with more people.

## Hibernation and wake

Bots are room state: their IDs, names, statuses, behaviours and `data`
are saved and come back after a wake or a room host crash. Before the
room hibernates, `onPlayerLeave` runs for every person in presence but
not for bots. On wake each bot is back in presence before `onWake`, and
its `start` runs after `onWake`.

Bots hold no connection, so a room with only bots in it hibernates 30
seconds after its last connection closes, like any room. A game that
should finish without people ends itself in `onLeave` or
`onPlayerLeave`.

## Simulating and testing

A room's bots are room code, so [`irt simulate`](/docs/guides/simulate)
and [`@irt/testing`](/docs/guides/testing) run them with nothing more to
set up. Their simulated bots are client connections, a different thing:
spawn them into a room whose bots fill it to test that people take their
seats. A [Node client](/docs/guides/node-client) can play a room as an
external bot, connecting like a person with its own token, for a game
whose logic lives only in its client.

---

# Presence

> Who's in the room, with a name and a small status per player, synced to every client with no kinds to declare and no join or leave code.

Every room has **presence**: an entry for each player in it, with a name
and a small status, synced to every client. The room runtime adds a
player when it connects and removes it when it leaves, so a player list,
"who's here" avatars, a lobby screen or a typing indicator need no kind
in your schema and no `onJoin` or `onLeave` code.

```ts
// src/room.ts
import { defineRoom } from "@irt/room";

export default defineRoom({});
```

```ts
// web/players.ts
import { connect } from "@irt/client";

const room = await connect({ router: "wss://eu.irt.io", project: "my-game", room: "main" });

for (const p of room.presence) console.log(p.player, p.name, p.status);
room.presence.onJoin((p) => console.log(`${p.name || p.player} joined`));
room.presence.onLeave((p) => console.log(`${p.name || p.player} left`));
room.presence.onChange((p, changed) => console.log(p.player, "changed", changed));

room.presence.setStatus({ typing: true });
```

## An entry

| Field | Type | Who sets it |
|---|---|---|
| `player` | `string` | The player ID, from the token's `sub` or a guest ID. |
| `name` | `string` | The room, with `room.presence.set`. It starts as the `name` string in the token's `meta`, if there is one of at most 64 characters, else `""`. |
| `status` | JSON | The player, with `setStatus`, or the room. At most 1 KB serialized; `null` until set. |
| `connected` | `boolean` | The runtime: `false` for 10 seconds after the player's last connection closes, then the entry leaves. |

One entry per player, however often it reconnects. A dropped connection
that reconnects within 10 seconds (`PRESENCE_GRACE`) keeps its entry and
its status: other clients see `connected` go `false` and back to `true`,
not a leave and a join. A player connecting again from a new tab, which
closes its old connection with 4012, doesn't change its entry at all.

## Status

The status is the player's own: a typing flag, "away", a ready check, an
emoji, which seat it's looking at. Set it from the client:

```ts
// web/status.ts
import type { RoomClient } from "@irt/client";

export function markReady(room: RoomClient, ready: boolean): void {
  room.presence.setStatus({ ready });
}
```

`setStatus` changes the local copy at once and sends it with the
client's other [owner writes](/docs/guides/ownership), at most once per
room tick. It throws a `RangeError` for a status over 1 KB as JSON. Like
any owner write, a status not yet sent when the connection drops is
lost, and the room has the last word: when it changes a player's status,
that player gets a correction and `onChange` runs for `status`.

A status is a claim from the player, so keep anything that decides the
game out of it. Your room's `onWrite` isn't called for status writes;
the room checks a status after the fact and replaces it with
`room.presence.set`:

```ts
// src/room-status.ts
import { defineRoom } from "@irt/room";

export default defineRoom({
  onJoin(room, connection) {
    const meta = connection.meta as { displayName?: string } | null;
    room.presence.set(connection.player, { name: meta?.displayName?.slice(0, 64) ?? "guest" });
  },
  onTick(room) {
    for (const p of room.presence) {
      if (typeof p.status !== "object" || p.status === null) continue;
      if ("ready" in p.status && typeof p.status.ready !== "boolean") room.presence.set(p.player, { status: null });
    }
  },
});
```

## In the room

```ts
interface Presence {
  get(player: string): PresenceEntry | undefined;
  readonly size: number;
  [Symbol.iterator](): IterableIterator<PresenceEntry>;
  set(player: string, values: { name?: string; status?: unknown }): void;
}
```

`room.presence` holds the same entries clients see. `set` throws for a
player with no entry, a name over 64 characters or a status over 1 KB.
A player's entry exists before `onJoin` runs and is still there, with
`connected` false from the next tick, when `onLeave` runs.

## What it costs, and what it isn't

- **Every connection sees every entry**, whatever your
  [interest](/docs/guides/state-sync#interest) says. A player list is
  useless with gaps, and a room has at most 1,024 connections, so the
  whole list is at most 1,024 small entries. An entry counts toward a
  connection's cap of 16,384 visible entities, and a resync sends the
  whole list. Rooms hold at most 1,024 entries (`MAX_PRESENCE`); when a
  room is full of them, the entry of the player gone longest makes room.
- **Unless the room hides entries.** Interest doesn't apply to
  presence, but `seesPresence(room, viewer, entry)` in `defineRoom` does:
  a viewer sees another player's entry only while it returns true, so a
  player who blocked someone stops seeing them in the list too. The
  client sees a hidden entry leave, and join again when it's shown. A
  player always sees its own entry. Players banned with `room.ban`, and
  connections the room kicks in `onJoin` before any `await`, never get
  an entry anyone sees.
- **It isn't room state.** Presence is who's connected now, so it isn't
  saved and doesn't survive hibernation: after a wake, the list fills
  again as players reconnect, with empty statuses. Keep per-player data
  that should last, such as settings or a seat, in
  [private state](/docs/reference/room-sdk#room) or an entity.
- **It isn't voice.** [Proximity voice](/docs/guides/proximity-voice)
  ignores presence, so seeing every entry doesn't make every player
  audible.
- **It isn't one of your entities.** `room.entities` doesn't hold
  presence, it doesn't change the IDs your entities get, and an entity
  you create with an explicit ID that a presence entry holds moves the
  entry, which clients don't notice. On the client, read presence through
  `room.presence`, not `room.entities`.

## Testing

Test clients have `client.presence` like any other:

```ts
// src/presence.test.ts
import { testRoom } from "@irt/testing";
import { expect, it } from "vitest";
import room from "./room-status.js";

it("shows who is ready", async () => {
  const r = testRoom(room);
  const alice = await r.connect({ player: "alice", meta: { displayName: "Alice" } });
  const bob = await r.connect({ player: "bob" });
  alice.client.presence.setStatus({ ready: true });
  await r.host.tick(2);
  expect(bob.client.presence.get("alice")).toMatchObject({ name: "Alice", status: { ready: true }, connected: true });
  expect(r.live.presence.size).toBe(2);
});
```

---

# Proximity voice

> Give rooms voice where each listener hears the closest speakers it can see.

Rooms can have voice chat in which each listener hears the speakers near
it. The room decides who hears whom; `@irt/client/voice` joins the voice
server and plays what the room allows.

## How it works

- Voice is audio only and runs on a voice server (LiveKit) in each
  region, outside your VMs. It runs no tenant code.
- A project turns voice on with its `voice` setting. Each connection then
  gets a voice token from the router after `welcome`, in a `voice`
  message (type 7) with the voice server's URL. The voice identity is the
  player ID, stable across reconnects.
- **Who hears whom comes from the room.** With `voice: {}` in
  `defineRoom`, a listener hears the players whose entities it can see
  under the room's [interest](/docs/guides/state-sync#interest), ranked by
  the interest limit's `priority`, capped at `maxSpeakers`.
  An entity belongs to the player in its `owner` string field, unless you
  pass `owner`. `audible(room, listener)` replaces the rule, for teams,
  radio channels or a whole room on one call.
- Each tick the room works out every connection's **speakers** (who it
  hears) and **listeners** (who hears it) and sends them, only when they
  change and at most 4 times a second, in a `peers` message (type 9).
- The client subscribes only to its speakers, and sets its own
  microphone track's permissions to its listeners, so a modified client
  can't overhear anyone and can only expose its own voice. A subscribe
  that arrives before a speaker's permission is retried when the
  permission comes.
- By default each speaker plays through its own `<audio>` element, with
  volume falling linearly to silence at `range`. `spatial: true` pans
  speakers in 3D with Web Audio, played through one `<audio>` element,
  because Chrome's echo cancellation ignores audio played straight from
  Web Audio.

## Room

```ts
// room.ts
import { defineRoom, defineSchema, entity, grid, type RoomEntity } from "@irt/room";

export const Avatar = entity("avatar", { owner: "string", x: "f32", y: "f32" });
export const schema = defineSchema({ entities: [Avatar] });

type A = RoomEntity<typeof Avatar>;

export default defineRoom({
  schema,
  interest: {
    ...grid({ cellSize: 16, radius: 1, dims: "xy", around: (_room, c) => c.data.avatar }),
    limit: {
      max: 64,
      priority: (_room, c, e) => -Math.hypot((e as A).x - (c.data.avatar as A).x, (e as A).y - (c.data.avatar as A).y),
    },
  },
  voice: { maxSpeakers: 6 },
  onJoin(room, conn) {
    conn.data.avatar = [...room.entities.all(Avatar)].find((e) => e.owner === conn.player) ?? room.entities.create(Avatar, { owner: conn.player, x: 0, y: 0 });
  },
  onPlayerLeave(room, player) {
    for (const e of room.entities.all(Avatar)) if (e.owner === player) room.entities.delete(e);
  },
});
```

`Voice` options on `defineRoom({ voice })`:

| Option | Default | Meaning |
|---|---|---|
| `maxSpeakers` | `8`, or `256` with `audible` | Speakers each listener hears, at most 256. The project's `voice.maxSpeakers` setting is a ceiling: a room gets the smaller of the two |
| `owner(entity)` | its `owner` string field | The player an entity speaks for |
| `audible(room, listener)` | speakers it can see | Player IDs the listener hears, replacing the default rule |

## Whole room on one call

Party games and calls want everyone to hear everyone, whatever they can
see. Return every connection's player from `audible`; the listener's own
ID is dropped for you:

```ts
// call-room.ts
import { defineRoom, defineSchema } from "@irt/room";

export const schema = defineSchema({});

export default defineRoom({
  schema,
  voice: { audible: (room) => [...room.connections.values()].map((c) => c.player) },
});
```

With `audible` the room's own cap defaults to 256, and the project's
`voice.maxSpeakers` setting, 64 by default, caps it, so a call of up to
65 players needs no setting. On the client, leave
out `position` so every speaker plays at full volume; see
[Client](#client).

## Muting a player

`room.muteVoice(player)` mutes a player in this room, for good or until
`{ expiresAt }` in wall-clock milliseconds; `room.unmuteVoice(player)`
lifts it, and `room.voiceMutes()` lists them. The room leaves a muted
player out of every listener's speakers, whatever `audible` or the
default rule says, so no client the room drives subscribes to it, and
its own client sees no listeners. Mutes are kept in room state, like
bans, so they last through hibernation and a room host restart.

```ts
calls: {
  mute: (room, conn, args: { player: string }) => {
    if (conn.player === room.creator) room.muteVoice(args.player);
  },
},
```

The voice server enforces a mute too: the player can't publish while
it lasts, and its voice tokens can't either, so neither a modified
client nor a reconnect gets around it. A player on the voice server is
muted at once, and one who joins it with a token from before the mute
is muted as it joins; should the voice server miss either, within a
minute. When the mute ends, `Voice` turns the player's microphone back
on if it was on, unless the player muted it with `setMuted`. The server
API's `voice/mute` is a one-off mute of the player's tracks, which its
own client can undo.

## Client

```ts
// client.ts
import { connect } from "@irt/client";
import { joinVoice } from "@irt/client/voice";
import { Avatar, schema } from "./room.js";

const room = await connect({ router: "wss://eu.irt.io", project: "my-game", room: "plaza", schema });

const voice = joinVoice(room, {
  position(player) {
    const a = [...room.entities.all(Avatar)].find((e) => e.owner === player);
    return a && { x: a.x, y: a.y };
  },
  range: 24,
});

document.querySelector("#talk")!.addEventListener("click", () => void voice.enableMic());
document.querySelector("#mute")!.addEventListener("click", () => void voice.setMuted(!voice.muted));
```

```ts
function joinVoice(room: RoomClient, opts?: VoiceOptions): Voice;

interface VoiceOptions {
  position?(player: string): { x: number; y: number; z?: number } | undefined;
  spatial?: boolean; // default false
  range?: number; // default 20
}

class Voice {
  readonly project: string;                      // the room connection's project
  readonly muted: boolean;                       // this player's mute, from setMuted
  readonly micOn: boolean;                       // enableMic called and not muted
  readonly participants: ReadonlySet<string>;    // other players on the voice server
  readonly speaking: ReadonlySet<string>;        // players speaking now, this one included
  readonly mutedPlayers: ReadonlySet<string>;    // other players on voice sending no audio
  on(event: "participants" | "speaking" | "mutedPlayers", fn: (players: ReadonlySet<string>) => void): () => void;
  on(event: "micError", fn: (error: Error) => void): () => void;
  enableMic(): Promise<void>;
  setMuted(muted: boolean): Promise<void>;
  disconnect(): Promise<void>;

  // Player controls; see below
  volume(player: string): number;                // 0 to 1, default 1
  setVolume(player: string, volume: number, keep?: boolean): void;
  readonly blocked: ReadonlySet<string>;
  setBlocked(player: string, blocked: boolean): void;
  devices(): Promise<{ inputs: VoiceDevice[]; outputs: VoiceDevice[] }>;  // VoiceDevice: { id, label }
  readonly input: string | undefined;            // chosen microphone; undefined for the default
  readonly output: string | undefined;           // chosen speaker; undefined for the default
  readonly canSetOutput: boolean;                // the browser has setSinkId
  setInput(deviceId: string): Promise<void>;
  setOutput(deviceId: string): Promise<void>;
  readonly level: number;                        // microphone input level, 0 to 1
  readonly pushToTalk: boolean;
  setPushToTalk(on: boolean): Promise<void>;
  talk(down: boolean): Promise<void>;
}
```

- **`position`** places players for volume and panning, and a speaker
  it returns undefined for is silent. Leave it out and every speaker
  plays at full volume, unpanned, as on a call; `spatial` and `range`
  then do nothing.
- **`participants`** is the set of other players' IDs on the voice
  server, whether or not the room has this player hear them: everyone
  a voice chat list should show. A player in the room who hasn't joined
  voice, or whose voice dropped, isn't in it. The `participants` event
  fires with the new set each time a player joins or leaves voice.
- **`speaking`** is the set of player IDs the voice server hears talking
  now, this player's included, so it covers speakers this client doesn't
  hear too. The `speaking` event fires with the new set each time it
  changes.
- **`enableMic`** while the room mutes this player publishes nothing
  until the mute ends, then turns the microphone on. Called before voice
  has joined, it turns the microphone on when it does.
- **`micError`** fires when the microphone fails to start, as when the
  player refuses permission, whether from `enableMic` or on joining.
  The microphone is then off again, so `micOn` is false and the next
  `enableMic` asks again; `enableMic` also rejects with the error. An
  error named `NotAllowedError` is a refusal.
- **`mutedPlayers`** is the other players on the voice server sending no
  audio: muted with `setMuted`, or not yet past `enableMic`. The
  `mutedPlayers` event fires with the new set; `voice.muted` stays this
  player's own mute. A player who isn't on the voice server
  is in neither set.
- The three sets empty when voice drops and fill again after it rejoins, so
  keep the same listeners across reconnects; there's nothing to rebind.
  `voice.livekit` is replaced on each reconnect, so listeners on it
  would need binding again.

### Player controls

These are the player's own settings, which the project shows in its UI;
the [UI kit](/docs/ui-kit)'s `<irt-voice-settings>` and
`<irt-voice-chat>` are built on them.

- **`setVolume(player, volume)`** sets how loud this player hears
  another, from 0 to 1, multiplied into the distance attenuation on both
  the `<audio>` and the `spatial` path. It can't go above 1: an
  `<audio>` element's volume is capped there, and gain past it would
  need Web Audio, which Chrome's echo cancellation ignores. With `keep`
  false it isn't saved, for a slider being dragged; save the value it
  stops at.
- **`setBlocked(player, true)`** is a local mute: the client never
  subscribes to a blocked player, whatever the room picks, so a blocked
  player costs no bandwidth. Other players still hear them. To silence
  a player for everyone, the room calls `muteVoice`.
- Volumes and blocks are kept in localStorage per project by player
  ID, so a player blocked in one room stays blocked in the next. Where
  the browser blocks storage they last for the page.
- **`devices()`** lists microphones and speakers. Labels are empty until
  the page has microphone permission, so list them again after
  `enableMic`. `setInput` and `setOutput` switch devices, and a device
  chosen before voice joins is used when it does. Speakers can only be
  chosen where the browser has `setSinkId`, which `canSetOutput`
  reports; elsewhere `devices()` lists none and `setOutput` throws.
- **`level`** is the microphone's input level from 0 to 1, 0 while it
  isn't sending. Read it on animation frames for a meter.
- **`setPushToTalk(true)`** keeps the microphone muted except between
  `talk(true)` and `talk(false)`. `Voice` doesn't bind keys; the page
  does, and should ignore key presses in text fields:

```ts
// push-to-talk.ts
import { connect } from "@irt/client";
import { joinVoice } from "@irt/client/voice";

const room = await connect({ router: "wss://eu.irt.io", project: "my-party", room: "lobby" });
const voice = joinVoice(room);
await voice.setPushToTalk(true);

const typing = (e: KeyboardEvent) => e.target instanceof HTMLInputElement || e.target instanceof HTMLTextAreaElement;
addEventListener("keydown", (e) => {
  if (e.code === "KeyV" && !e.repeat && !typing(e)) void voice.talk(true);
});
addEventListener("keyup", (e) => {
  if (e.code === "KeyV") void voice.talk(false);
});
document.querySelector("#mic")!.addEventListener("click", () => void voice.enableMic());
```

### Indicators

```ts
// indicators.ts
import { connect } from "@irt/client";
import { joinVoice } from "@irt/client/voice";

const room = await connect({ router: "wss://eu.irt.io", project: "my-party", room: "lobby" });
const voice = joinVoice(room);

function badge(player: string): string {
  if (voice.mutedPlayers.has(player)) return "muted";
  return voice.speaking.has(player) ? "speaking" : "";
}

function show(): void {
  const onVoice = [...room.presence].filter((p) => voice.participants.has(p.player));
  console.log(onVoice.map((p) => `${p.player} ${badge(p.player)}`));
}

for (const event of ["participants", "speaking", "mutedPlayers"] as const) voice.on(event, show);
```

The voice follows the room connection: it leaves the voice server when
the connection drops, joins again with the new token after the
reconnect, and ends when the connection closes for good. Without the
project's `voice` setting the router sends no token, and `joinVoice`
does nothing. `room.peers` (`{ speakers, listeners }`) and the `peers`
event are on every `RoomClient`, so a project can show who's talking
without `@irt/client/voice`, which is a separate entry so projects without
voice don't load `livekit-client`.

`livekit-client` is most of a voice game's bundle, about 570 KB
minified. Import `@irt/client/voice` dynamically, once the game has
connected or when the player opts in, and the scaffold's `build-web.mjs`, which bundles with esbuild's
`splitting`, puts it in a chunk of its own that loads only then:

```ts
// lazy-voice.ts
import { connect } from "@irt/client";

const room = await connect({ router: "wss://eu.irt.io", project: "my-party", room: "lobby" });

const { joinVoice } = await import("@irt/client/voice");
const voice = joinVoice(room);
document.querySelector("#talk")!.addEventListener("click", () => void voice.enableMic());
```

A build script of your own needs `splitting: true`, `format: "esm"` and
`outdir` rather than `outfile` for this; without `splitting`, esbuild
inlines the dynamic import into the main bundle. Keep `enableMic` in a
click handler of its own, after the import has resolved, since browsers
grant the microphone only from a user gesture.

## Testing

Test clients expose the room's decision, so proximity voice is testable
without a voice server:

```ts
// voice.test.ts
import { testRoom } from "@irt/testing";
import { expect, it } from "vitest";
import room, { Avatar } from "./room.js";

it("hears nearby players", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  const bob = await t.connect({ player: "bob" });
  await t.host.tick();
  expect(alice.speakers).toEqual(["bob"]);
  expect(bob.listeners).toEqual(["alice"]);
  const far = [...t.live.entities.all(Avatar)].find((a) => a.owner === "bob")!;
  far.x = 500;
  await t.host.tick(10);
  expect(alice.speakers).toEqual([]);
});
```

## Turning it on

Voice is a project setting:

| Setting | Default | Meaning |
|---|---|---|
| `voice.enabled` | `false` | Connections get a voice token |
| `voice.maxSpeakers` | `64` | 1 to 64. A ceiling on every room's speakers per listener: a room gets the smaller of this and its own `maxSpeakers`, whose default of 8 is unchanged for proximity voice. A change applies to each room from its next wake |

Declare them in [`irt.config.ts`](/docs/cli#irtconfigts):

```ts
settings: { voice: { enabled: true } },
```

Locally, voice is off unless you run a LiveKit server and point `irt dev`
at it; `peers` messages arrive either way, so the room's rule can be
checked without one:

```sh
docker run -d --rm --network host livekit/livekit-server:v1.9.1 --dev --bind 127.0.0.1
IRT_LIVEKIT_URL=ws://127.0.0.1:7880 npx @irt/cli dev
```

`IRT_LIVEKIT_KEY` and `IRT_LIVEKIT_SECRET` default to LiveKit's dev
mode `devkey` and `secret`. The token `irt dev` mints has the grants the
router's does: identity the player ID, LiveKit room `{project}/{room}`,
publishing only the microphone, and subscribing.

## Common mistakes

- **Leaving out `voice` in `defineRoom`.** Without it the room sends no
  `peers`, and every client hears no one.
- **An interest that shows everyone everything.** With no interest, every
  connection sees every entity, so a listener hears the first
  `maxSpeakers` players rather than the nearest.
- **A `priority` that ranks far entities higher.** Priority is "higher is
  more important"; use the negative of the distance.
- **Entities without an owner.** The default rule only counts entities
  with an `owner` string field naming a player; pass `owner` otherwise.
- **Calling `enableMic` outside a click.** Browsers only grant the
  microphone from a user gesture.
- **Expecting voice to keep a room awake.** Rooms hibernate 30 seconds
  after their last connection closes, whatever voice is doing.

---

# Simulating players

> Run the room locally with dozens of scripted players, check invariants such as visibility leaks and lost writes every tick, and read the trace.

`irt simulate` runs the project's room on your machine with simulated
players, checks invariants after every tick, prints a summary and writes
a trace. Each player is a bot with a real `@irt/client` connection, so
state updates, owner writes, inputs and calls go through the same
protocol as in a browser. It runs against local rooms only, never a
deployed project.

```
$ npx irt simulate --players 20
20 players, 600 ticks (30.0 s at 20 Hz), seed 1, in 2.1 s
  pass  visibility    11980 client views checked against the room's interest
  pass  prediction    0 mispredictions, at most 0 for one bot (allowed 10)
  skip  owned-writes  no bot wrote an owned entity with bot.write
  pass  room-errors   0 errors logged by the room
  pass  limits        room state peaked at 1840 bytes (allowed 33554432), 20 entities
  skip  reconnects    no bot reconnected; set drops or call bot.drop()
  pass  script        0 errors thrown by the script and behaviours
  traffic per player: 1.42 KB/s down, 0.31 KB/s up
  wall time per tick: p50 0.41 ms, p95 0.9 ms, max 3.2 ms
trace: .irt/simulate/trace.jsonl
```

It exits with 1 when an invariant fails, so it can run in CI beside
`irt test`.

## How it runs

The room runs in process on the same test host as
[`@irt/testing`](/docs/guides/testing): a controlled clock, the local
router and in-memory room state, with no network. Time moves one tick at
a time, so a run takes far less wall time than room time. Bots join one
after another before the first tick, then the room runs `--ticks` ticks,
then a second or so more with the bots' behaviours stopped, so the last
writes and reconnects settle.

A run is deterministic for a seed: the bots' choices, the simulated
network and `Math.random` in room code all come from it, and `Date.now`
follows the test clock. Running twice with one seed writes the same
trace, apart from wall times.

Without a script, every bot runs the built-in behaviours (`walk` by
default). With an `irt.sim.ts` in the project, or `--script <file>`,
the script decides.

## Invariants

| Name | Fails when |
|---|---|
| `visibility` | A client holds an entity its interest excludes. Each tick, the simulation calls the room's `keysOf`, `subscriptionsOf` and `sees` afresh for every connection and entity, and compares with what each client holds at the tick it last applied. Skipped for rooms without interest. |
| `prediction` | A bot's predictions are corrected by the room more than `maxCorrections` times (default 10). |
| `owned-writes` | A write made with `bot.write` was neither applied by the room nor corrected: the room never held the value and sent no correction. Corrections are expected; silent losses aren't. |
| `room-errors` | The room logs an error, such as a throw in `onMessage`, a call or `onWrite`, or stops. |
| `limits` | Room state grows past `maxRoomState` (default the 32 MB a room stops at), or a connection goes over a state sync cap: interest keys, visible entities or presence. |
| `reconnects` | After a bot reconnects, its shared state, private state or entities differ from what the room held at that tick, or it's missing entities it should see. |
| `script` | The script or a behaviour throws. |

Each one passes, fails or is skipped when nothing exercised it; the
skip line says what would. A script adds its own invariants by name.

The visibility check finds rooms whose interest functions read something
other than the entity and connection they're given. Here `keysOf` reads a
team table that `onTick` changes, but the room recomputes an entity's
keys only when the entity changes, so a player who switches teams stays
visible to the old team:

```ts
const teams = new Map<string, string>();
const interest = {
  keysOf: (e) => [teams.get(e.owner)],         // reads outside the entity
  subscriptionsOf: (conn) => [teams.get(conn.player)],
};
```

`irt simulate` reports it as a visibility failure naming the player who
still sees the entity, the tick, and the entity's values on both sides.
Store the team on the entity instead, so changing it changes the keys.

## A script

A script is a module whose default export is `defineSimulation(room,
{...})` from `@irt/simulate`. The CLI bundles it with the room, and
resolves `@irt/simulate` to its own copy, so it needs nothing installed;
add `@irt/simulate` as a devDependency for your editor's types.

```ts
// schema.ts
import { defineCalls, defineSchema, defineStepper, entity } from "@irt/room";

export const Runner = entity("runner", { owner: "string", x: "f32", y: "f32" });
export const Score = entity("score", { laps: "u32" });

export const schema = defineSchema({
  state: Score,
  entities: [Runner],
  calls: defineCalls<{ boost(args: { power: number }): { ok: boolean } }>(),
});

export const stepper = defineStepper<{ dx: number; dy: number }>({
  step(world, inputs, dt) {
    for (const r of world.all(Runner)) {
      const i = inputs.get(r.owner);
      if (i) r.x += i.dx * 10 * dt;
    }
  },
});
```

```ts
// room.ts
import { defineRoom } from "@irt/room";
import { Runner, schema, stepper } from "./schema.js";

export default defineRoom({
  schema,
  stepper,
  onJoin(room, conn) {
    if (![...room.entities.all(Runner)].some((r) => r.owner === conn.player)) room.entities.create(Runner, { owner: conn.player });
  },
  calls: {
    boost: (_room, _conn, { power }) => ({ ok: power <= 3 }),
  },
});
```

```ts
// irt.sim.ts
import { type Behaviour, chat, defineSimulation, walk } from "@irt/simulate";
import room from "./room.js";
import { Runner } from "./schema.js";

const booster: Behaviour<any, any, any> = {
  name: "booster",
  async start(bot) {
    await bot.wait(20 + Math.floor(bot.random() * 40));
    await bot.call("boost", { power: 2 });
  },
};

export default defineSimulation(room, {
  players: 16,
  ticks: 1200,
  seed: 42,
  network: { rttMs: 120, jitterMs: 20, loss: 0.02 },
  drops: 4,
  behaviour: [walk(), chat({ every: 10 }), booster],
  async run(sim) {
    await sim.wait(200);
    const late = await sim.spawn({ player: "late", network: { rttMs: 300 } });
    sim.log("late joined", { tick: sim.tick });
    await sim.crash();
    await late.until(() => late.client.status === "open");
  },
  invariants: {
    "one runner per player": ({ room }) => {
      const owners = [...room.entities.all(Runner)].map((r) => r.owner);
      return new Set(owners).size === owners.length || `runners: ${owners.join(", ")}`;
    },
  },
});
```

`defineSimulation(room, spec)` takes:

| Field | Default | Meaning |
|---|---|---|
| `players` | 8 | Bots that join before the first tick |
| `ticks` | 30 s of ticks | Ticks to run after they've joined |
| `seed` | 1 | Seeds every random choice in the run |
| `network` | none | `{ rttMs, jitterMs?, loss? }` for every bot, as [`simulateNetwork`](/docs/dev-tools) takes |
| `behaviour` | `walk()` | One behaviour or a list, for every bot |
| `drops` | 0 | Connections dropped at seeded random ticks, to exercise reconnects |
| `maxMispredictions` | 10 | Mispredictions each bot's predictions may have |
| `maxRoomState` | 32 MB | Room state bytes the `limits` invariant allows |
| `run(sim)` | none | The scenario, run beside the behaviours |
| `invariants` | none | Functions of `{ tick, room, bots }` run after every tick: return `false` or a message to fail |

Flags given to `irt simulate` override the script's fields.

### Behaviours

A behaviour is `{ name, start?(bot), tick?(bot) }`: `start` runs once
when the bot has joined and may await, and `tick` runs each tick while
it's connected. The built-ins:

- `walk({ turnEvery? })` moves in a random direction `{ dx, dy }`, each
  -1, 0 or 1, turning about every second. With a stepper, it's the input
  the bot predicts with; on an owned entity with writable `x` and `y`,
  the bot writes them; otherwise it sends `{ dx, dy }` as a message, as
  the `irt init` room takes. A stepper whose input has another shape needs
  its own behaviour that calls `bot.predict`.
- `chat({ every?, message? })` sends `{ type: "chat", text }` about every
  5 seconds.
- `idle()` does nothing.

### Bots

| Member | Meaning |
|---|---|
| `player`, `index` | The player ID (`bot-1`, ... unless `spawn` names one) and join order |
| `client` | The bot's `RoomClient`: `state`, `private`, `entities`, `tick`, `status` |
| `random()` | The bot's own seeded stream |
| `send(message)`, `call(name, args)` | As on `RoomClient`; `call` is typed by the schema's calls |
| `write(entity, values)` | Sets writable fields of an owned entity and checks they aren't lost |
| `predict(stepper, { sample, find? })` | Predicts with the stepper; `find` defaults to `own()` |
| `own()` | The first entity the bot owns, or else the first whose `owner` field is its player ID |
| `view(kind)`, `messages`, `data` | What it sees, what it received, and room for a behaviour's state |
| `wait(ticks)`, `until(test, maxTicks?)` | Wait on the room's ticks |
| `drop()`, `leave()` | Drop the connection, which reconnects, or leave for good |

The scenario's `sim` has `room` (the running room, as room code sees
it), `bots`, `tick`, `random()`, `spawn(opts?)`, `wait`, `until`,
`crash()` and `log(message, data?)`.

## The trace

The trace is JSON lines, one event each, written to
`.irt/simulate/trace.jsonl` or `--trace <file>`. A coding agent can read
the last line for the verdict and the first failure, then the lines
around that tick.

| `type` | Fields |
|---|---|
| `start` | `seed`, `tickRate`, `ticks`, `players`, `behaviours`, `network`, `interest`, `stepper`, `invariants` |
| `join`, `leave`, `drop`, `restored` | `tick`, `player` |
| `crash`, `stopped`, `note` | `tick`, and the reason or note |
| `second` | Once a second of room time: `tick`, `players`, `entities`, `bytesDown`, `bytesUp` |
| `error` | `tick` and the room's log line |
| `failure` | `invariant`, `tick`, `players`, `message`, and `entities`: each with `id`, `kind`, `owner`, and its values in the `room` and on the `client` |
| `end` | `passed`, every invariant's `status`, `checks`, `failures`, `detail` and `first` failure, `firstFailure`, `traffic` and `wall` |

At most 20 `failure` lines are written per invariant; the `end` line
counts them all.

```json
{"type":"failure","invariant":"visibility","tick":81,"players":["bot-1"],"message":"bot-1 sees runner 3, which its interest excludes at tick 81","entities":[{"id":3,"kind":"runner","owner":"bot-2","room":{"owner":"bot-2","x":0,"y":0},"client":{"owner":"bot-2","x":0,"y":0}}]}
```

From code, `simulate(sim, { trace })` from `@irt/simulate` runs the same
simulation and resolves to the result the summary is printed from.

---

# Testing rooms

> Patterns for testing rooms with @irt/testing, from ticks and clocks to hibernation, crashes, reconnects, ownership, calls and migrations, and running them in CI.

`@irt/testing` runs a room in process, with the real `@irt/client` as
its clients and a clock that moves only when the test moves it. Tests
need no network, no `irt dev` and no account, so they run the same on a
laptop and in CI. This guide shows how to test what rooms usually get
wrong; every call is in the [@irt/testing reference](/docs/reference/testing).

```sh
npx irt test            # vitest run, in the directory of irt.config.ts
npx irt test src/room   # arguments go to vitest
```

## The shape of a test

```ts
// counter.ts
import { defineRoom, defineSchema, entity } from "@irt/room";

export const Count = entity("count", { n: "u32" });
export const Mine = entity("mine", { clicks: "u32" });

export default defineRoom({
  schema: defineSchema({ state: Count, private: Mine }),
  tickRate: 20,
  onMessage(room, conn, message) {
    if (message !== "click") return;
    room.state.n += 1;
    room.private(conn).clicks += 1;
  },
});
```

```ts
// counter.test.ts
import { testRoom } from "@irt/testing";
import { expect, test } from "vitest";
import room from "./counter.js";

test("every player sees the total and only their own clicks", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  const bob = await t.connect({ player: "bob" });

  alice.send("click");
  alice.send("click");
  bob.send("click");
  await t.host.tick();

  expect(bob.client.state.n).toBe(3);
  expect(alice.private.clicks).toBe(2);
  expect(bob.private.clicks).toBe(1);
  expect(t.live.state.n).toBe(3);
});
```

- `testRoom(def)` is one room, `"room"`, in project `"test"`.
  `createTestHost(def)` holds several rooms of one build in one room host.
- `connect({ player })` signs a token for that player ID; without
  `player` the client is a guest. `meta` sets the token's `meta` claim.
- Changes reach clients at the end of a tick, so `await t.host.tick()`
  before asserting on what a client sees.
- `t.live` is the running room: read it, or write its entities to set up a
  case, from the test.

## Time

| Call | Moves the clock | Use it to |
|---|---|---|
| `t.host.tick(n)` | `n / tickRate` seconds; every running room runs exactly `n` ticks | Step the simulation |
| `t.host.advance(ms)` | `ms`, running every timer that falls due | Cross timeouts: idle hibernation after 30 s, call timeouts, reconnect backoff |
| `t.host.clock.jump(ms)` | `ms`, running nothing until the next `tick` or `advance` | Simulate a blocked event loop |

Room code's own `setTimeout` and `Date.now()` use real time, which the
test doesn't move. Time things in ticks instead: store
`endsAt = room.tick + seconds * tickRate` in room state and compare in
`onTick`. For wall-clock time, use `room.now()`, which reads the test
clock: each host's clock starts at the real time when it's created, or
at `createTestHost(room, { startAt })` / `testRoom(room, { startAt })`,
milliseconds since the epoch, for a test that needs a known date. Two
hosts made a while apart have clocks that far apart, so room state moved
from one to the other wakes with that `elapsed`; give the second a
`startAt` past the first's `clock.wall()` to set the gap.

```ts
// catch-up.test.ts
import { defineRoom } from "@irt/room";
import { testRoom } from "@irt/testing";
import { expect, test } from "vitest";

test("a room that stalls runs at most 4 ticks to catch up", async () => {
  const t = testRoom(defineRoom({ tickRate: 20 }));
  await t.wake();
  const before = t.live.tick;
  t.host.clock.jump(1000);
  await t.host.advance(0);
  expect(t.live.tick - before).toBe(4);
});
```

## Hibernation and crashes

The three ways a room loses its process behave differently, and a room
should be tested through each:

| Call | Runs `onLeave` | Clients | Room starts again with |
|---|---|---|---|
| `t.hibernate()` | yes, for every connection | closed with 4011; they don't reconnect | `onWake`, when the next client connects or on `t.wake()` |
| `t.host.crash()` | no | reconnect by themselves | `onWake`, then `onJoin` for each client that reconnects |
| `client.drop()` | yes, for that connection | that client reconnects with backoff | nothing; the room keeps running |

```ts
// avatars.ts
import { defineRoom, defineSchema, entity } from "@irt/room";

export const Avatar = entity("avatar", { owner: "string", x: "f32" });
export const Wins = entity("wins", { wins: "u16" });

export default defineRoom({
  schema: defineSchema({ private: Wins, entities: [Avatar] }),
  onJoin(room, conn) {
    const existing = [...room.entities.all(Avatar)].find((a) => a.owner === conn.player);
    conn.data.avatar = existing ?? room.entities.create(Avatar, { owner: conn.player });
  },
  onMessage(room, conn, message) {
    if (message === "win") room.private(conn).wins += 1;
  },
  onPlayerLeave(room, player) {
    for (const e of room.entities.all(Avatar)) if (e.owner === player) room.entities.delete(e);
  },
});
```

```ts
// avatars.test.ts
import { testRoom } from "@irt/testing";
import { expect, test } from "vitest";
import room, { Avatar } from "./avatars.js";

test("a crash keeps one avatar per player", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  await t.host.crash();
  await alice.reconnected();
  expect(alice.view(Avatar)).toHaveLength(1);
  expect(alice.events).toContain("restored");
});

test("wins outlast hibernation and the avatar doesn't", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  alice.send("win");
  await t.host.tick();
  await t.hibernate();
  expect(alice.closedWith).toBe(4011);
  expect(t.stored().entities).toEqual([]);

  const back = await t.connect({ player: "alice" });
  expect(back.private.wins).toBe(1);
  expect(back.view(Avatar)).toHaveLength(1);
});

test("a dropped connection keeps the avatar, and leaving for good removes it", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  const bob = await t.connect({ player: "bob" });
  alice.drop();
  await alice.reconnected();
  await t.host.tick();
  expect(bob.view(Avatar).map((a) => a.owner).sort()).toEqual(["alice", "bob"]);
  await alice.leave();
  // onPlayerLeave runs once the presence grace, 10 seconds, has passed.
  await t.host.advance(10_000);
  await t.host.tick();
  expect(bob.view(Avatar).map((a) => a.owner)).toEqual(["bob"]);
});
```

- `t.stored()` is the room state a wake would start from, as `RoomData`.
  Assert on it to check what's saved without waking the room.
- `client.events` records `"waking"`, `"disconnected 1006"`, `"restored"`
  and `"closed 4011"` in order; `closedWith` is the final close code.
- `reconnected()` waits for the reconnect after the client's last drop or
  crash, and resolves at once if it already happened. After a crash every
  client reconnects while the clock moves for the first, so await each in
  turn: `await bob.reconnected(); await alice.reconnected();`.
- `t.host.advance(31_000)` after the last client leaves hibernates the
  room by its idle timeout, as in production.

## Calls

`client.call` is the real client's. The room runs a call's handler as
it arrives, between ticks. A call that changed room state replies only
after the next tick has saved the change, so start it, tick, then await
it; awaited before a tick, it never resolves, since the test clock
doesn't move by itself. A call that changed nothing, or that failed,
answers at once:

```ts
// shop.test.ts
import { defineCalls, defineRoom, defineSchema, entity } from "@irt/room";
import { testRoom } from "@irt/testing";
import { expect, test } from "vitest";

const Purse = entity("purse", { coins: "u32" });
const room = defineRoom({
  schema: defineSchema({ private: Purse, calls: defineCalls<{ buy(args: { price: number }): { left: number } }>() }),
  onJoin(room, conn) {
    room.private(conn).coins = 10;
  },
  calls: {
    buy(room, conn, { price }) {
      const purse = room.private(conn);
      if (!Number.isInteger(price) || price < 0) throw new Error("price must be a whole number");
      if (purse.coins < price) throw new Error("not enough coins");
      purse.coins -= price;
      return { left: purse.coins };
    },
  },
});

test("a call resolves to the reply or rejects with the handler's error", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  const bought = alice.client.call("buy", { price: 4 });
  await expect(alice.client.call("buy", { price: 40 })).rejects.toThrow("call buy failed in the room: not enough coins");
  await t.host.tick();
  await expect(bought).resolves.toEqual({ left: 6 });
  expect(alice.private.coins).toBe(6);
});

test("a call in flight fails when the connection drops", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  const pending = alice.client.call("buy", { price: 1 });
  alice.drop();
  await expect(pending).rejects.toThrow(/it may or may not have run/);
});
```

## Ownership and corrections

`client.mine(kind)` gives the entities a test client's player owns, with
writable fields to set. `expectCorrected` asserts the room overrode a
write:

```ts
// cursor.test.ts
import { defineRoom, defineSchema, entity } from "@irt/room";
import { testRoom } from "@irt/testing";
import { expect, test } from "vitest";

const Cursor = entity("cursor", { x: "f32" }, { writable: ["x"] });
const room = defineRoom({
  schema: defineSchema({ entities: [Cursor] }),
  onJoin(room, conn) {
    if ([...room.entities.ownedBy(conn.player, Cursor)].length === 0) room.entities.create(Cursor, {}, { owner: conn.player });
  },
  onWrite(_room, _conn, _entity, next) {
    return { ...next, x: Math.min(Math.max(next.x as number, 0), 100) };
  },
});

test("writes in bounds reach others, and the room clamps the rest", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  const bob = await t.connect({ player: "bob" });
  const [cursor] = alice.mine(Cursor);

  cursor!.x = 40;
  await t.host.tick(2);
  expect(bob.view(Cursor).find((c) => c.id === cursor!.id)).toMatchObject({ x: 40 });

  cursor!.x = 500;
  await t.host.tick(2);
  alice.expectCorrected(cursor!.id, "x");
  expect(cursor!.x).toBe(100);
});
```

## Several rooms

```ts
// isolation.test.ts
import { defineRoom, defineSchema, entity } from "@irt/room";
import { createTestHost, RoomStoppedError } from "@irt/testing";
import { expect, test } from "vitest";

const Score = entity("score", { n: "u32" });
const room = defineRoom({
  schema: defineSchema({ state: Score }),
  onMessage(room, _conn, message) {
    if (message === "boom") room.state.n = 999;
  },
  onTick(room) {
    if (room.state.n === 999) throw new Error("boom");
  },
});

test("a room that throws stops alone", async () => {
  const host = createTestHost(room);
  const a = await host.room("a").connect({ player: "alice" });
  const b = await host.room("b").connect({ player: "bob" });
  a.send("boom");
  await expect(host.tick()).rejects.toThrow(RoomStoppedError);
  expect(a.closedWith).toBe(4007);
  await host.tick();
  expect(b.client.status).toBe("open");
});
```

`tick` and `advance` throw `RoomStoppedError` when a room stopped, with
its tick and the stack. A test that doesn't expect it fails there, which
is usually what you want.

## Migrations

Test a migration by making room state with the old build and waking it
with the new one. Both hosts' storage is the same in-memory format, so
copy it across:

```ts
// migration.test.ts
import { defineRoom, defineSchema, entity } from "@irt/room";
import { testRoom } from "@irt/testing";
import { expect, test } from "vitest";

const PlayerV1 = entity("player", { owner: "string", hp: "u8" });
const v1 = defineRoom({
  schema: defineSchema({ entities: [PlayerV1] }),
  onCreate(room) {
    room.entities.create(PlayerV1, { owner: "alice", hp: 7 });
  },
});

const PlayerV2 = entity("player", { owner: "string", health: "u16" });
const v2 = defineRoom({
  schema: defineSchema({ entities: [PlayerV2] }),
  version: 2,
  migrations: {
    2: (data) => ({
      ...data,
      entities: data.entities.map((e) => (e.kind === "player" ? { ...e, values: { owner: e.values.owner, health: e.values.hp } } : e)),
    }),
  },
});

test("version 2 wakes rooms saved by version 1", async () => {
  const before = testRoom(v1);
  await before.wake();
  await before.hibernate();
  const { base, log } = before.host.storage.load("test", "room");

  const after = testRoom(v2);
  after.host.storage.writeBase("test", "room", base);
  for (const batch of log) after.host.storage.append("test", "room", batch);
  await after.wake();
  expect([...after.live.entities.all(PlayerV2)].map((p) => p.health)).toEqual([7]);
  expect(after.stored().version).toBe(2);
});

test("without the migration the room stops and says why", async () => {
  const before = testRoom(v1);
  await before.wake();
  await before.hibernate();
  const after = testRoom({ ...v2, migrations: {} });
  after.host.storage.writeBase("test", "room", before.host.storage.load("test", "room").base);
  await expect(after.wake()).rejects.toThrow(/no migration to version 2/);
});
```

Keep a saved copy of real room state from each released version in the
repository, as a file written from `storage.load(...).base`, and wake it
with the current build in a test, so a migration is tested against what
rooms really hold.

## Prediction and interest

- Prediction: `client.predict(stepper, { find, sample })` samples once per
  room tick as the test moves the clock. Assert on `settled`, not on
  `pending`; see [Testing it](/docs/guides/prediction#testing-it).
- Interest: `expectSees(id)` and `expectNotSees(id)` fail with what the
  client sees instead; see the [reference](/docs/reference/testing#testclient).
- Wire size: `client.lastUpdate` has the last state update's parts and
  bytes, to keep a game's bandwidth in check.

## Without a backend

The host has `createRoom`, `joinByCode` and `listPublic`, with the
project's settings applied; pass settings with
`testRoom(def, { settings })`. See
[Games without a backend](/docs/no-backend#testing).

## In CI

Tests need Node 24 or later and nothing else:

```yaml
# .github/workflows/test.yml
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npm ci
      - run: npx irt test
```

`irt test` exits non-zero when a test fails. To deploy from CI after the
tests pass, see [Deploying from CI](/docs/builds#deploying-from-ci).

## Common mistakes

- **Asserting before a tick.** State updates go out at the end of a tick.
- **Starting a call that fails and awaiting it later.** The rejection
  arrives as soon as the room answers, and Vitest reports it as
  unhandled if nothing awaits it yet. Await calls where you make them.
- **Using `setTimeout` to wait.** Test time moves only with `tick` and
  `advance`; real waiting changes nothing.
- **Testing only the happy path.** Crash, drop and hibernate each run
  different hooks. A room that passes one can fail another.
- **Reconnecting a client after `hibernate()`.** It's closed with 4011
  and doesn't come back; connect a new one.
- **Sharing a host between tests.** Make one per test, so a stopped room
  or leftover client can't leak into the next.

---

# Node clients and bots

> Run @irt/client from Node scripts, bots and load tests, with the schema the room uses.

`@irt/client` runs in Node 24 or later as well as in browsers, so a
script can play a room: an external bot, a smoke test against `irt dev`
or a deployed project, or a load test. To fill a seat with a bot the
room drives itself, with no connection, see [Bots](/docs/guides/bots). Node has no
WebTransport, so the client connects over WebSocket; everything else
works as in a browser. On an older Node, which may lack a global
`WebSocket`, `connect` rejects with an `IrtError` naming the Node version
it needs and the one it found.

## Running TypeScript with the room's schema

A script needs the same schema module as the room, or the router refuses
it with 4004. The schema is TypeScript, so either bundle the script or
run it with a TypeScript loader.

**Bundle with esbuild**, which a scaffolded project already has:

```sh
npx esbuild scripts/bot.ts --bundle --platform=node --format=esm --packages=external --outfile=.irt/bot.mjs
node .irt/bot.mjs
```

`--packages=external` leaves `@irt/client` and its dependencies in
`node_modules` instead of bundling them, and the schema, imported by a
relative path, is bundled into the script.

**Or run it with a loader** such as [tsx](https://tsx.is):

```sh
npx tsx scripts/bot.ts
```

Node 24's own type stripping (`node scripts/bot.ts`) doesn't work here:
it doesn't rewrite the `.js` extensions in imports such as
`"../src/schema.js"` to the `.ts` files they name.

## A bot

This bot plays the [quickstart's](/docs/guides/quickstart) room, whose
schema is:

```ts
// src/schema.ts
import { defineSchema, entity } from "@irt/room";

export const Player = entity("player", { owner: "string", x: "f32", y: "f32" });
export const Board = entity("board", { moves: "u32" });
export const Mine = entity("mine", { moves: "u32" });
export const schema = defineSchema({ state: Board, private: Mine, entities: [Player] });
```

```ts
// scripts/bot.ts
import { connect, createRoom, joinByCode } from "@irt/client";
import { Player, schema } from "../src/schema.js";

const router = process.argv[2] ?? "http://127.0.0.1:7350";
const project = "dots";

// Create a room with a join code, then resolve the code as a second player would.
const { joinCode } = await createRoom({ router, project, joinCode: true });
const id = await joinByCode({ router, project, code: joinCode!.toLowerCase() });

const room = await connect({ router, project, room: id, schema });
console.log(`joined ${id} as ${room.player}`);
room.on("message", (m) => console.log("message", m));
room.on("closed", (e) => {
  console.log("closed", e.code, e.message);
  process.exit(e.code === 1000 ? 0 : 1);
});

const timer = setInterval(() => {
  room.send({ type: "move", x: Math.random() * 100, y: Math.random() * 100 });
  const others = [...room.entities.all(Player)].filter((p) => p.owner !== room.player);
  console.log(`tick ${room.tick}: ${others.length} others, ${room.state.moves} moves`);
}, 1000);

setTimeout(() => {
  clearInterval(timer);
  room.leave();
}, 10_000);
```

- **The router address** is the same as a browser client's:
  `http://127.0.0.1:7350`, or the `--port` you gave `irt dev`, locally,
  and the one `irt deploy` prints, such as `wss://eu.irt.io`, for a
  deployed project. An `http://` or `https://` address works as well as
  `ws://` and `wss://`.
- **Guests.** Without a `token`, the client joins as a guest when the
  project allows guests. Node has no `localStorage` by default, so the
  guest token is kept in memory: each process is a new guest with a new
  player ID, and private state doesn't carry over between runs. Pass a
  player token from your backend to play as a known player; see
  [Player tokens](/docs/player-tokens). To keep a guest's identity
  across runs with no backend, see [A guest that returns](#a-guest-that-returns).
- **Join codes** are uppercase, but `joinByCode` accepts them in any case
  and with spaces around them, so codes typed by people or passed on a
  command line need no cleaning.
- **Exiting.** An open client keeps the process alive, as it reconnects
  on its own. Call `room.leave()` to end it, and exit on `closed`.

## A guest that returns

The client keeps its guest token in `localStorage` when there is one,
and Node has one behind a flag. Run the script with Node's web storage
turned on and a file to keep it in, and every run is the same guest,
with the same player ID and private state, for as long as the guest
token lasts (30 days):

```sh
node --experimental-webstorage --localstorage-file=.irt/guest.db .irt/bot.mjs
```

That's the simplest way to test "a guest comes back" from a script. Each
file is one guest per project; use another file for a second player. On
Node 24, `--localstorage-file` alone is accepted silently and does
nothing: `localStorage` stays undefined, and each run is a new guest
again. It needs `--experimental-webstorage` with it. Node prints an
experimental warning when the flag is on.

## Predicting from a script

`predict` works in Node too. Its `sample` runs once per room tick from
the next tick on, and receives the prediction, so a bot can steer by
where it predicts itself:

```ts
// scripts/runner.ts
import { connect } from "@irt/client";
import { Runner, schema, stepper } from "../src/shared.js";

const room = await connect({ router: "http://127.0.0.1:7350", project: "runners", room: "track-1", schema });

const me = room.predict(stepper, {
  find: (r) => [...r.entities.all(Runner)].find((e) => e.owner === r.player),
  sample: (p) => ({ dx: (p.entity?.x ?? 0) < 40 ? 1 : 0, dy: 0 }),
});

const check = setInterval(() => {
  if ((me.entity?.x ?? 0) < 40 || !me.settled) return;
  console.log(`reached ${me.entity!.x} after ${me.mispredictions} mispredictions`);
  clearInterval(check);
  room.leave();
}, 100);
```

```ts
// src/shared.ts
import { defineSchema, defineStepper, entity } from "@irt/client";

export const Runner = entity("runner", { owner: "string", x: "f32", y: "f32" });
export const schema = defineSchema({ entities: [Runner] });

export const stepper = defineStepper<{ dx: number; dy: number }>({
  step(world, inputs, dt) {
    for (const r of world.all(Runner)) {
      const input = inputs.get(r.owner);
      if (input) r.x += input.dx * 6 * dt;
    }
  },
});
```

## In tests

To drive a room from a test, use [`@irt/testing`](/docs/reference/testing)
instead: it runs the room in process with the real client and a clock
the test controls, so nothing waits on timers. Scripts like the ones here
are for checking a room as it really runs, under `irt dev` or deployed.

## Common mistakes

- **A copy of the schema in the script.** Import the room's own schema
  module; a copy that drifts gives 4004.
- **Running TypeScript with plain `node`.** Bundle it, or use a loader
  that resolves `.js` imports to `.ts` files.
- **Expecting a bot to keep its player ID across runs.** A guest in Node
  is new each run unless web storage is on; pass a player token, or run
  with `--experimental-webstorage --localstorage-file`.
- **Leaving the process running.** Call `leave()`; the client otherwise
  reconnects for as long as the process lives.

---

# Limits

> Sizes, rates, timeouts and spending caps that rooms, connections and projects work within.

These limits are provisional and may change before launch. Going over a
connection limit closes the connection with the close code listed below.

## Rooms

| Limit | Value |
|---|---|
| Room state | 32 MB; a room whose room state grows past it stops |
| Tick rate | 1 to 120 ticks per second; default 20 |
| Private state of a player who left | kept 24 hours by default; a room's `privateRetention` sets it |
| Room ID | 1 to 64 characters of `A-Z`, `a-z`, `0-9`, `_`, `-` |
| Connections per room | 64 for `standard`, 256 for `large`, 1,024 for `extra-large`; a room's `maxPlayers` caps it lower |
| Hibernate after the last connection leaves | 30 seconds |
| VM stops after its last room hibernates | 5 minutes |
| Wake timeout before held connections are closed | 10 seconds |
| Room state written to object storage | every 30 seconds when changed, and on hibernate |

## Replays and clips

| Limit | Value |
|---|---|
| A replay's records | 64 MB, then recording stops |
| A replay's length | 2 hours, then recording stops |
| One tick's records | 4 MB, or recording stops |
| Recordings a room starts | one every 10 seconds |
| A clip | 1 to 60 seconds |
| Clips | one every 10 seconds, 20 per replay |
| Replays and clips a room keeps | its newest 20 replays and 100 clips |
| Replay retention | `rooms.replayRetention`, 1 hour to 30 days; default 7 days |
| Replay and clip IDs | 1 to 64 characters of `A-Z`, `a-z`, `0-9`, `_`, `-` |

## Player data, collections and leaderboards

| Limit | Value |
|---|---|
| A value | 64 KB of JSON or bytes |
| A player's data | 256 keys and 1 MB |
| Keys and entry IDs | 1 to 64 characters of `A-Z`, `a-z`, `0-9`, `_`, `.`, `:`, `-` |
| An entry's `meta` | 1 KB, flat strings, numbers and booleans |
| A collection | 1,000,000 entries; `maxOwn` per player from clients, default 100 |
| Collections | 32 per project |
| A list or `top` page | 100 entries, 20 by default |
| Leaderboard periods kept | the current one and the three before it |
| Calls | 200 a second and 64 at once per room; 10 a second per client address and per player; 2,000 a second per project |
| Guests minted with `POST /v1/guest` | 10 a minute per client address, with those connecting mints |
| A request | 128 KB |
| Deadline | 5 seconds, then `E_UNAVAILABLE` |
| Guests' player data | deleted 90 days after it was last written |

Reads and writes are metered and free within these limits. See
[Player data, collections and leaderboards](/docs/guides/player-data).

## Messages and connections

| Limit | Value |
|---|---|
| Message size | 64 KB |
| Messages per connection | 120 per second |
| Connections per player per room | 1; a new one closes the old one |
| WebTransport connect before falling back to WebSocket | 3 seconds |

A state update for one tick can span several messages, so a client
entering a large view isn't bound by the message size.

## Outbound calls from rooms

| Limit | Value |
|---|---|
| Protocols and ports | `fetch` to `https://` on port 443 only, by host name |
| Addresses | public only; names resolving to private, loopback or link-local addresses are refused |
| Connections open at once | 64 per VM |
| Bandwidth | 10 MB a second per VM, both directions together |
| Idle connection | closed after 5 minutes |

See [Calling your backend](/docs/reference/room-sdk#calling-your-backend).

## State sync

| Limit | Value |
|---|---|
| A `bytes` field | 48 KB |
| A `string` field | 16 KB of UTF-8 |
| A `json` field | 16 KB serialized |
| An entity, encoded with every field | 61,376 bytes (60 KB minus 64) |
| Prediction inputs held ahead of the room | 32 ticks |
| How far a view tick, and `room.rewind`, reach back | 250 ms (`MAX_REWIND_MS`), plus two ticks kept |
| Lag compensation history | 8 MB per room (`MAX_HISTORY`); 8 bytes per field per kept tick per entity, plus 128 bytes |
| Interest keys a connection subscribes to | 4,096 |
| Entities a connection sees, presence entries included | 16,384 |
| Presence entries in a room | 1,024 |
| A presence name | 64 characters |
| A presence status | 1 KB serialized |

Going over a state sync cap is an error in the room's log; the extra keys
or entities are left out.

## Player tokens

| Limit | Value |
|---|---|
| Lifetime (`exp` after `iat`) | at most 24 hours |
| Player ID (`sub`) | 1 to 128 bytes, not starting with `guest:` |
| `meta` | JSON, up to 1 KB |

## Join codes

6 characters of `A-H`, `J-N`, `P-Z` and `2-9`, so codes have no `I`, `O`,
`0` or `1`.

## Project settings with limits

| Setting | Default | Meaning |
|---|---|---|
| `limits.maxActiveRooms` | 100 | Rooms active at once |
| `limits.maxRoomHoursPerDay` | 200 | Room-hours per day |
| `limits.maxRooms` | 1000 | Rooms that exist at once, hibernated or not |
| `limits.maxSleepingConnections` | 10,000 | Connections the project's [sleeping rooms](/docs/hibernation#sleeping-rooms) hold in a region; past it, a room that sleeps closes its connections with 4011 |
| `voice.maxSpeakers` | 64 | Speakers each listener hears, 1 to 64, a ceiling on each room's own; see [Proximity voice](/docs/guides/proximity-voice#turning-it-on) |
| `rooms.retention` | `"7d"` | How long a hibernated room is kept: `"none"`, `"<n>h"`, `"<n>d"` up to 365 days, or `"forever"` |

The `limits` are spending caps, set only in the dashboard, never from
`irt.config.ts`. A project over `maxActiveRooms` or `maxRoomHoursPerDay`
can't wake more rooms, and clients get close code 4009. At 80% of either,
IRT sends a [usage alert](/docs/stats#usage-alerts) first. A project at
`maxRooms` can't create more until rooms expire or are deleted. A project
can have 10,000 active [bans](/docs/moderation).

## Credit

Usage is paid from your account's prepaid credit, which you top up by
card on the dashboard's Billing page. Below a low-balance threshold the
dashboard shows a banner and each project with a webhook gets a
`billing.low_balance` event. When the balance reaches zero your projects
keep running for 24 hours. After that they can't wake rooms, their
players are disconnected with close code 4009, the server API answers
`429 limit`, and running rooms hibernate. Topping up undoes this at
once. Running out never deletes a room.

## Close codes

| Code | Meaning | Client SDK |
|---|---|---|
| 4000 | Protocol version not supported | Fails; the site needs a newer SDK |
| 4001 | Token invalid or expired | Fails |
| 4002 | Room not found, and `players.createRooms` is off | Fails |
| 4003 | Room full: at its size's connection limit or its `maxPlayers` | Fails |
| 4004 | Schema differs from the room's build | Fails; rebuild and redeploy the client and room together, or reload the site |
| 4005 | Rate or size limit exceeded | Reconnects after backoff |
| 4006 | Kicked by the room, or its `onJoin` threw | Fails |
| 4007 | Room stopped | Fails |
| 4008 | Room moved or restarted | Reconnects at once |
| 4009 | Project over its spending limit, or out of credit | Fails |
| 4010 | Wake timed out | Reconnects after backoff |
| 4011 | The room hibernated by its own request, or went to sleep past `limits.maxSleepingConnections` | Fails; the game can offer to rejoin |
| 4012 | The same player connected again elsewhere | Fails |
| 4013 | The player is [banned](/docs/moderation) from the project | Fails |

Any other close reconnects with backoff. See [Errors and close
codes](/docs/reference/errors) for what causes each and what to do.

---

# Player data, collections and leaderboards

> Keep a player's progress across rooms, store what players make, and rank players, from room code or the client, with no backend of your own.

A room's state lasts as long as the room. Some data outlives every
room: a player's progress, the levels players build, a high score
table. IRT keeps it for you in the **data service**, the same from room
code, from a client and from the [server API](/docs/http-api):

- **Player data**: keys per player per project, each a JSON or bytes
  value of at most 64 KB with a version that goes up on every write. A
  player has at most 256 keys and 1 MB.
- **Collections**: named sets of **entries** you declare in
  `irt.config.ts`. An entry has an `id`, a value, flat `meta` you filter
  on, an optional `score` you sort on, an optional `owner`, a `version`
  and its `created` and `updated` times.
- **Leaderboards**: collections with leaderboard settings, holding one
  score per player per period, written by `submit`.

Data for one player in one room needs none of this: keep it in the
room's [private state](/docs/room-state), which is room state.

## Declaring it

```ts
// irt.config.ts
import { defineConfig } from "@irt/cli/config";

export default defineConfig({
  project: "my-game",
  room: "src/room.ts",
  settings: {
    data: {
      player: {
        clientWrite: ["settings"],
      },
      collections: {
        levels: { clientRead: true, clientWrite: "own", maxOwn: 50 },
        highscores: {
          clientRead: true,
          leaderboard: { order: "desc", keep: "best", periods: ["all", "week"] },
        },
      },
    },
  },
});
```

| Setting | Default | Meaning |
|---|---|---|
| `data.player.clientWrite` | none | The player data keys a client may write for its own player. A client always reads its own player's data. |
| `collections.<name>` | | Names are 1 to 32 of `a-z 0-9 _ -`, starting with a letter; at most 32 collections |
| `clientRead` | `false` | Any client may get and list the entries, or read the board |
| `clientWrite` | none | `"own"`: a client may create entries and change and delete the ones it owns, or submit its own score |
| `maxOwn` | `100` | The most entries one player creates from clients, 1 to 10,000 |
| `leaderboard.order` | `"desc"` | `"desc"` or `"asc"`; it also decides what the best score is |
| `leaderboard.keep` | `"best"` | `"best"`, `"latest"` or `"sum"` |
| `leaderboard.periods` | `["all"]` | Any of `"all"`, `"day"`, `"week"` and `"month"`, in UTC; weeks are ISO weeks from Monday |

Room code may do anything with any declared collection; the client
settings only limit clients. A board's `order` and `keep` can't change
once a live build declared it: declare a board under a new name for a
new rule. A collection you remove keeps its entries, unreachable, until
you declare it again.

## From room code

```ts
// src/room.ts
import { DataError, defineRoom } from "@irt/room";

interface Save {
  level: number;
  coins: number;
}

export default defineRoom({
  async onJoin(room, conn) {
    // Load once, then keep it in memory for the rest of the visit.
    const save = await room.playerData(conn.player).get<Save>("save");
    conn.data.save = save?.value ?? { level: 1, coins: 0 };
    conn.data.version = save?.version ?? 0;
  },
  async onMessage(room, conn, message) {
    const m = message as { type?: string; score?: unknown };
    if (m.type === "level-done" && typeof m.score === "number") {
      const save: Save = { ...conn.data.save, level: conn.data.save.level + 1 };
      try {
        const { version } = await room.playerData(conn.player).set("save", save, { version: conn.data.version });
        conn.data.save = save;
        conn.data.version = version;
      } catch (e) {
        if (!(e instanceof DataError)) throw e;
        room.send(conn, { error: e.code });
      }
      await room.leaderboard("highscores").submit(conn.player, m.score, { meta: { level: save.level } });
    }
  },
});
```

`room.playerData(player)` has `get`, `set`, `increment`, `delete`,
`list` and `refresh`:

- `get(key)` resolves with `{ value, version }`, or `undefined` when the
  key has none. A value is any JSON or a `Uint8Array`.
- `set(key, value, { version?, once? })` resolves with `{ version }`. Without
  `version` the write is unconditional. With it, the write fails with
  `E_VERSION` unless the key has that version; `version: 0` means the key
  must have none.
- `increment(key, by, { once? })` adds to a number in one step, creating it at 0,
  and resolves with the new number. On a value that isn't a number it
  fails with `E_TYPE`.
- `delete(key, { version?, once? })` resolves with whether the key existed.
- `list()` gives every key with its value and version.

`room.collection(name)` has `get(id)`, `put({ id?, value, meta?, score?,
owner?, version?, once? })`, which resolves with `{ id, version }` and
makes up an ID when you give none, `list({ where?, owner?, order?,
limit?, after? })` and `delete(id, { version?, once? })`. `once` makes
a write safe to repeat; see
[Writes that may or may not have happened](#writes-that-may-or-may-not-have-happened). `put` replaces the whole entry:
`meta`, `score` and `owner` left out become empty.

```ts
// levels.ts
import type { Connection, Room } from "@irt/room";

export async function publish(room: Room, conn: Connection, tiles: number[]) {
  const levels = room.collection("levels");
  const { id } = await levels.put({ value: { tiles }, meta: { theme: "ice", size: tiles.length }, owner: conn.player });
  const page = await levels.list({ where: { theme: "ice" }, order: "-created", limit: 20 });
  const mine = await levels.list({ owner: conn.player });
  return { id, newest: page.entries, count: mine.entries.length, more: page.next !== null };
}
```

A list gives at most 100 entries a page, 20 by default, each **without
its value**, so a page stays small; `get` fetches one value. Pass
`next` as `after` for the next page; it's `null` on the last. `where`
matches `meta` keys by equality, all of them; `order` is `score`,
`-score`, `created`, `-created` (the default), `updated` or `-updated`.

`room.leaderboard(name)` has `submit(player, score, { meta?, once? })`, which
applies the board's `keep` rule to the player's entry of every period at
once and resolves with what each keeps, `top({ period?, limit?, after?
})` and `around(player, { period?, count? })`, the player's rank and up
to `count` entries either side, or `undefined` when they have no entry.
A period is `"all"` (the default), `"day"`, `"week"` or `"month"` for
the current one, or a full name such as `"week:2026-W45"` for one of the
three before it, which are kept; older ones are deleted. Ranks go by
score, then by who reached it first.

## The cache in the room

Each room keeps what it read and wrote of player data and entries for 5
seconds: a `get` within 5 seconds of the room's last read or write of
the same key or entry is answered from memory, with no call. So:

- A room always sees its own writes. After its own `put`, the next
  `get` of that entry is a call, since the data service sets the
  entry's times; the rest is cached as above.
- Another writer's change, from another room, a client or your backend,
  shows within 5 seconds. Call `refresh()` on the player's data or the
  collection to drop what the room holds and read it again.
- `list`, `top` and `around` are never cached; each is a call.

The cache is what keeps a `get` in `onTick` from reaching the limits,
but a hit doesn't extend it: a `get` every tick still makes a call
every 5 seconds. Load what a player
needs in `onJoin`, keep it in `conn.data` or private state, and write it
back when it changes, rather than calling `get` every tick for data the
room is the only writer of. Don't call `list` or `top` per tick; call
them on an event, or every few seconds.

## From a client

Clients use the same calls for the player they are, over the router's
HTTP API, with or without a room connection:

```ts
// client-data.ts
import { connect, dataClient } from "@irt/client";

const router = "wss://eu.irt.io";
const data = dataClient({ router, project: "my-game" });
await data.playerData.set("settings", { volume: 0.5 });
const best = await data.leaderboard("highscores").top({ period: "week", limit: 10 });
const me = await data.leaderboard("highscores").around({ count: 2 });

const room = await connect({ router, project: "my-game", room: "arena" });
const levels = await room.collection("levels").list({ order: "-score" });
console.log(best.entries, me?.rank, levels.entries);
```

`client.playerData`, `client.collection(name)` and
`client.leaderboard(name)` on a connected `RoomClient` are the same as
`dataClient`'s. A guest with no token gets one from `POST /v1/guest` on
its first call, kept where `connect` keeps its guest token, so a guest
is one player across rooms and data calls. A player token from your
backend works too: pass `token`. A client may:

- read its own player's data, and write only the keys in
  `data.player.clientWrite`;
- get and list entries and read a board with `clientRead`;
- with `clientWrite: "own"`, create entries, change and delete its own,
  and submit its own score. `owner` is always set to the client's
  player, whatever it sends, and `maxOwn` caps how many it creates.

**A score a client submits can be faked**: any player can send any
number. Submit from room code, which decides the score, for any board
that matters. Native rooms, which run no room code, need
`clientWrite: "own"`.

## Writes that may or may not have happened

Every call has a 5-second deadline. When the data service can't be
reached in time, room code and clients get `E_UNAVAILABLE`; nothing is
queued. A write that timed out may or may not have been made. A room can
also wake after a host failure without the last 30 seconds of its room
state, while the data writes it made in them are kept. Either way, room
code may make a write again that already happened.

From room code, give each write a `once` key built from what happened,
and repeating it is safe. A write whose key the project used in the
last day doesn't run again: it resolves as the first one did, without
counting as a write. The same key with different arguments fails with
`E_INVALID`. Every write takes it: `set`, `increment` and `delete` on
player data, `put` and `delete` on a collection, and `submit` on a
leaderboard. Keys are 1 to 64 characters of letters, digits, `_`, `.`,
`:` and `-`.

```ts
// reward.ts
import { DataError, type Room } from "@irt/room";

// The match's ID was in room state since the match began, so a room that wakes after a host
// failure still knows it, and rewarding the match again adds nothing.
export async function reward(room: Room, matchId: string, winners: string[]): Promise<void> {
  for (const player of winners) {
    for (let attempt = 0; ; attempt++) {
      try {
        await room.playerData(player).increment("coins", 50, { once: `reward:${matchId}:${player}` });
        break;
      } catch (e) {
        if (e instanceof DataError && e.code === "E_UNAVAILABLE" && attempt < 3) continue;
        throw e;
      }
    }
  }
}
```

To pair a write with room state, keep what you're about to do in room
state first, such as the matches still to reward, then write with a
`once` key derived from it, then clear it. In `onWake`, finish whatever
is still there. The key has to come from something in room state from
before the write, not from a counter the lost seconds could reset, or
the repeat gets a new key and runs again. A repeated `increment`
resolves with the number the first one made, which may have changed
since; `get` reads it now.

Clients can't use `once`, so a player can't take a room's key first.
Retry a client's write with `version`, which fails with `E_VERSION` if
it was made:

```ts
// retry.ts
import { DataError, type PlayerData } from "@irt/room";

export async function saveOnce(data: PlayerData, value: unknown, version: number): Promise<number> {
  for (let attempt = 0; ; attempt++) {
    try {
      return (await data.set("save", value, { version })).version;
    } catch (e) {
      if (!(e instanceof DataError)) throw e;
      if (e.code === "E_UNAVAILABLE" && attempt < 3) continue;
      if (e.code === "E_VERSION") {
        const now = await data.get("save");
        // Written by the try that timed out, or by another writer: compare before writing again.
        if (now && JSON.stringify(now.value) === JSON.stringify(value)) return now.version;
      }
      throw e;
    }
  }
}
```

## Who wrote an entry

Use `owner` for authorship, not `meta`. A client's writes always carry
its own player as `owner`, set by the data service, while `meta` is
whatever the writer sent, so a `meta.author` a client set proves
nothing. `list({ owner })` finds a player's entries, and deleting a
player through the server API deletes every entry they own.

## Errors

Calls reject with `DataError`, whose `code` is one of:

| Code | When |
|---|---|
| `E_INVALID` | A malformed call, or one over a size limit |
| `E_FORBIDDEN` | The caller may not do it, such as a client writing a key not in `clientWrite` |
| `E_UNKNOWN` | The collection isn't declared in the live build, or it's the wrong kind for the call |
| `E_VERSION` | `version` didn't match |
| `E_TYPE` | `increment` on a value that isn't a number |
| `E_QUOTA` | Over a player's 256 keys or 1 MB, a collection's 1,000,000 entries, or `maxOwn` |
| `E_LIMIT` | Over a rate limit |
| `E_SPENDING` | The project is over its spending limit, or out of credit |
| `E_UNAVAILABLE` | The data service couldn't be reached; a write may or may not have happened |

## Limits

| What | Limit |
|---|---|
| A value | 64 KB of JSON or bytes |
| A player | 256 keys, 1 MB |
| `meta` | 1 KB, flat strings, numbers and booleans |
| A collection | 1,000,000 entries |
| A project | 32 collections, 2,000 calls a second |
| A room | 200 calls a second, 64 at once |
| A client address, and a player | 10 calls a second |
| Guests minted per client address | 10 a minute |
| A request | 128 KB |

Guests' player data is deleted 90 days after it was last written; a
guest whose token is lost can't get back to it. Player data of your own
player IDs is kept until your backend deletes the player. Calls are
metered and free within the limits; see
[Limits](/docs/limits#player-data-collections-and-leaderboards).

## Locally and in tests

`irt dev` and [self-hosted](/docs/self-hosting) room hosts run the same
calls on SQLite, in `data.sqlite` in the data directory, `.irt/data` for
`irt dev`, and serve `POST /v1/data/{project}` and `POST /v1/guest` as
the router does. `@irt/testing` keeps it in memory and lets a test seed
and read it:

```ts
// data.test.ts
import { createTestHost } from "@irt/testing";
import { expect, test } from "vitest";
import room from "./src/room.js";

test("a finished level is saved and scored", async () => {
  const host = createTestHost(room, {
    settings: { data: { collections: { highscores: { leaderboard: { periods: ["all", "week"] } } } } },
  });
  await host.playerData("ada").set("save", { level: 3, coins: 0 });
  const ada = await host.room("arena").connect({ player: "ada" });
  ada.send({ type: "level-done", score: 1200 });
  await host.tick();
  expect(await host.playerData("ada").get("save")).toMatchObject({ value: { level: 4 } });
  const top = await host.leaderboard("highscores").top({ period: "week" });
  expect(top.entries[0]).toMatchObject({ player: "ada", score: 1200 });
});
```

---

# Replays and clips

> Record a room tick by tick, keep its best moments as clips, and play either back in the browser with the code that renders the live game.

A **replay** is a recording of a room's synced state, tick by tick: what
a client that sees every entity would have seen. A **clip** is the last
few seconds of a replay, kept after the replay itself expires. You play
both with `@irt/client/replay`, into an entity store with the same
events as a live room, so the code that renders your game renders its
replays too.

Nothing is recorded unless the room asks. Replays are never public: your
backend downloads them with its API key and decides who may watch.

## Recording

```ts
import { defineRoom } from "@irt/room";
import { schema } from "./schema.js";

export default defineRoom({
  schema,
  onCreate(room) {
    room.data.replay = room.record();
  },
  onWake(room) {
    room.data.replay = room.record();
  },
  onTick(room) {
    // ...
  },
});
```

`room.record()` starts recording from the room's next tick and returns
the replay's ID. Recording stops with `room.stopRecording()`, when the
room hibernates or stops, and when the replay reaches 64 MB or 2 hours.
A recording isn't room state, so a room that always records calls
`record` in `onWake` as well as `onCreate`; after a hibernation, or a
crash of its room host, it's a new replay. `room.recording` is the ID
being recorded, or undefined.

Options:

- `id`: your own ID, such as a match ID, 1 to 64 of `A-Z`, `a-z`, `0-9`,
  `_` and `-`. A room uses an ID once; recording under an ID it has used
  keeps nothing, and the project's logs say so. Without one you get a
  random ID.
- `private`: also record each player's private state. **Off by
  default.** Whoever can watch a replay sees everything in it, so turn
  this on only for replays that only you or the player see, or after a
  game where hands no longer matter.
- `messages`: also record what the room broadcasts to every connection,
  such as chat or kill feed events. Messages to one connection are never
  recorded.

```ts
room.record({ id: `match-${matchId}`, messages: true });
```

`record` throws when the room is already recording, and when it started
a recording less than 10 seconds ago.

## What a replay holds

The shared state, every entity and presence, every tick that changed
any of them, and a full state every 10 seconds so playback can seek.
Interest doesn't apply: a replay sees everything, whoever could see it
at the time. Owner writes appear as the changes they made; corrections,
inputs and client messages aren't recorded.

A replay carries the kinds and fields it was recorded with, as room
state does, so it plays after you change your schema.

## Clips

```ts
onMessage(room, connection, message) {
  if (message.type === "ace") room.clip({ seconds: 15, id: `ace-${room.tick}` });
},
```

`room.clip({ seconds })` keeps the last 1 to 60 seconds of the current
recording and returns the clip's ID. A room makes at most one clip every
10 seconds and 20 per replay. A clip is kept until you delete it, after
its replay has expired.

To clip from your backend, send the room a message and call `clip` in
`onRequest`, returning the ID:

```ts
onRequest(room, message) {
  if (message.type === "clip") return { clip: room.clip({ seconds: message.seconds }) };
},
```

## Downloading

Your backend lists a room's replays and clips and downloads their files
with the project's API key:

```sh
curl -H "Authorization: Bearer $IRT_API_KEY" \
  https://api.irt.io/v1/projects/my-game/rooms/match-42/replays
curl -H "Authorization: Bearer $IRT_API_KEY" -o match.irtr \
  https://api.irt.io/v1/projects/my-game/rooms/match-42/replays/match-42/file
```

The listing says when each replay started and ended, its ticks, size and
when it expires. A file grows while its replay records. Serve it to the
players you choose, from your own backend or storage.

## Playing back

```ts
import { loadReplay } from "@irt/client/replay";
import { Ball, schema } from "./schema.js";

const bytes = new Uint8Array(await (await fetch("/my-backend/replays/match-42")).arrayBuffer());
const replay = loadReplay(bytes, { schema });

replay.entities.onEnter(Ball, (b) => scene.add(b.id));
replay.entities.onChange(Ball, (b) => scene.move(b.id, b.x, b.y));
replay.entities.onLeave(Ball, (b) => scene.remove(b.id));
replay.on("message", (m) => feed.push(m));

replay.play();         // at the room's tick rate
replay.speed = 2;      // twice as fast
replay.pause();
replay.seek(1200);     // any tick from replay.firstTick to replay.lastTick
replay.step();         // the next tick; false at the end
```

- `replay.entities` is an `EntityStore`, as `room.entities` is on a live
  client, and `replay.state` and `replay.presence` work the same way.
  Entities are read-only.
- A seek starts from the full state at or before the tick, so it's fast
  anywhere in a replay. Entities shown before leave and those at the tick
  enter, without the changes between. Recorded messages fire only while
  playing through their tick.
- With `schema`, a kind whose fields are as recorded is your kind, so
  `entities.all(Ball)` finds its entities. A kind you've changed since is
  read from the replay: `replay.kind("ball")` returns it.
- `replay.privateOf(player)` is a player's private state, when the replay
  recorded it.
- A clip loads the same way and starts at its first second.

`@irt/client/replay` is a separate entry, so a game that doesn't play
replays doesn't carry it.

## Testing

`@irt/testing` keeps replays in memory:

```ts
const room = testRoom(game);
const alice = await room.connect({ player: "alice" });
await room.host.tick(100);
const replay = room.replay(room.live.recording!);
replay.seek(50);
expect([...replay.entities.all(Ball)]).toHaveLength(3);
```

`room.replays()` and `room.clips()` list IDs, and `room.clip(id)` loads
a clip. `irt dev` keeps replays on disk next to room state.

## Retention and cost

A replay is deleted `rooms.replayRetention` after it ends: 7 days by
default, from 1 hour to 30 days, set in `irt.config.ts` or the
dashboard. A room keeps its newest 20 replays and 100 clips. Deleting a
room through the API deletes its replays and clips; a room deleted by
its own retention keeps them until they expire or you delete them.

Replays and clips are billed as storage, by what IRT writes, never by
anything your room reports. See [Limits](/docs/limits#replays-and-clips).

---

# Lobbies and parties

> Gather players in a lobby declared in irt.config.ts, with ready and start rules, a countdown and bots, and hand them off to a room of another type; keep a party together across rooms; and hand players off from your own room code.

Most multiplayer games start with players gathering: friends with an
invite code, or strangers quick joining until there are enough. A
**lobby** does this without any room code. It's a
[native room](/docs/concepts#rooms) with lobby settings: players join
it, mark themselves ready, and when its start rule holds it counts down
and hands everyone off to a new room of another type. The router makes
that room, holds a seat in it for each player, and tells their clients,
which connect by themselves. A failure, such as the project being at its
room limit, leaves everyone in the lobby with the reason.

## Declare a lobby

A lobby is a native room type with `lobby` settings, in
`irt.config.ts`:

```ts
// irt.config.ts
import { defineConfig } from "@irt/cli/config";

export default defineConfig({
  project: "space-race",
  rooms: {
    lobby: {
      native: true,
      size: "small",
      lobby: {
        minPlayers: 2,
        maxPlayers: 4,
        start: "allReady",
        countdown: 5,
        to: { type: "match" },
        bots: { wait: 20, upTo: "min", behaviour: "racer" },
      },
    },
    match: { room: "src/match.ts", maxPlayers: 4 },
  },
});
```

| Setting | Meaning |
|---|---|
| `maxPlayers` | The lobby's seats, at most its size's connection limit and the `to` type's `maxPlayers` or connection limit. A lobby type doesn't also set the type's own `maxPlayers` |
| `minPlayers` | The fewest people and bots the countdown starts with, 1 to `maxPlayers`. Default 1 |
| `start` | `"allReady"` (the default): every person is ready. `"leader"`: only the leader's `start`. `"full"`: a join, of a person or a bot, brings the lobby to `maxPlayers`. Under every rule the leader can also call `start` |
| `countdown` | Seconds from the start rule holding to the handoff, 0 to 60. Default 5 |
| `to` | `{ type }`, a room type of the build, standard or native: each handoff makes a new private room of it. With `quickJoin: true` the people go to a public room of it instead, with no bots; see [Parties](#parties) |
| `stay` | Keep the players connected to the lobby while they play. Default false |
| `bots` | Optional: fill seats with bots, for a standard `to` type; see [Bots](#bots) |

`irt build` and `irt deploy` refuse a lobby whose `to.type` isn't a type
of the build, whose `maxPlayers` is more than the target seats, with
`bots` and a native target or `quickJoin`, with `upTo: "min"` and
`start: "full"`, with `quickJoin` and no `stay`, or with bots running a behaviour the target
room doesn't declare. The manifest carries the settings on the type as
`lobby`, every default filled in.

## What players see

```
waiting -> countdown -> handing-off -> waiting
```

- **waiting**: people join and set ready. The countdown starts when the
  start rule holds, or the leader calls `start`, with at least
  `minPlayers` people and bots.
- **countdown**: ends after `countdown` seconds, or goes back to waiting
  when the lobby drops below `minPlayers`, or, under `allReady`, someone
  un-readies. The leader can cancel it, which clears every ready flag,
  so the countdown doesn't start again at once.
- **handing-off**: the lobby has asked the router for the room and takes
  no one new; a connection arriving now is refused with 4003. It ends
  with the router's answer, or after 15 seconds without one.

Then it's back at waiting with every ready flag cleared. Without `stay`
its people have moved on, so a public lobby is a standing place to
gather, not one room per game. A lobby that is still full after a
handoff, such as a `"full"` party, doesn't count down again until
someone joins it at `maxPlayers` or the leader calls `start`. A person
whose client couldn't reach the new room stays in the lobby as before,
and the next handoff takes them too.

The client SDK keeps the lobby's state in `client.lobby`, and marks
ready, starts and cancels with calls:

```ts
// web/lobby.ts
import { connect, type RoomClient } from "@irt/client";
import { matchSchema } from "./schema.js";

const lobby = await connect({
  router: "wss://eu.irt.io",
  project: "space-race",
  room: "public-lobby",
  type: "lobby",
  targets: { match: matchSchema },
});

lobby.on("lobby", (state) => {
  if (state.phase === "countdown") console.log(`starting at ${new Date(state.startsAt!)}`);
  if (state.failed) console.log("the last start failed:", state.failed);
});

lobby.onHandoff((handoff) => {
  if (handoff.error) return console.log("couldn't join the match:", handoff.error.message);
  play(handoff.client);
});

await lobby.setReady(true);

declare function play(match: RoomClient<any, any, any>): void;
```

```ts
// web/schema.ts
import { defineSchema, entity } from "@irt/client";

export const matchSchema = defineSchema({ state: entity("race", { lap: "u8" }) });
```

`client.lobby` is `{ phase, ready, startsAt, min, max, failed }`:
`ready` lists the ready people, in the order they joined, then every
bot, which is always ready; `startsAt` is when the countdown ends, in
the room's wall-clock milliseconds, so compare it with
`client.serverTime()`; `failed` is why the last handoff failed, until the
next countdown: `players` (too few were still connected), `limit` (the
project is at `limits.maxRooms`, or the lobby handed off 6 times in a
minute), `spending` or `unavailable`.

**Following a handoff.** When the router hands the player off, the
client connects to the new room itself, with the schema `targets` names
for its type, and once it holds the room's state it leaves the lobby,
unless the lobby has `stay`, and calls `onHandoff` with the new
`RoomClient`. If it can't connect, `onHandoff` gets the error and the
client stays in the lobby. The router holds each player's seat for 10
seconds from when their client reaches it, through a wake. A token bound
to the lobby by its `room` claim is accepted at a room the lobby's
handoff created, for each person it brought there, so a reconnect later
works too.

A client older than protocol 4 can ready and start through calls, but
the router never moves it: it's left out of the handoff, as someone who
just disconnected would be.

## The lobby element

`<irt-lobby>`, from the [UI kit](/docs/ui-kit) at `@irt/client/ui/lobby`,
shows an `<irt-invite>` for the code, share link and QR code, the
lobby's players with who is ready and who leads, a ready button, start
and cancel buttons for the leader, a "Make leader" button beside each
other connected player for the leader, the countdown, and why a handoff
failed. Give it the lobby's client, and take the new room's client from
its `handoff` event. The invite, `el.invite`, replaced the lobby
element's name field and create and join buttons; find the lobby with
it or the [room browser](/docs/ui-kit#irt-room-browser), and theme it
with the kit's shared `--irt-*` properties, which replaced
`--irt-panel-*`.

```html
<irt-lobby router="wss://eu.irt.io" project="space-race" qr></irt-lobby>
```

```ts
// web/element.ts
import { RoomClient } from "@irt/client";
import "@irt/client/ui/lobby";
import { matchSchema } from "./schema.js";

const el = document.querySelector("irt-lobby")!;
el.invite.addEventListener("room-join", (e) => {
  el.client?.leave();
  el.client = new RoomClient({ router: el.router, project: el.project, room: e.detail.room, type: "lobby", targets: { match: matchSchema } });
});
el.addEventListener("handoff", (e) => {
  if (e.detail.client) el.hidden = true;
});
```

The invite joins the room a share link names and fires `room-join`. For
a lobby found another way, such as by quick join, set `el.invite.room`
and `el.invite.code` so players can share it. The start button shows to
the leader while the lobby waits, and the cancel button during the
countdown. Its text is in `labels`, as `LobbyLabels`, with
`countdown`'s `{n}` for the seconds left. It takes the kit's theme,
opens as a dialog with the `dialog` attribute, and its parts are listed
on the [UI kit](/docs/ui-kit#irt-lobby) page.

## Bots

With `bots`, the lobby fills empty seats so a game can start without
waiting for strangers:

- `wait` seconds after its first person joins, 20 by default, the lobby
  adds bots until people and bots reach `upTo`: `"min"`, the default,
  is `minPlayers`, and `"max"` is `maxPlayers`. It keeps them at that
  number, so each person who joins takes a bot's seat.
- A bot is in presence with a `bot:` ID and a name, never in voice, and
  always ready. In the lobby it only holds a seat.
- The handoff brings the bots along: the new room has them in
  `room.bots`, with the same IDs and names, running the `behaviour`
  named in the settings, before its `onCreate` runs. See
  [Bots](/docs/guides/bots).
- After a handoff the lobby has no bots, since they went with the
  people, and the wait for new ones starts again. An empty lobby has no
  bots, and one that hibernates comes back with none.

## Parties

A **party** is a lobby with `stay: true`, usually private with a join
code. Its people keep their party connection while they play, so the
party keeps its leader, invite code and presence, and when they're done
with the match they're already back in the party's waiting phase, ready
for the next one. Nothing has to send them back: they never left.

- `to: { type }` takes the party to a new private room, as for any lobby.
- `to: { type, quickJoin: true }` takes it into a public room of that
  type whose `meta` matches the party's own `meta`, with space for
  everyone, the fullest first, as quick join picks; else a new public
  room with that `meta`. The router holds a seat for each person, so
  players quick joining at the same moment don't split the party.
  `quickJoin` needs `stay`, and takes people only, so it can't have
  `bots`.
- A party is billed as the native room it is, for every hour anyone is
  connected to it, the time they spend in the match included.

## From your own room code

A standard room with its own idea of a lobby, with team picks or a map
vote, asks the router for the same handoff with `room.handoff`:

```ts
// src/hall.ts
import { defineRoom, HandoffFailed, isBot } from "@irt/room";

export default defineRoom({
  async onMessage(room, _conn, message) {
    if ((message as { type?: string }).type !== "go") return;
    const people = [...room.presence].filter((p) => p.connected && !isBot(p.player));
    try {
      const { room: id } = await room.handoff({ players: people, to: { type: "match", meta: { map: "dunes" } }, stay: true });
      room.broadcast({ type: "started", room: id });
    } catch (e) {
      if (e instanceof HandoffFailed) room.broadcast({ type: "failed", reason: e.reason });
      else throw e;
    }
  },
});
```

It moves people connected to the calling room only, never bots, into a
room of a type of the live build: a new private one with `to.meta`, or
with `quickJoin` a public one, and resolves once their clients have been
told. It rejects with `HandoffFailed`, whose `reason` is `players`,
`limit`, `spending`, `unavailable` or `invalid`, and nobody moves. A
room hands off at most 6 times a minute.

The room a handoff created has `room.from`, `{ lobby, players, bots }`,
before `onCreate`: the room they came from and who it brought, with the
names and statuses they had there. It's `null` in a room no handoff
created, and in one a quick join picked or made.

## Testing

`@irt/testing` runs lobbies in process, with the target type in
`types`:

```ts
// test/lobby.test.ts
import { defineRoom, nativeRoom } from "@irt/room";
import { createTestHost } from "@irt/testing";
import { expect, it } from "vitest";

it("moves two ready players into a match", async () => {
  const host = createTestHost(nativeRoom(undefined, { lobby: { minPlayers: 2, maxPlayers: 2, countdown: 0, to: { type: "match" } } }), {
    types: { match: defineRoom({}) },
  });
  const lobby = host.room("lobby");
  const [ada, bob] = [await lobby.connect({ player: "ada" }), await lobby.connect({ player: "bob" })];
  await ada.client.setReady(true);
  await bob.client.setReady(true);
  await host.tick(4);
  expect(ada.handoffs[0]?.room).toBe(bob.handoffs[0]?.room);
});
```

---

# Engines and frameworks

> How @irt/client fits a rendering engine or UI framework, with the room and shared module every integration guide uses.

`@irt/client` doesn't draw anything and doesn't need an adapter: it
holds the room's entities and tells you when they change, and your
engine draws them. The guides in this section show the same game in
[Phaser](/docs/integrations/phaser), [PixiJS](/docs/integrations/pixi),
[Three.js](/docs/integrations/three), [Babylon.js](/docs/integrations/babylon)
and [React](/docs/integrations/react). Each does the same six things:

| Task | IRT API | In the engine |
|---|---|---|
| Connect and show the connection's state | `new RoomClient(...)`, `ready`, `waking`, `disconnected`, `restored`, `closed` | A status label |
| Make and drop an engine object per entity | `entities.onEnter`, `onChange`, `onLeave` | Sprites, meshes, components |
| Move remote entities smoothly | `room.interpolate(kind, fields)`, `get(entity)` | The engine's frame loop |
| Move the local player at once | `room.predict(stepper, { find, sample })`, `render(fields)` | The same frame loop |
| Write direct input | Writable fields on `entities.mine(kind)` | Pointer events |
| Ask the room for something | `room.call(name, args)` | A button |

## The game

Every player is a runner moved by the arrow keys, which points where the
pointer is and can buy items with coins. Movement is predicted; aim is a
writable field the player owns. The room and its clients import one
module:

```ts
// shared.ts
import { defineCalls, defineSchema, defineStepper, entity } from "@irt/room";

export const Runner = entity("runner", { owner: "string", x: "f32", y: "f32", angle: "f32" }, { writable: ["angle"] });
export const Wallet = entity("wallet", { coins: "u32" });
export const Match = entity("match", { round: "u16" });

export const prices = { dash: 20, shield: 50 };
export type Item = keyof typeof prices;

export const schema = defineSchema({
  state: Match,
  private: Wallet,
  entities: [Runner],
  calls: defineCalls<{ buy(args: { item: Item }): { coins: number } }>({
    buy(raw) {
      const item = (raw as { item?: unknown } | null)?.item;
      if (typeof item !== "string" || !Object.hasOwn(prices, item)) throw new Error("unknown item");
      return { item: item as Item };
    },
  }),
});

export interface Input {
  dx: number;
  dy: number;
}

const SPEED = 6;

export const stepper = defineStepper<Input>({
  parseInput(raw) {
    const i = raw as Partial<Input>;
    if (typeof i.dx !== "number" || typeof i.dy !== "number" || Math.abs(i.dx) > 1 || Math.abs(i.dy) > 1) {
      throw new TypeError("input is { dx, dy } with each from -1 to 1");
    }
    return { dx: i.dx, dy: i.dy };
  },
  step(world, inputs, dt) {
    for (const r of world.all(Runner)) {
      const input = inputs.get(r.owner);
      if (!input) continue;
      r.x += input.dx * SPEED * dt;
      r.y += input.dy * SPEED * dt;
    }
  },
});
```

`x` and `y` are in world units, and `angle` is in radians from the +x
axis toward +y. The runner belongs to its player, so the player can write
`angle`; `x` and `y` aren't writable, so the room's stepper moves them
and the client predicts them. The room:

```ts
// room.ts
import { defineRoom, grid } from "@irt/room";
import { prices, Runner, schema, stepper } from "./shared.js";

export default defineRoom({
  schema,
  tickRate: 30,
  stepper,
  interest: grid({ cellSize: 16, range: 40, dims: "xy", around: (_room, conn) => conn.data.runner }),
  voice: {},
  onJoin(room, conn) {
    const [existing] = room.entities.ownedBy(conn.player, Runner);
    conn.data.runner = existing ?? room.entities.create(Runner, { owner: conn.player }, { owner: conn.player });
    const wallet = room.private(conn);
    if (wallet.coins === 0) wallet.coins = 100;
  },
  onWrite(room, conn, entity, next) {
    return Number.isFinite(next.angle) ? next : undefined;
  },
  calls: {
    buy(room, conn, { item }) {
      const wallet = room.private(conn);
      if (wallet.coins < prices[item]) throw new Error("not enough coins");
      wallet.coins -= prices[item];
      return { coins: wallet.coins };
    },
  },
  onLeave(room, conn) {
    room.entities.delete(conn.data.runner);
  },
});
```

`onWrite` keeps a modified client from writing `NaN` or `Infinity`: an
`f32` field accepts both, and every other client would draw it.

## Connecting

The engine guides construct a `RoomClient` instead of awaiting
`connect`, so that their listeners are in place before the first state
update arrives:

```ts
const room = new RoomClient({ router, project: "my-game", room: roomId, schema });
room.entities.onEnter(Runner, (r) => addSprite(r));
room.on("closed", (e) => showError(e));
await room.ready;
```

`connect` resolves only after the first full state update has been
applied, and `onEnter` doesn't replay entities that are already there,
so listeners added after `await connect(...)` miss every entity the room
had when the player joined. Either add them before `ready` resolves, as
here, or first walk `room.entities.all(kind)` for what is already there.

`ready` rejects as `connect` does, and `closed` fires either way, so a
`closed` listener is the one place to report a connection that failed or
ended. `call` and `send` throw until `ready` resolves.

| Event | Show |
|---|---|
| `waking` | "Waking the room": the room was hibernated, and the connection waits while it wakes |
| `disconnected` | "Reconnecting"; the client retries by itself |
| `restored` | Clear the message. Every entity has left and entered again |
| `closed` | `error.message`. Reload on 4004, offer a rejoin on 4011, and tell the player they're playing elsewhere on 4012 |

The router address and the room ID come from outside the scene: the
router is `location.origin` under `irt dev` and the region's router once
deployed, and room IDs come from your lobby, through
[createRoom, joinByCode or quickJoin](/docs/reference/client-sdk#http-helpers-for-games-without-a-backend)
or your backend.

## Entities and engine objects

Keep a map from entity ID to engine object. Create the object in
`onEnter`, update what isn't drawn every frame in `onChange`, and
destroy it in `onLeave`.

- On a reconnect or a room restart, every entity leaves and enters again
  as a new object with the same ID. With the map above, that rebuilds
  the scene; don't keep entity objects elsewhere.
- `onChange` doesn't fire for the writable fields of an entity the local
  player owns: the client keeps its own values for those and ignores the
  room's, except for a correction, after which `onCorrect` fires.
- `onEnter`, `onChange` and `onLeave` fire as each state update is
  applied, at the room's tick rate or less, not once per frame. Positions
  belong in the frame loop.

## The frame loop

Draw positions from two sources, each frame:

- **Remote entities**: `others.get(entity)` from
  `room.interpolate(Runner, ["x", "y"])`, which is about 100 ms behind
  the room and moves smoothly between state updates.
- **The local player**: `me.render(["x", "y"])` from `room.predict`,
  which is ahead of the room by the inputs it hasn't heard back about,
  with mispredictions smoothed away. Use `me.entity` for game logic, such as
  whether the player stands on a pickup; it jumps when the room corrects
  it, so don't draw it.

`render` is `NaN` while `find` finds nothing, such as before the room
has created the player's runner. Don't move the object until it's a
number.

`sample` runs once per room tick, not per frame, on timers of its own,
so read input state there (which keys are down) rather than input
events.

## Teardown

When the scene, level or component goes away:

1. Remove the room listeners: each `on`, `onTick` and `onEnter` returns
   a function that removes it. Remove them before `leave()`, which
   emits `closed`, so the handler doesn't touch destroyed objects.
2. `me.stop()` and `await voice.disconnect()`.
3. `room.leave()`. The client doesn't reconnect, and the room hibernates
   30 seconds after its last connection closes.
4. Remove the engine's own listeners: pointer and key handlers on
   `window` outlive the scene.

A prediction and an interpolator have no teardown of their own and live
as long as their `RoomClient`. A game that keeps one connection across
several scenes should create them once per client, not once per scene.

## Common mistakes

- **Adding `onEnter` after `await connect(...)`.** The entities already
  in the room never enter. Construct a `RoomClient` and add listeners
  before `ready`.
- **Drawing `room.entities` values directly.** They change once per
  state update and stutter. Interpolate remote entities and render the
  prediction for the local one.
- **Moving the local player with interpolation, or remote players with
  prediction.** Interpolation draws the local player a round trip late;
  only the local player's entity is predicted.
- **Opening a second client when a scene restarts.** The router closes
  the older connection of a player with 4012, and that one doesn't
  reconnect. Leave the old client first.
- **Sampling input in a key event.** `sample` is called once per room
  tick; read the keys that are held at that moment.

---

# Phaser

> Run an IRT room in a Phaser 3 scene, with predicted movement, interpolated players, owned aim, calls, voice and teardown on shutdown.

This page builds the runners game from
[Engines and frameworks](/docs/integrations/overview) as a Phaser 3
scene. It imports `shared.ts` from that page; read its
[Connecting](/docs/integrations/overview#connecting) and
[Teardown](/docs/integrations/overview#teardown) sections first.

The scene owns one `RoomClient`: it connects in `create`, draws in
`update` and leaves on the scene's `shutdown` event, which Phaser emits
when the scene stops or restarts.

```ts
// arena-scene.ts
import { CloseCode, IrtError, RoomClient } from "@irt/client";
import { joinVoice, type Voice } from "@irt/client/voice";
import Phaser from "phaser";
import { type Input, Runner, schema, stepper, Wallet } from "./shared.js";

const router = location.hostname.endsWith(".irt-serve.com") ? "wss://eu.irt.io" : location.origin;
// Pixels per world unit.
const PX = 32;

interface Sprite {
  body: Phaser.GameObjects.Container;
  nose: Phaser.GameObjects.Rectangle;
}

export class ArenaScene extends Phaser.Scene {
  private roomId = "";
  private draw = () => {};

  constructor() {
    super("arena");
  }

  init(data: { room: string }) {
    this.roomId = data.room;
  }

  create() {
    const room = new RoomClient({ router, project: "my-game", room: this.roomId, schema });
    const sprites = new Map<number, Sprite>();
    const status = this.add.text(8, 8, "connecting");
    const wallet = this.add.text(8, 32, "");
    let voice: Voice | undefined;

    const offs = [
      room.on("waking", () => status.setText("waking the room")),
      room.on("disconnected", () => status.setText("reconnecting")),
      room.on("restored", () => status.setText("")),
      room.on("closed", (e) => {
        if (e.code === CloseCode.SchemaMismatch) location.reload();
        else status.setText(e.message);
      }),
      room.entities.onEnter(Runner, (r) => {
        const color = r.owner === room.player ? 0x4cc9f0 : 0xf72585;
        const nose = this.add.rectangle(0, 0, 18, 4, 0xffffff).setOrigin(0, 0.5).setRotation(r.angle);
        const body = this.add.container(r.x * PX, r.y * PX, [this.add.circle(0, 0, 12, color), nose]);
        sprites.set(r.id, { body, nose });
      }),
      room.entities.onChange(Runner, (r, changed) => {
        if (changed.includes("angle")) sprites.get(r.id)?.nose.setRotation(r.angle);
      }),
      room.entities.onLeave(Runner, (r) => {
        sprites.get(r.id)?.body.destroy();
        sprites.delete(r.id);
      }),
      room.entities.onChange(Wallet, (w) => wallet.setText(`${w.coins} coins`)),
    ];

    const keys = this.input.keyboard!.createCursorKeys();
    const me = room.predict(stepper, {
      find: (r) => [...r.entities.all(Runner)].find((e) => e.owner === r.player),
      sample: (): Input => ({
        dx: (keys.right.isDown ? 1 : 0) - (keys.left.isDown ? 1 : 0),
        dy: (keys.down.isDown ? 1 : 0) - (keys.up.isDown ? 1 : 0),
      }),
    });
    const others = room.interpolate(Runner, ["x", "y"]);

    const aim = (pointer: Phaser.Input.Pointer) => {
      const at = me.render(["x", "y"]);
      for (const r of room.entities.mine(Runner)) {
        r.angle = Math.atan2(pointer.worldY - at.y * PX, pointer.worldX - at.x * PX);
        sprites.get(r.id)?.nose.setRotation(r.angle);
      }
    };
    this.input.on("pointermove", aim);

    this.draw = () => {
      const local = me.render(["x", "y"]);
      for (const r of room.entities.all(Runner)) {
        const at = r.owner === room.player ? local : others.get(r);
        if (!Number.isNaN(at.x)) sprites.get(r.id)?.body.setPosition(at.x * PX, at.y * PX);
      }
    };

    room.ready.then(
      () => {
        status.setText("");
        wallet.setText(`${room.private!.coins} coins`);
        voice = joinVoice(room, {
          position(player) {
            const r = [...room.entities.all(Runner)].find((e) => e.owner === player);
            return r && { x: r.x, y: r.y };
          },
          range: 12,
        });
        this.add.text(8, 56, "[ talk ]").setInteractive().on("pointerdown", () => void voice?.enableMic());
        this.add.text(80, 56, "[ buy dash ]").setInteractive().on("pointerdown", () => void buy());
      },
      // A failed connection has already been reported by the closed listener.
      () => {},
    );

    const buy = async () => {
      try {
        const { coins } = await room.call("buy", { item: "dash" });
        wallet.setText(`${coins} coins`);
      } catch (e) {
        if (e instanceof IrtError) status.setText(e.message);
        else throw e;
      }
    };

    this.events.once(Phaser.Scenes.Events.SHUTDOWN, () => {
      for (const off of offs) off();
      this.input.off("pointermove", aim);
      me.stop();
      void voice?.disconnect();
      room.leave();
      sprites.clear();
      this.draw = () => {};
    });
  }

  update() {
    this.draw();
  }
}
```

Start it with the room ID your lobby picked:

```ts
// main.ts
import Phaser from "phaser";
import { ArenaScene } from "./arena-scene.js";

const game = new Phaser.Game({ type: Phaser.AUTO, width: 960, height: 640 });
// Added here rather than in the config, so that it starts with its room ID.
game.scene.add("arena", ArenaScene, true, { room: new URLSearchParams(location.search).get("room") ?? "arena" });
```

How it fits together:

- **`create` is synchronous.** Phaser doesn't wait for a promise from
  `create`, so the scene builds its listeners at once and continues in
  `room.ready.then(...)`. The buttons that call the room appear only
  then, because `call` throws until the client is ready.
- **`update` draws.** It runs every frame, between Phaser's own updates
  and its render. Every runner but the player's is interpolated; the
  player's is predicted.
- **The local nose turns at once.** The aim handler writes `angle` on the
  owned runner and rotates its sprite itself, since `onChange` doesn't
  fire for the player's own writable fields. The client sends the writes
  once per room tick, however often the pointer moves.
- **The wallet is private state.** `room.private` is an entity of the
  schema's private kind, so `onChange(Wallet, ...)` follows it, and the reply to `buy`
  updates the label before the state update arrives.
- **Shutdown undoes `create`.** Phaser destroys the scene's game objects
  itself; the scene removes IRT listeners first, so the `closed` event
  that `leave()` emits doesn't reach a destroyed label.

Browsers pause `requestAnimationFrame`, and with it Phaser's `update`,
in background tabs. The IRT client keeps applying state updates, so the
scene is current when the player comes back.

## Common mistakes

- **An `async create()`.** Phaser calls `update` before the promise
  settles, and an error in it is lost. Keep `create` synchronous.
- **Destroying game objects in `onLeave` after shutdown.** Remove the
  room listeners in the shutdown handler, before `leave()`.
- **Reading pointer input in `sample`.** Aim isn't an input: it's a
  writable field, so write it from the pointer event and keep `sample`
  for what the stepper simulates.
- **No shutdown handler.** `scene.restart()` then opens a second client
  as the same player, and the router closes the first with 4012 while
  its listeners still draw into the old scene.

---

# PixiJS

> Draw an IRT room with PixiJS 8, with predicted movement, interpolated players, owned aim, calls and teardown.

This page builds the runners game from
[Engines and frameworks](/docs/integrations/overview) with PixiJS 8. It
imports `shared.ts` from that page; read its
[Connecting](/docs/integrations/overview#connecting) and
[Teardown](/docs/integrations/overview#teardown) sections first.

PixiJS is a renderer, not a framework, so the arena is a function: it
takes an initialized `Application` and a room ID, adds a layer to the
stage, and returns a function that removes everything it added.

```ts
// arena.ts
import { CloseCode, RoomClient } from "@irt/client";
import { type Application, Container, type FederatedPointerEvent, Graphics } from "pixi.js";
import { type Input, Runner, schema, stepper } from "./shared.js";

const router = location.hostname.endsWith(".irt-serve.com") ? "wss://eu.irt.io" : location.origin;
// Pixels per world unit.
const PX = 32;

interface Sprite {
  body: Container;
  nose: Graphics;
}

export function startArena(app: Application, roomId: string, show: (status: string) => void) {
  const room = new RoomClient({ router, project: "my-game", room: roomId, schema });
  const layer = app.stage.addChild(new Container());
  const sprites = new Map<number, Sprite>();
  show("connecting");

  const offs = [
    room.on("waking", () => show("waking the room")),
    room.on("disconnected", () => show("reconnecting")),
    room.on("restored", () => show("")),
    room.on("closed", (e) => {
      if (e.code === CloseCode.SchemaMismatch) location.reload();
      else show(e.message);
    }),
    room.entities.onEnter(Runner, (r) => {
      const body = layer.addChild(new Container());
      body.addChild(new Graphics().circle(0, 0, 12).fill(r.owner === room.player ? 0x4cc9f0 : 0xf72585));
      const nose = body.addChild(new Graphics().rect(0, -2, 18, 4).fill(0xffffff));
      nose.rotation = r.angle;
      body.position.set(r.x * PX, r.y * PX);
      sprites.set(r.id, { body, nose });
    }),
    room.entities.onChange(Runner, (r, changed) => {
      const sprite = sprites.get(r.id);
      if (sprite && changed.includes("angle")) sprite.nose.rotation = r.angle;
    }),
    room.entities.onLeave(Runner, (r) => {
      sprites.get(r.id)?.body.destroy({ children: true });
      sprites.delete(r.id);
    }),
  ];

  const keys = new Set<string>();
  const down = (e: KeyboardEvent) => keys.add(e.key);
  const up = (e: KeyboardEvent) => keys.delete(e.key);
  addEventListener("keydown", down);
  addEventListener("keyup", up);

  const me = room.predict(stepper, {
    find: (r) => [...r.entities.all(Runner)].find((e) => e.owner === r.player),
    sample: (): Input => ({
      dx: (keys.has("ArrowRight") ? 1 : 0) - (keys.has("ArrowLeft") ? 1 : 0),
      dy: (keys.has("ArrowDown") ? 1 : 0) - (keys.has("ArrowUp") ? 1 : 0),
    }),
  });
  const others = room.interpolate(Runner, ["x", "y"]);

  app.stage.eventMode = "static";
  app.stage.hitArea = app.screen;
  const aim = (e: FederatedPointerEvent) => {
    const at = me.render(["x", "y"]);
    for (const r of room.entities.mine(Runner)) {
      r.angle = Math.atan2(e.global.y - at.y * PX, e.global.x - at.x * PX);
      const sprite = sprites.get(r.id);
      if (sprite) sprite.nose.rotation = r.angle;
    }
  };
  app.stage.on("pointermove", aim);

  const frame = () => {
    const local = me.render(["x", "y"]);
    for (const r of room.entities.all(Runner)) {
      const at = r.owner === room.player ? local : others.get(r);
      if (!Number.isNaN(at.x)) sprites.get(r.id)?.body.position.set(at.x * PX, at.y * PX);
    }
  };
  app.ticker.add(frame);

  const stop = () => {
    for (const off of offs) off();
    app.ticker.remove(frame);
    app.stage.off("pointermove", aim);
    removeEventListener("keydown", down);
    removeEventListener("keyup", up);
    me.stop();
    room.leave();
    layer.destroy({ children: true });
    sprites.clear();
  };
  return { room, stop };
}
```

And the page that runs it:

```ts
// main.ts
import { IrtError } from "@irt/client";
import { Application } from "pixi.js";
import { startArena } from "./arena.js";
import { Wallet } from "./shared.js";

const app = new Application();
await app.init({ resizeTo: window, background: "#101418", antialias: true });
document.body.appendChild(app.canvas);

const status = document.querySelector("#status")!;
const coins = document.querySelector("#coins")!;
const buy = document.querySelector<HTMLButtonElement>("#buy")!;

const arena = startArena(app, new URLSearchParams(location.search).get("room") ?? "arena", (s) => (status.textContent = s));
document.querySelector("#leave")!.addEventListener("click", arena.stop);
arena.room.entities.onChange(Wallet, (w) => (coins.textContent = `${w.coins} coins`));

buy.addEventListener("click", async () => {
  try {
    const reply = await arena.room.call("buy", { item: "dash" });
    coins.textContent = `${reply.coins} coins`;
  } catch (e) {
    if (e instanceof IrtError) status.textContent = e.message;
    else throw e;
  }
});

arena.room.ready.then(
  () => {
    buy.disabled = false;
    coins.textContent = `${arena.room.private!.coins} coins`;
  },
  // The closed listener in startArena has reported it.
  () => {},
);
```

How it fits together:

- **Listeners before `ready`.** `startArena` returns as soon as the
  client is constructed, with every listener in place, so the runners
  already in the room enter as sprites. The buy button stays disabled
  until `ready` resolves, because `call` throws before then.
- **The ticker draws.** `app.ticker` runs once per animation frame; the
  frame callback places every runner from the prediction or the
  interpolator. `onEnter` places a new sprite at the entity's current
  position, so it doesn't flash at the origin for a frame.
- **Aim is written, not sampled.** The stage gets pointer events only
  with `eventMode = "static"` and a `hitArea`, here the whole screen.
  The handler writes the owned runner's `angle` and turns its nose at
  once; other clients see it through `onChange`.
- **Teardown.** `stop` removes the IRT listeners first, then the ticker
  callback, the pointer and key handlers, then leaves the room and
  destroys the layer with its children. It leaves the `Application`
  alone, since the arena didn't create it.

Voice works the same in every engine; see the
[Phaser guide](/docs/integrations/phaser) for `joinVoice` with a talk
button and [Proximity voice](/docs/guides/proximity-voice) for the
details.

## Common mistakes

- **Destroying a sprite without `{ children: true }`.** The runner's
  circle and nose stay in memory; PixiJS 8 doesn't destroy children by
  default.
- **Using `app.ticker.deltaMS` to move runners.** Movement comes from
  the room's ticks: the prediction steps at the room's fixed timestep,
  and the interpolator places remote runners by the room's clock. The
  ticker only says when to draw.
- **Pointer events on the stage with no `hitArea`.** An empty part of
  the stage then gets no events, and aim stops when the pointer leaves a
  sprite.

---

# Three.js

> Render an IRT room with Three.js, with predicted movement, interpolated players, aim from a raycast, calls, spatial voice and teardown.

This page builds the runners game from
[Engines and frameworks](/docs/integrations/overview) in 3D with
Three.js. It imports `shared.ts` from that page; read its
[Connecting](/docs/integrations/overview#connecting) and
[Teardown](/docs/integrations/overview#teardown) sections first.

The room's world is flat, in `x` and `y`. The scene puts it on the
ground plane: a runner at room `(x, y)` stands at `(x, 0, y)` in Three.js,
and its `angle` turns it about the vertical axis.

```ts
// arena.ts
import { CloseCode, RoomClient } from "@irt/client";
import { joinVoice } from "@irt/client/voice";
import * as THREE from "three";
import { type Input, Runner, schema, stepper } from "./shared.js";

const router = location.hostname.endsWith(".irt-serve.com") ? "wss://eu.irt.io" : location.origin;

export function startArena(parent: HTMLElement, roomId: string, show: (status: string) => void) {
  const room = new RoomClient({ router, project: "my-game", room: roomId, schema });

  const renderer = new THREE.WebGLRenderer({ antialias: true });
  renderer.setSize(parent.clientWidth, parent.clientHeight);
  parent.appendChild(renderer.domElement);
  const scene = new THREE.Scene();
  const camera = new THREE.PerspectiveCamera(60, parent.clientWidth / parent.clientHeight, 0.1, 500);
  scene.add(new THREE.HemisphereLight(0xffffff, 0x334455, 2));

  const bodyShape = new THREE.CapsuleGeometry(0.4, 0.8);
  const noseShape = new THREE.BoxGeometry(0.5, 0.15, 0.15);
  const materials = {
    mine: new THREE.MeshStandardMaterial({ color: 0x4cc9f0 }),
    theirs: new THREE.MeshStandardMaterial({ color: 0xf72585 }),
    nose: new THREE.MeshStandardMaterial({ color: 0xffffff }),
  };
  const meshes = new Map<number, THREE.Mesh>();
  show("connecting");

  const offs = [
    room.on("waking", () => show("waking the room")),
    room.on("disconnected", () => show("reconnecting")),
    room.on("restored", () => show("")),
    room.on("closed", (e) => {
      if (e.code === CloseCode.SchemaMismatch) location.reload();
      else show(e.message);
    }),
    room.entities.onEnter(Runner, (r) => {
      const mesh = new THREE.Mesh(bodyShape, r.owner === room.player ? materials.mine : materials.theirs);
      const nose = new THREE.Mesh(noseShape, materials.nose);
      nose.position.set(0.5, 0.3, 0);
      mesh.add(nose);
      mesh.position.set(r.x, 0.8, r.y);
      mesh.rotation.y = -r.angle;
      scene.add(mesh);
      meshes.set(r.id, mesh);
    }),
    room.entities.onChange(Runner, (r, changed) => {
      const mesh = meshes.get(r.id);
      if (mesh && changed.includes("angle")) mesh.rotation.y = -r.angle;
    }),
    room.entities.onLeave(Runner, (r) => {
      const mesh = meshes.get(r.id);
      if (mesh) scene.remove(mesh);
      meshes.delete(r.id);
    }),
  ];

  const keys = new Set<string>();
  const down = (e: KeyboardEvent) => keys.add(e.key);
  const up = (e: KeyboardEvent) => keys.delete(e.key);
  addEventListener("keydown", down);
  addEventListener("keyup", up);

  const me = room.predict(stepper, {
    find: (r) => [...r.entities.all(Runner)].find((e) => e.owner === r.player),
    sample: (): Input => ({
      dx: (keys.has("ArrowRight") ? 1 : 0) - (keys.has("ArrowLeft") ? 1 : 0),
      dy: (keys.has("ArrowDown") ? 1 : 0) - (keys.has("ArrowUp") ? 1 : 0),
    }),
  });
  const others = room.interpolate(Runner, ["x", "y"]);

  const ground = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0);
  const raycaster = new THREE.Raycaster();
  const pointer = new THREE.Vector2();
  const hit = new THREE.Vector3();
  const aim = (e: PointerEvent) => {
    const rect = renderer.domElement.getBoundingClientRect();
    pointer.set(((e.clientX - rect.left) / rect.width) * 2 - 1, -((e.clientY - rect.top) / rect.height) * 2 + 1);
    raycaster.setFromCamera(pointer, camera);
    if (!raycaster.ray.intersectPlane(ground, hit)) return;
    const at = me.render(["x", "y"]);
    for (const r of room.entities.mine(Runner)) {
      r.angle = Math.atan2(hit.z - at.y, hit.x - at.x);
      const mesh = meshes.get(r.id);
      if (mesh) mesh.rotation.y = -r.angle;
    }
  };
  renderer.domElement.addEventListener("pointermove", aim);

  const voice = joinVoice(room, {
    position(player) {
      const r = [...room.entities.all(Runner)].find((e) => e.owner === player);
      return r && { x: r.x, y: 0, z: r.y };
    },
    spatial: true,
    range: 20,
  });

  renderer.setAnimationLoop(() => {
    const local = me.render(["x", "y"]);
    for (const r of room.entities.all(Runner)) {
      const at = r.owner === room.player ? local : others.get(r);
      if (!Number.isNaN(at.x)) meshes.get(r.id)?.position.set(at.x, 0.8, at.y);
    }
    if (!Number.isNaN(local.x)) {
      camera.position.set(local.x, 14, local.y + 10);
      camera.lookAt(local.x, 0, local.y);
    }
    renderer.render(scene, camera);
  });

  const stop = async () => {
    for (const off of offs) off();
    renderer.setAnimationLoop(null);
    renderer.domElement.removeEventListener("pointermove", aim);
    removeEventListener("keydown", down);
    removeEventListener("keyup", up);
    me.stop();
    room.leave();
    await voice.disconnect();
    for (const mesh of meshes.values()) scene.remove(mesh);
    meshes.clear();
    bodyShape.dispose();
    noseShape.dispose();
    for (const m of Object.values(materials)) m.dispose();
    renderer.dispose();
    renderer.domElement.remove();
  };
  return { room, voice, stop };
}
```

And the page that runs it, with a talk button and a call:

```ts
// main.ts
import { IrtError } from "@irt/client";
import { startArena } from "./arena.js";

const status = document.querySelector("#status")!;
const arena = startArena(document.querySelector("#game")!, new URLSearchParams(location.search).get("room") ?? "arena", (s) => {
  status.textContent = s;
});

// Browsers grant the microphone only from a user gesture.
document.querySelector("#talk")!.addEventListener("click", () => void arena.voice.enableMic());
document.querySelector("#buy")!.addEventListener("click", async () => {
  if (arena.room.status !== "open") return;
  try {
    const { coins } = await arena.room.call("buy", { item: "dash" });
    status.textContent = `${coins} coins left`;
  } catch (e) {
    if (e instanceof IrtError) status.textContent = e.message;
    else throw e;
  }
});
document.querySelector("#leave")!.addEventListener("click", () => void arena.stop());
```

How it fits together:

- **One animation loop.** `setAnimationLoop` draws every frame: remote
  runners at their interpolated position, the local runner at its
  predicted one, and the camera following the predicted position, so
  the camera never lags the player.
- **Aim from a raycast.** The pointer's ray meets the ground plane, and
  the angle from the predicted position to that point is written to the
  owned runner. The local mesh turns at once; other clients get the new
  `angle` through `onChange`, a state update later.
- **Spatial voice.** `spatial: true` pans speakers with Web Audio. The
  positions given to `joinVoice` are room positions on the Three.js
  axes, `(x, 0, y)`, and the Web Audio listener faces `-z` with `+x` to
  its right, as the camera does, so a speaker on the right of the screen
  is heard on the right.
- **The buy button checks `status`.** `call` throws before the client
  is first ready and rejects while it reconnects, so the button does
  nothing until the room is open.
- **Teardown frees GPU memory.** Removing a mesh from the scene doesn't
  free its geometry or material; the shared ones are disposed once, in
  `stop`, with the renderer.

Resize handling is left out: on resize, set `camera.aspect`, call
`camera.updateProjectionMatrix()` and `renderer.setSize(...)` as in any
Three.js app.

## Common mistakes

- **New geometry and material per runner.** A runner enters again on
  every reconnect, so per-entity GPU resources pile up unless each
  `onLeave` disposes them. Share them, as above.
- **Driving the camera from `me.entity`.** It jumps on every correction;
  `render` smooths them.
- **Mixing up the axes.** The room's `y` is the scene's `z`. Map in one
  place, in both directions: positions, aim and voice.

---

# Babylon.js

> Run an IRT room in a Babylon.js scene, with predicted movement, interpolated players, aim from a pick, calls, spatial voice and teardown with the scene.

This page builds the runners game from
[Engines and frameworks](/docs/integrations/overview) in 3D with
Babylon.js. It imports `shared.ts` from that page; read its
[Connecting](/docs/integrations/overview#connecting) and
[Teardown](/docs/integrations/overview#teardown) sections first.

The room's world is flat, in `x` and `y`; a runner at room `(x, y)`
stands at `(x, 0, y)` in the scene. The room connection belongs to the
`Scene`: it's opened with the scene and closed by the scene's
`onDisposeObservable`, so disposing the scene, as a level change does,
tears down everything.

```ts
// arena.ts
import { CloseCode, RoomClient } from "@irt/client";
import { joinVoice } from "@irt/client/voice";
import { ArcRotateCamera, Engine, HemisphericLight, type Mesh, MeshBuilder, PointerEventTypes, Scene, Vector3 } from "@babylonjs/core";
import { type Input, Runner, schema, stepper } from "./shared.js";

const router = location.hostname.endsWith(".irt-serve.com") ? "wss://eu.irt.io" : location.origin;

export function createArena(engine: Engine, roomId: string, show: (status: string) => void) {
  const scene = new Scene(engine);
  const room = new RoomClient({ router, project: "my-game", room: roomId, schema });
  const camera = new ArcRotateCamera("camera", -Math.PI / 2, Math.PI / 3, 18, Vector3.Zero(), scene);
  new HemisphericLight("light", new Vector3(0, 1, 0), scene);
  const ground = MeshBuilder.CreateGround("ground", { width: 200, height: 200 }, scene);
  const meshes = new Map<number, Mesh>();
  show("connecting");

  const offs = [
    room.on("waking", () => show("waking the room")),
    room.on("disconnected", () => show("reconnecting")),
    room.on("restored", () => show("")),
    room.on("closed", (e) => {
      if (e.code === CloseCode.SchemaMismatch) location.reload();
      else show(e.message);
    }),
    room.entities.onEnter(Runner, (r) => {
      const body = MeshBuilder.CreateCapsule(`runner-${r.id}`, { height: 1.6, radius: 0.4 }, scene);
      const nose = MeshBuilder.CreateBox(`nose-${r.id}`, { width: 0.5, height: 0.15, depth: 0.15 }, scene);
      nose.parent = body;
      nose.position.set(0.5, 0.3, 0);
      body.position.set(r.x, 0.8, r.y);
      body.rotation.y = -r.angle;
      meshes.set(r.id, body);
    }),
    room.entities.onChange(Runner, (r, changed) => {
      const body = meshes.get(r.id);
      if (body && changed.includes("angle")) body.rotation.y = -r.angle;
    }),
    // Disposing a mesh disposes its children, so the nose goes with it.
    room.entities.onLeave(Runner, (r) => {
      meshes.get(r.id)?.dispose();
      meshes.delete(r.id);
    }),
  ];

  const keys = new Set<string>();
  const down = (e: KeyboardEvent) => keys.add(e.key);
  const up = (e: KeyboardEvent) => keys.delete(e.key);
  addEventListener("keydown", down);
  addEventListener("keyup", up);

  const me = room.predict(stepper, {
    find: (r) => [...r.entities.all(Runner)].find((e) => e.owner === r.player),
    sample: (): Input => ({
      dx: (keys.has("ArrowRight") ? 1 : 0) - (keys.has("ArrowLeft") ? 1 : 0),
      dy: (keys.has("ArrowUp") ? 1 : 0) - (keys.has("ArrowDown") ? 1 : 0),
    }),
  });
  const others = room.interpolate(Runner, ["x", "y"]);

  scene.onPointerObservable.add((info) => {
    if (info.type !== PointerEventTypes.POINTERMOVE) return;
    const pick = scene.pick(scene.pointerX, scene.pointerY, (m) => m === ground);
    if (!pick.hit || !pick.pickedPoint) return;
    const at = me.render(["x", "y"]);
    for (const r of room.entities.mine(Runner)) {
      r.angle = Math.atan2(pick.pickedPoint.z - at.y, pick.pickedPoint.x - at.x);
      const body = meshes.get(r.id);
      if (body) body.rotation.y = -r.angle;
    }
  });

  const voice = joinVoice(room, {
    position(player) {
      const r = [...room.entities.all(Runner)].find((e) => e.owner === player);
      return r && { x: r.x, y: 0, z: -r.y };
    },
    spatial: true,
    range: 20,
  });

  scene.onBeforeRenderObservable.add(() => {
    const local = me.render(["x", "y"]);
    for (const r of room.entities.all(Runner)) {
      const at = r.owner === room.player ? local : others.get(r);
      if (!Number.isNaN(at.x)) meshes.get(r.id)?.position.set(at.x, 0.8, at.y);
    }
    if (!Number.isNaN(local.x)) camera.target.set(local.x, 0, local.y);
  });

  scene.onDisposeObservable.addOnce(() => {
    for (const off of offs) off();
    removeEventListener("keydown", down);
    removeEventListener("keyup", up);
    me.stop();
    room.leave();
    void voice.disconnect();
    meshes.clear();
  });

  return { scene, room, voice };
}
```

And the page that runs it:

```ts
// main.ts
import { IrtError } from "@irt/client";
import { Engine } from "@babylonjs/core";
import { createArena } from "./arena.js";

const canvas = document.querySelector<HTMLCanvasElement>("#game")!;
const status = document.querySelector("#status")!;
const engine = new Engine(canvas, true);
const arena = createArena(engine, new URLSearchParams(location.search).get("room") ?? "arena", (s) => {
  status.textContent = s;
});
engine.runRenderLoop(() => arena.scene.render());
addEventListener("resize", () => engine.resize());

// Browsers grant the microphone only from a user gesture.
document.querySelector("#talk")!.addEventListener("click", () => void arena.voice.enableMic());
document.querySelector("#buy")!.addEventListener("click", async () => {
  if (arena.room.status !== "open") return;
  try {
    const { coins } = await arena.room.call("buy", { item: "dash" });
    status.textContent = `${coins} coins left`;
  } catch (e) {
    if (e instanceof IrtError) status.textContent = e.message;
    else throw e;
  }
});
document.querySelector("#leave")!.addEventListener("click", () => {
  engine.stopRenderLoop();
  arena.scene.dispose();
});
```

How it fits together:

- **`onBeforeRenderObservable` is the frame loop.** It runs once per
  frame before the scene renders: remote runners take their
  interpolated position, the local runner its predicted one, and the
  camera's target follows the predicted position.
- **Babylon.js is left-handed.** With `+y` up, `+z` points away from a
  camera at `alpha = -π / 2`, so the room's `+y` is up the screen. The
  arrow keys here send `dy = 1` for up to match; in a right-handed engine
  such as [Three.js](/docs/integrations/three), down is `+y`.
- **Aim from a pick.** `scene.pick` with a predicate that accepts only
  the ground gives the point under the pointer; the angle to it from the
  predicted position is written to the owned runner.
- **Spatial voice.** Web Audio is right-handed, so voice positions flip
  the sign of `z`: a speaker on the right of the screen is heard on the
  right.
- **Teardown follows the scene.** `scene.dispose()` disposes every mesh,
  camera and light, and its `onDisposeObservable` removes the IRT
  listeners, stops the prediction and leaves the room. The observers
  added to the scene's own observables go with the scene.

## Common mistakes

- **Calling `room.leave()` without disposing the scene.** The meshes
  stay in it, frozen, because `onLeave` no longer runs.
- **Using `engine.getDeltaTime()` to move runners.** Movement comes from
  the room's ticks: the prediction steps at the room's fixed timestep
  and the interpolator places remote runners by the room's clock.
- **Picking every mesh for aim.** Without a predicate the pick hits the
  runners themselves, and the aim snaps to the nearest capsule.

---

# React

> Use @irt/client from React with three small hooks, written on this page, for the connection, entity lists and per-tick values, plus a canvas for the game itself.

This page builds the runners game from
[Engines and frameworks](/docs/integrations/overview) with React. It
imports `shared.ts` from that page; read its
[Connecting](/docs/integrations/overview#connecting) and
[Teardown](/docs/integrations/overview#teardown) sections first.

IRT has no React package. The hooks below are short enough to copy into
a project, and they're all a React app needs: one that owns the
connection, and two built on `useSyncExternalStore` that re-render a
component when the room's state changes.

React is for the UI around the game: the connection status, lists of
players, a wallet, buttons. The game world changes dozens of times a
second and is drawn every frame, so draw it imperatively, in a canvas or
an engine, from an effect; don't put positions in React state.

## The hooks

```ts
// hooks.ts
import { type Calls, type ClientEntity, type ConnectionStatus, type ConnectOptions, type IrtError, type Kind, type ReadyRoomClient, RoomClient, type ValuesOf } from "@irt/client";
import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from "react";

/**
 * Connects while the component is mounted. `room` is set once the client holds the room's full
 * state, so `call`, `send`, `state` and `private` are safe to use from then on.
 */
export function useRoom<S extends Kind<any>, P extends Kind<any>, C extends Calls<any>>(opts: ConnectOptions<S, P, C>) {
  const { router, project, room: id, token, schema } = opts;
  const [room, setRoom] = useState<ReadyRoomClient<S, P, C>>();
  const [status, setStatus] = useState<ConnectionStatus>("connecting");
  const [error, setError] = useState<IrtError>();

  useEffect(() => {
    const client = new RoomClient<S, P, C>({ router, project, room: id, token, schema });
    setRoom(undefined);
    setStatus("connecting");
    setError(undefined);
    const offs = [
      client.on("waking", () => setStatus("waking")),
      client.on("disconnected", () => setStatus("reconnecting")),
      client.on("restored", () => setStatus("open")),
      client.on("closed", (e) => {
        setStatus("closed");
        setError(e);
      }),
    ];
    client.ready.then(
      () => {
        setRoom(client as ReadyRoomClient<S, P, C>);
        setStatus("open");
      },
      // The closed listener has set the error.
      () => {},
    );
    return () => {
      for (const off of offs) off();
      client.leave();
    };
  }, [router, project, id, token, schema]);

  return { room, status, error };
}

/**
 * The entities of a kind the client sees. Re-renders when one enters or leaves, and when one
 * of `fields` changes, or any field when `fields` is left out.
 */
export function useEntities<K extends Kind<any>>(
  room: RoomClient<any, any, any> | undefined,
  kind: K,
  fields?: readonly (keyof ValuesOf<K> & string)[],
): readonly ClientEntity<K>[] {
  const key = fields?.join();
  const store = useMemo(() => {
    let snapshot: readonly ClientEntity<K>[] = room ? [...room.entities.all(kind)] : [];
    return {
      subscribe(notify: () => void) {
        if (!room) return () => {};
        let dirty = false;
        const offs = [
          room.entities.onEnter(kind, () => (dirty = true)),
          room.entities.onLeave(kind, () => (dirty = true)),
          room.entities.onChange(kind, (_e, changed) => {
            if (!fields || changed.some((f) => fields.includes(f))) dirty = true;
          }),
          // One snapshot per state update, however many entities it changed.
          room.onTick(() => {
            if (!dirty) return;
            dirty = false;
            snapshot = [...room.entities.all(kind)];
            notify();
          }),
        ];
        // Catches up with updates between the first render and this subscription.
        snapshot = [...room.entities.all(kind)];
        return () => {
          for (const off of offs) off();
        };
      },
      snapshot: () => snapshot,
    };
    // `key` stands for `fields`, which callers usually pass as a new array each render.
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, [room, kind, key]);
  return useSyncExternalStore(store.subscribe, store.snapshot);
}

/**
 * A value read from the room after each state update, such as `(r) => r.private.coins`.
 * `read` must return a primitive or an object that only changes when the value does.
 */
export function useRoomValue<R extends RoomClient<any, any, any>, T>(room: R | undefined, read: (room: R) => T): T | undefined {
  const subscribe = useCallback((notify: () => void) => (room ? room.onTick(notify) : () => {}), [room]);
  return useSyncExternalStore(subscribe, () => (room ? read(room) : undefined));
}
```

- **`useRoom`** owns the client: it connects in an effect and leaves in
  its cleanup, so unmounting the component, or changing the room ID,
  leaves the room. It returns `room` only after `ready`, so children
  never see a client that throws on `call`.
- **`useEntities`** keeps one array per state update, as
  `useSyncExternalStore` needs: the same array until something changes,
  then a new one. The entities in it are the client's own objects, read
  fresh on each render; a component wrapped in `memo` that gets an
  entity as a prop doesn't re-render when its fields change, so pass it
  the fields instead.
- **`useRoomValue`** re-reads after every state update and re-renders
  only when the value differs.

In development, `StrictMode` runs each effect twice: `useRoom` connects,
leaves and connects again. The first client leaves before its
connection has opened, so the router never sees two connections of one
player and closes neither with 4012.

## The app

```tsx
// app.tsx
import { CloseCode, IrtError, type ReadyRoomClient } from "@irt/client";
import { joinVoice, type Voice } from "@irt/client/voice";
import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from "react";
import { useEntities, useRoom, useRoomValue } from "./hooks.js";
import { type Input, type Match, Runner, schema, stepper, type Wallet } from "./shared.js";

type ArenaRoom = ReadyRoomClient<typeof Match, typeof Wallet, typeof schema.calls>;

const router = location.hostname.endsWith(".irt-serve.com") ? "wss://eu.irt.io" : location.origin;
// Pixels per world unit.
const PX = 32;

export function App({ roomId }: { roomId: string }) {
  const { room, status, error } = useRoom({ router, project: "my-game", room: roomId, schema });

  useEffect(() => {
    if (error?.code === CloseCode.SchemaMismatch) location.reload();
  }, [error]);

  if (error) return <p>{error.message}</p>;
  if (!room) return <p>{status === "waking" ? "Waking the room" : "Connecting"}</p>;
  return (
    <>
      {status === "reconnecting" && <p>Reconnecting</p>}
      <Arena room={room} />
      <Coins room={room} />
      <Players room={room} />
      <Talk room={room} />
    </>
  );
}

function Arena({ room }: { room: ArenaRoom }) {
  const canvas = useRef<HTMLCanvasElement>(null);

  useEffect(() => {
    const el = canvas.current!;
    const ctx = el.getContext("2d")!;
    const keys = new Set<string>();
    const down = (e: KeyboardEvent) => keys.add(e.key);
    const up = (e: KeyboardEvent) => keys.delete(e.key);
    addEventListener("keydown", down);
    addEventListener("keyup", up);

    const me = room.predict(stepper, {
      find: (r) => [...r.entities.all(Runner)].find((e) => e.owner === r.player),
      sample: (): Input => ({
        dx: (keys.has("ArrowRight") ? 1 : 0) - (keys.has("ArrowLeft") ? 1 : 0),
        dy: (keys.has("ArrowDown") ? 1 : 0) - (keys.has("ArrowUp") ? 1 : 0),
      }),
    });
    const others = room.interpolate(Runner, ["x", "y"]);

    const aim = (e: PointerEvent) => {
      const at = me.render(["x", "y"]);
      const rect = el.getBoundingClientRect();
      for (const r of room.entities.mine(Runner)) {
        r.angle = Math.atan2(e.clientY - rect.top - at.y * PX, e.clientX - rect.left - at.x * PX);
      }
    };
    el.addEventListener("pointermove", aim);

    let frame = 0;
    const draw = () => {
      ctx.clearRect(0, 0, el.width, el.height);
      const local = me.render(["x", "y"]);
      for (const r of room.entities.all(Runner)) {
        const mine = r.owner === room.player;
        const at = mine ? local : others.get(r);
        if (Number.isNaN(at.x)) continue;
        const x = at.x * PX;
        const y = at.y * PX;
        ctx.fillStyle = mine ? "#4cc9f0" : "#f72585";
        ctx.beginPath();
        ctx.arc(x, y, 12, 0, 2 * Math.PI);
        ctx.fill();
        ctx.strokeStyle = "#fff";
        ctx.beginPath();
        ctx.moveTo(x, y);
        ctx.lineTo(x + Math.cos(r.angle) * 20, y + Math.sin(r.angle) * 20);
        ctx.stroke();
      }
      frame = requestAnimationFrame(draw);
    };
    frame = requestAnimationFrame(draw);

    return () => {
      cancelAnimationFrame(frame);
      el.removeEventListener("pointermove", aim);
      removeEventListener("keydown", down);
      removeEventListener("keyup", up);
      me.stop();
    };
  }, [room]);

  return <canvas ref={canvas} width={960} height={640} />;
}

function Coins({ room }: { room: ArenaRoom }) {
  const coins = useRoomValue(room, (r) => r.private.coins);
  const [message, setMessage] = useState("");

  async function buy() {
    try {
      await room.call("buy", { item: "dash" });
      setMessage("");
    } catch (e) {
      if (e instanceof IrtError) setMessage(e.message);
      else throw e;
    }
  }

  return (
    <p>
      {coins} coins <button onClick={() => void buy()}>Buy a dash</button> {message}
    </p>
  );
}

function Players({ room }: { room: ArenaRoom }) {
  const runners = useEntities(room, Runner, ["owner"]);
  return (
    <ul>
      {runners.map((r) => (
        <li key={r.id}>{r.owner === room.player ? `${r.owner} (you)` : r.owner}</li>
      ))}
    </ul>
  );
}

function Talk({ room }: { room: ArenaRoom }) {
  const [voice, setVoice] = useState<Voice>();
  const subscribe = useCallback((notify: () => void) => room.on("peers", notify), [room]);
  const speakers = useSyncExternalStore(subscribe, () => room.peers.speakers);

  useEffect(() => {
    const v = joinVoice(room, {
      position(player) {
        const r = [...room.entities.all(Runner)].find((e) => e.owner === player);
        return r && { x: r.x, y: r.y };
      },
      range: 12,
    });
    setVoice(v);
    return () => void v.disconnect();
  }, [room]);

  return (
    <p>
      <button onClick={() => void voice?.enableMic()}>Talk</button> Hearing: {speakers.join(", ") || "no one"}
    </p>
  );
}
```

```tsx
// main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { App } from "./app.js";

createRoot(document.querySelector("#root")!).render(
  <StrictMode>
    <App roomId={new URLSearchParams(location.search).get("room") ?? "arena"} />
  </StrictMode>,
);
```

How it fits together:

- **`App` renders by connection state.** Until `useRoom` returns a
  room, it shows connecting or waking; after a `closed` it shows the
  error, and reloads on 4004. Reconnects keep the room, so the game stays
  mounted with a banner on top.
- **`Arena` draws in an effect.** The prediction, the interpolator, the
  input handlers and the animation frame are created when it mounts and
  stopped in its cleanup. Nothing in it sets React state, so the canvas
  redraws every frame without a single re-render.
- **Aim writes the owned runner.** The pointer handler sets `angle` on
  `entities.mine(Runner)`, and the draw loop reads it back from the
  entity: the client keeps the owner's value, so the local aim line
  turns at once.
- **`Coins` re-renders once per change.** `useRoomValue` reads
  `room.private.coins` after each state update; the buy call's reply
  isn't needed for the label, since the room's change to the wallet
  arrives with the next state update.
- **`Players` ignores movement.** With `["owner"]`, it re-renders when a
  runner enters or leaves, not 30 times a second as runners move.
- **`Talk` owns the voice.** It joins in an effect and disconnects in
  the cleanup, and `room.peers.speakers` is a new array only when the
  room changes who this player hears, so it works as a snapshot as is.

An interpolator lives as long as its `RoomClient`, so each mount of
`Arena` adds one. That's harmless for a component that mounts once per
room; one that mounts and unmounts often should get its interpolator
from the component that calls `useRoom`.

## Common mistakes

- **Positions in React state.** Setting state on every state update
  re-renders 30 times a second and still stutters, because it isn't
  interpolated. Draw from the frame loop.
- **Creating the client in `useMemo` or during render.** React may call
  either twice and drop one result, leaving a connected client nobody
  leaves. Create it in an effect, as `useRoom` does.
- **Creating a prediction in `useMemo`.** The same goes for `predict`:
  a dropped one keeps sampling and sending inputs. Create it in an
  effect and `stop()` it in the cleanup.
- **A new array from `getSnapshot` on every call.**
  `useSyncExternalStore` then re-renders forever. Return the same array
  until something changed, as `useEntities` does.
- **Passing an object literal to `useRoom` with a new schema each
  render.** The effect depends on the schema; import it from the shared
  module so it stays the same object.

---

# Migrating from Colyseus

> Port a Colyseus 0.16 project to IRT, with a concept map, a small game ported side by side, what has no equivalent and a checklist that ends in tests.

Colyseus and IRT have the same shape: authoritative room code that the
framework runs, state synced to clients as binary patches, and a client SDK that
joins rooms. Most of a port is mechanical. The differences that take
thought are that IRT rooms hibernate and wake, so state lives in synced
entities rather than in fields of a class, and that IRT has no matchmaker
you program: rooms are found by ID, join code, the public list or quick
join.

There is no compatibility layer. IRT doesn't run Colyseus room classes or
speak the Colyseus client protocol, and isn't planning to: Colyseus
expects long-running processes that share a matchmaker and a presence
store, which rooms that hibernate and wake in any room host don't fit.
You rewrite the room against `@irt/room` and the client against
`@irt/client`. Game logic carries over nearly line for line.

This page describes Colyseus 0.16 with `@colyseus/schema` 3.

## Concept map

| Colyseus | IRT |
|---|---|
| `class MyRoom extends Room`, registered with `gameServer.define("name", MyRoom)` | `export default defineRoom({...})` in a room module, named in `irt.config.ts`'s `rooms` as `name: "src/my-room.ts"`, a [room type](/docs/cli#room-types) |
| `onCreate(options)` | `onCreate(room)`, once in a room's life. It gets no options; see [Create and join options](#what-has-no-direct-equivalent) |
| `onAuth` | [Player tokens](/docs/player-tokens) your backend signs, checked by the router before the room sees the connection, or guests |
| `onJoin(client, options, auth)` | `onJoin(room, conn)`. Runs on every reconnect too. `conn.player` is the player, `conn.meta` the token's `meta` claim |
| `onLeave(client, consented)` and `allowReconnection` | `onLeave(room, conn)`. Clients reconnect by themselves and come back as the same `conn.player`, so key anything that should survive by player |
| `onDispose` | `onHibernate`. An empty room saves its room state and wakes on the next connect; `rooms.retention` decides when it's deleted |
| `client.sessionId` | `conn.player`, stable across reconnects and reloads. `conn.id` is per connection |
| `client.userData` | `conn.data`, not saved |
| A `Schema` class as the room's `state` | `defineSchema({ state, private, entities })`: a shared state entity, per-player private state, and entity kinds |
| `MapSchema<Player>` keyed by session ID | Entities of a `Player` kind with an `owner` field, or owned by the player |
| `@view()` and `StateView` | [Interest](/docs/guides/state-sync#interest) for what each connection sees, and private state for per-player data |
| `this.onMessage("type", handler)` | One `onMessage(room, conn, message)` hook; switch on a `type` field of your own |
| `client.send("type", msg)`, `this.broadcast("type", msg, { except })` | `room.send(conn, msg)`, `room.broadcast(msg, { except })` |
| A message and a reply message you match up | [Calls](/docs/guides/calls): `room.call(name, args)` resolves to the handler's return value |
| `setSimulationInterval` and `setPatchRate` | `tickRate` and `onTick(room, dt)`. Changes go out once per tick |
| `this.clock.setTimeout` | Store the tick something happens at in `room.state` and check it in `onTick`; it survives hibernation |
| `client.joinOrCreate(name, options)` with `filterBy` and `maxClients` | [`quickJoin`](/docs/reference/client-sdk#http-helpers-for-games-without-a-backend) with `type: name`, `meta` and `maxPlayers`, then `connect` with the same `type` |
| `client.create`, `client.joinById` | `createRoom`, then `connect({ room: id })` |
| Room listing, `LobbyRoom` | `listPublic` |
| `setMetadata` | `meta` given to `createRoom`, fixed at creation |
| `this.lock()`, `maxClients` | `maxPlayers`, or `room.kick(conn)` from `onJoin` |
| `getStateCallbacks(room)` with `onAdd`, `listen`, `onRemove` | `room.entities.onEnter`, `onChange`, `onLeave` |
| `room.reconnect(token)` | Automatic |
| `@colyseus/testing` | [`@irt/testing`](/docs/guides/testing) |

## A game, ported

A coin chase: players move around a 100 by 100 board, and whoever reaches
the coin scores and moves it. Players pick a name when they join, and
someone who drops has 20 seconds to come back with their score.

### In Colyseus

```ts
// src/rooms/CoinRoom.ts (Colyseus 0.16)
import { Client, Room } from "colyseus";
import { MapSchema, Schema, type } from "@colyseus/schema";

export class Player extends Schema {
  @type("string") name = "";
  @type("number") x = 10;
  @type("number") y = 10;
  @type("number") score = 0;
}

export class CoinState extends Schema {
  @type({ map: Player }) players = new MapSchema<Player>();
  @type("number") coinX = 50;
  @type("number") coinY = 50;
}

export class CoinRoom extends Room<CoinState> {
  maxClients = 8;
  state = new CoinState();

  onCreate(options: { mode: string }) {
    this.setMetadata({ mode: options.mode });
    this.onMessage("move", (client, { dx, dy }) => {
      const p = this.state.players.get(client.sessionId);
      if (!p) return;
      p.x = Math.min(100, Math.max(0, p.x + Math.sign(dx) * 2));
      p.y = Math.min(100, Math.max(0, p.y + Math.sign(dy) * 2));
      if (Math.hypot(p.x - this.state.coinX, p.y - this.state.coinY) < 3) {
        p.score += 1;
        this.state.coinX = Math.random() * 100;
        this.state.coinY = Math.random() * 100;
        this.broadcast("collected", { by: client.sessionId });
      }
    });
  }

  onJoin(client: Client, options: { name?: string }) {
    this.state.players.set(client.sessionId, new Player().assign({ name: options.name ?? "anon" }));
  }

  async onLeave(client: Client, consented: boolean) {
    if (!consented) {
      try {
        await this.allowReconnection(client, 20);
        return;
      } catch {}
    }
    this.state.players.delete(client.sessionId);
  }
}

// app.config.ts
gameServer.define("coins", CoinRoom).filterBy(["mode"]);
```

```ts
// client.ts (colyseus.js 0.16)
import { Client, getStateCallbacks } from "colyseus.js";

const client = new Client("wss://coins.example.com");
const room = await client.joinOrCreate<CoinState>("coins", { mode: "classic", name: "Alice" });
const $ = getStateCallbacks(room);

$(room.state).players.onAdd((player, sessionId) => {
  $(player).onChange(() => draw(sessionId, player.x, player.y));
});
$(room.state).players.onRemove((_player, sessionId) => erase(sessionId));
room.onMessage("collected", ({ by }) => console.log(by, "scored"));

addEventListener("keydown", (e) => {
  if (e.key === "ArrowRight") room.send("move", { dx: 1, dy: 0 });
});
```

### In IRT

The schema module is shared by the room and its clients, in place of
`@type` decorators that both sides compile:

```ts
// schema.ts
import { defineSchema, entity } from "@irt/room";

export const Player = entity("player", { owner: "string", x: "f32", y: "f32", score: "u16" });
export const Board = entity("board", { coinX: "f32", coinY: "f32" });

export const schema = defineSchema({ state: Board, entities: [Player] });
```

The room. Names go into [presence](/docs/guides/presence), which every
room has, rather than onto the player entity. `allowReconnection` has
no counterpart because the client reconnects by itself, so the room
keeps a player's entity until their presence entry leaves, 10 seconds
after their last connection closed:

```ts
// room.ts
import { defineRoom, type RoomEntity } from "@irt/room";
import { Player, schema } from "./schema.js";

const clamp = (v: number) => Math.min(100, Math.max(0, v));

export default defineRoom({
  schema,
  onCreate(room) {
    room.state.coinX = 50;
    room.state.coinY = 50;
  },
  onJoin(room, conn) {
    // A reconnecting player finds the entity it had.
    const existing = [...room.entities.all(Player)].find((p) => p.owner === conn.player);
    conn.data.player = existing ?? room.entities.create(Player, { owner: conn.player, x: 10, y: 10 });
  },
  onMessage(room, conn, message) {
    const m = message as { type?: unknown; name?: unknown; dx?: unknown; dy?: unknown } | null;
    if (m?.type === "name" && typeof m.name === "string") {
      room.presence.set(conn.player, { name: m.name.slice(0, 64) });
      return;
    }
    if (m?.type !== "move" || typeof m.dx !== "number" || typeof m.dy !== "number") return;
    const p = conn.data.player as RoomEntity<typeof Player>;
    p.x = clamp(p.x + Math.sign(m.dx) * 2);
    p.y = clamp(p.y + Math.sign(m.dy) * 2);
    if (Math.hypot(p.x - room.state.coinX, p.y - room.state.coinY) < 3) {
      p.score += 1;
      room.state.coinX = Math.random() * 100;
      room.state.coinY = Math.random() * 100;
      room.broadcast({ type: "collected", by: conn.player });
    }
  },
  onTick(room) {
    const gone = [...room.entities.all(Player)].filter((p) => !room.presence.get(p.owner));
    for (const p of gone) room.entities.delete(p);
  },
});
```

The client. `joinOrCreate` with `filterBy(["mode"])` and `maxClients`
becomes `quickJoin`, which needs `players.quickJoin` on in
`irt.config.ts`:

```ts
// client.ts
import { connect, quickJoin } from "@irt/client";
import { Player, schema } from "./schema.js";

const router = location.hostname.endsWith(".irt-serve.com") ? "wss://eu.irt.io" : location.origin;
const project = "coins";

function draw(owner: string, x: number, y: number) {
  console.log("draw", owner, x, y);
}
function erase(owner: string) {
  console.log("erase", owner);
}

const { id } = await quickJoin({ router, project, meta: { mode: "classic" }, maxPlayers: 8 });
const room = await connect({ router, project, room: id, schema });
room.send({ type: "name", name: "Alice" });

for (const p of room.entities.all(Player)) draw(p.owner, p.x, p.y);
room.entities.onEnter(Player, (p) => draw(p.owner, p.x, p.y));
room.entities.onChange(Player, (p) => draw(p.owner, p.x, p.y));
room.entities.onLeave(Player, (p) => erase(p.owner));
room.on("message", (m) => console.log("message", m));

addEventListener("keydown", (e) => {
  if (e.key === "ArrowRight") room.send({ type: "move", dx: 1, dy: 0 });
});
```

`connect` resolves with the full state applied, and `onEnter` doesn't
replay it, which is why the loop over `all(Player)` comes first. For
movement that feels instant, replace the `move` message with a
[stepper and prediction](/docs/guides/prediction) once the port works.

### Its tests

```ts
// room.test.ts
import { testRoom } from "@irt/testing";
import { expect, test } from "vitest";
import room from "./room.js";
import { Player } from "./schema.js";

test("reaching the coin scores and tells everyone", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  const bob = await t.connect({ player: "bob" });
  t.live.state.coinX = 12;
  t.live.state.coinY = 10;

  alice.send({ type: "move", dx: 1, dy: 0 });
  await t.host.tick();
  bob.expectMessage({ type: "collected", by: "alice" });
  expect(bob.view(Player).find((p) => p.owner === "alice")).toMatchObject({ x: 12, score: 1 });
});

test("a dropped player keeps their score, and a player who left is removed", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  const bob = await t.connect({ player: "bob" });
  t.live.state.coinX = 12;
  t.live.state.coinY = 10;
  alice.send({ type: "move", dx: 1, dy: 0 });
  await t.host.tick();

  alice.drop();
  await alice.reconnected();
  expect(alice.view(Player)).toEqual(expect.arrayContaining([expect.objectContaining({ owner: "alice", score: 1 })]));

  await alice.leave();
  await t.host.advance(11_000);
  expect(bob.view(Player).map((p) => p.owner)).toEqual(["bob"]);
});
```

## What has no direct equivalent

**`filterBy` on any option, and custom matchmaking.** `quickJoin` picks
the fullest public room whose `meta` has equal values for every top-level
key you pass, or creates one. That covers `filterBy` on a few fixed
options with `sortBy({ clients: -1 })`. Anything more, such as skill
ranges, parties, queues or `matchMaker.reserveSeatFor`, belongs in your
backend: it lists rooms with `GET /projects/{p}/rooms`, creates them with
`POST /projects/{p}/rooms` and signs a [player token](/docs/player-tokens)
whose `room` claim limits the player to the room it chose. The token is
the seat reservation.

**Create and join options.** Rooms get no options on create or join.
What a player brings, such as a name or a team chosen on your site, goes
in a message or call after joining, or, if the room shouldn't trust the
client, in the `meta` claim of a token your backend signs. What a room is
set up with goes in its room ID, which you choose with `createRoom({ id })`,
or in an `onRequest` message from your backend before players arrive.
`createRoom`'s `meta` is for `listPublic` and `quickJoin` to read; the
room itself doesn't see it.

**Several room types.** Each `gameServer.define` becomes a
[room type](/docs/cli#room-types) in `irt.config.ts`'s `rooms`, with its
own module, schema and migrations. A room's type is fixed when it's
created; clients name it with `type` in `connect`, `createRoom`,
`quickJoin` and `listPublic`, and a client of the wrong type is closed
with 4015. Unlike Colyseus, a type isn't chosen by the room ID: a room ID
names one room, whatever its type.

**Presence and cross-room messages.** Colyseus's presence store lets
rooms and processes publish to each other. IRT rooms don't message each
other. A backend sends a message into any room with
`POST /projects/{p}/rooms/{id}/messages`, which the room answers in
`onRequest`, and hears about rooms through [webhooks](/docs/webhooks).
IRT's presence is something else: the list of players in one room.

**Nested schemas and collections.** Entity fields are flat scalars,
strings, bytes and JSON. A `MapSchema` or `ArraySchema` of schemas
becomes an entity kind; a small nested value becomes a `json` field,
which is sent whole when it changes.

**Long-lived room objects.** A Colyseus room is an object that lives
until it's disposed, so fields on `this` are safe. An IRT room
hibernates when it empties and may wake in another room host, so only
entities, `room.state`, private state and the tick come back. `conn.data`,
`room.data` and module variables don't: see
[Where player data lives](/docs/guides/state-sync#where-player-data-lives).

**HTTP routes beside rooms.** IRT rooms don't serve HTTP. Express routes
that ran in the Colyseus process move to your backend, which reaches
rooms through the [HTTP API](/docs/http-api). A game with no routes
needs no backend at all; see [Games without a backend](/docs/no-backend).

**Clients outside TypeScript.** `@irt/client` runs in browsers and Node.
There are no Unity, Defold or Haxe clients.

## Checklist

1. Write `schema.ts`: each `Schema` class becomes an `entity(...)` kind,
   the root state becomes `state`, per-player secrets become `private`.
   Import it from both the room and the client.
2. Move each `onMessage` handler into the one `onMessage` hook, and
   validate every field: the types in your code are the client's
   promise, not the room's guarantee.
3. Turn messages that expect a reply message into [calls](/docs/guides/calls).
4. Replace `setSimulationInterval` with `tickRate` and `onTick`, and
   `clock` timers with tick numbers kept in `room.state`.
5. Key players by `conn.player`, and in `onJoin` reuse the entity a
   player already has; after a crash it's still there.
6. Decide what each piece of per-room data is: synced state in entities,
   per-player data in private state, a derived cache in `room.data`
   rebuilt in `onCreate` and `onWake`.
7. Replace `joinOrCreate`, `create` and `joinById` with `quickJoin`,
   `createRoom`, `joinByCode` and `connect`, and set the matching
   `players.*` settings in `irt.config.ts`.
8. Move `onAuth` to your backend as signed player tokens, or allow guests.
9. Write tests with `@irt/testing` for joining, each message, a dropped
   connection, a crash (`t.host.crash()`) and a hibernation
   (`t.hibernate()`). The [testing guide](/docs/guides/testing) has a
   pattern for each.
10. Run it with `npx irt dev`, check rooms in the
    [inspector](/docs/dev-tools), then `npx irt deploy`.

---

# Migrating from Playroom Kit

> Port a Playroom Kit game to IRT, moving host-player logic and client-written state into a room, with a concept map, a game ported side by side and a checklist that ends in tests.

A Playroom Kit game has no server code. Every player's browser writes
its own state, and one player, the host, runs the logic everyone else
trusts. On IRT that logic moves into a **room**: room code you write in
TypeScript, which runs on IRT's machines, owns the game state and checks
everything clients send. Players still write some values straight from
the client, such as their position or cursor, but only the fields you
declare writable on entities they own, and the room checks each write.

There is no compatibility layer: IRT doesn't implement `insertCoin`,
`myPlayer` or `RPC`, and Playroom code doesn't run on it unchanged. The
port is mostly moving the code inside `if (isHost())` into a room
module and replacing state keys with typed entities.

## Concept map

| Playroom Kit | IRT |
|---|---|
| `insertCoin(options)` | `connect({ router, project, room, schema })`, after finding a room with `createRoom`, `joinByCode`, `listPublic` or `quickJoin`. IRT draws no lobby screen |
| The code the lobby screen shows | `createRoom({ joinCode: true })` returns a 6-character code; `joinByCode` turns it into a room ID |
| `skipLobby` and a random room | [`quickJoin`](/docs/reference/client-sdk#http-helpers-for-games-without-a-backend) |
| `maxPlayersPerRoom` | `maxPlayers` on `createRoom` or `quickJoin` |
| The host player, `isHost()` | None. The room runs the logic, so the host's branches become room code |
| `setState(key, value)` and `getState(key)` | Fields of `room.state`, which only the room writes and every client reads |
| `player.setState(key, value)` | A [writable field](/docs/guides/ownership) of an entity the player owns: `entity.x = 5` on the client, checked by `onWrite` in the room |
| State only one player should see | [Private state](/docs/guides/state-sync#shared-private-and-entity-state): `room.private(conn)` in the room, `room.private` on the client |
| `myPlayer()`, `me()` | `room.player` for the ID, `room.entities.mine(kind)` for the entities it owns |
| `onPlayerJoin(cb)` and `player.onQuit(cb)` | `room.presence.onJoin` and `onLeave` on the client; `onJoin` and `onLeave` hooks in the room |
| `player.getProfile()` | [Presence](/docs/guides/presence) gives each player a `name` the room sets and a `status` the player sets. Colors and avatars are yours |
| `RPC.register` and `RPC.call(name, data, RPC.Mode.HOST)` with a reply | [Calls](/docs/guides/calls): a handler in the room, `await room.call(name, args)` on the client |
| `RPC.call` with `RPC.Mode.ALL` or `OTHERS` | `room.send(msg)` to the room, which forwards it with `room.broadcast(msg, { except })` |
| `waitForState(key)` | `connect` resolves with the full state applied; `room.entities.onChange` for later changes |
| React hooks such as `usePlayersList` and `useMultiplayerState` | Connect in an effect and read the client; see [React](/docs/integrations/react) |
| Playroom's hosted relay | IRT hosts the rooms, and can host the site too, at `<project>.irt-serve.com` |

## A game, ported

A coin chase: players move around a 100 by 100 board, and whoever reaches
the coin scores and moves it. Players can wave at each other and set a
display name.

### In Playroom Kit

Each client moves its own player. The host checks pickups and moves the
coin:

```js
// main.js
import { getState, insertCoin, isHost, myPlayer, onPlayerJoin, RPC, setState } from "playroomkit";

await insertCoin({ maxPlayersPerRoom: 8 });

const players = [];
onPlayerJoin((player) => {
  players.push(player);
  player.onQuit(() => players.splice(players.indexOf(player), 1));
});

RPC.register("wave", async (data, caller) => showWave(caller.id));

if (isHost()) setState("coin", { x: 50, y: 50 }, true);

function frame() {
  const me = myPlayer();
  const pos = me.getState("pos") ?? { x: 10, y: 10 };
  if (keys.has("ArrowRight")) pos.x = Math.min(100, pos.x + 1);
  me.setState("pos", pos);

  if (isHost()) {
    const coin = getState("coin");
    for (const p of players) {
      const at = p.getState("pos");
      if (at && Math.hypot(at.x - coin.x, at.y - coin.y) < 3) {
        p.setState("score", (p.getState("score") ?? 0) + 1, true);
        setState("coin", { x: Math.random() * 100, y: Math.random() * 100 }, true);
      }
    }
  }
  for (const p of players) draw(p.id, p.getState("pos"), p.getProfile().name);
  requestAnimationFrame(frame);
}
frame();

document.querySelector("#wave").onclick = () => RPC.call("wave", {}, RPC.Mode.OTHERS);
```

Any client can write any of these keys, so a modified client can teleport
or award itself points, and the game is only as fair as the host's
browser.

### In IRT

The schema, shared by room and client. The player's position stays
client-written, as `writable` fields of an entity the player owns; the
score stays the room's:

```ts
// schema.ts
import { defineCalls, defineSchema, entity } from "@irt/room";

export const Player = entity("player", { x: "f32", y: "f32", score: "u16" }, { writable: ["x", "y"] });
export const Board = entity("board", { coinX: "f32", coinY: "f32" });

export const schema = defineSchema({
  state: Board,
  entities: [Player],
  calls: defineCalls<{ rename(args: { name: string }): string }>({
    rename(raw) {
      const name = (raw as { name?: unknown } | null)?.name;
      if (typeof name !== "string" || name.trim() === "") throw new Error("name must be a non-empty string");
      return { name };
    },
  }),
});
```

The room holds what the host did, and checks each position a client
writes: at most 3 units a tick, and on the board.

```ts
// room.ts
import { defineRoom, type RoomEntity } from "@irt/room";
import { Board, Player, schema } from "./schema.js";

const MAX_STEP = 3;

function toward(from: number, to: unknown): number {
  if (typeof to !== "number" || !Number.isFinite(to)) return from;
  const step = Math.min(MAX_STEP, Math.max(-MAX_STEP, to - from));
  return Math.min(100, Math.max(0, from + step));
}

export default defineRoom({
  schema,
  onCreate(room) {
    room.state.coinX = 50;
    room.state.coinY = 50;
  },
  onJoin(room, conn) {
    if ([...room.entities.ownedBy(conn.player, Player)].length > 0) return;
    room.entities.create(Player, { x: 10, y: 10 }, { owner: conn.player });
  },
  onWrite(room, conn, entity, next) {
    if (entity.kind !== Player) return undefined;
    const p = entity as RoomEntity<typeof Player>;
    return { x: toward(p.x, next.x ?? p.x), y: toward(p.y, next.y ?? p.y) };
  },
  onTick(room) {
    const board: RoomEntity<typeof Board> = room.state;
    for (const p of room.entities.all(Player)) {
      if (Math.hypot(p.x - board.coinX, p.y - board.coinY) >= 3) continue;
      p.score += 1;
      board.coinX = Math.random() * 100;
      board.coinY = Math.random() * 100;
    }
  },
  onMessage(room, conn, message) {
    if ((message as { type?: unknown } | null)?.type === "wave") {
      room.broadcast({ type: "wave", from: conn.player }, { except: conn });
    }
  },
  calls: {
    rename(room, conn, { name }) {
      const trimmed = name.trim().slice(0, 64);
      room.presence.set(conn.player, { name: trimmed });
      return trimmed;
    },
  },
});
```

Players who leave keep their entity and score for when they come back.
To remove them, delete it in `onLeave`, which also runs for a dropped
network, or sweep entities whose owner has no presence entry in
`onTick`, as the [Colyseus guide](/docs/migrate/colyseus#in-irt) does.

The client keeps its frame loop. It writes its own position and reads
everyone else's from the room:

```ts
// client.ts
import { connect, createRoom, joinByCode } from "@irt/client";
import { Player, schema } from "./schema.js";

const router = location.hostname.endsWith(".irt-serve.com") ? "wss://eu.irt.io" : location.origin;
const project = "coins";
const keys = new Set<string>();
addEventListener("keydown", (e) => keys.add(e.key));
addEventListener("keyup", (e) => keys.delete(e.key));

// The join code goes in the URL, as Playroom does with #r=.
async function roomId(): Promise<string> {
  const code = new URLSearchParams(location.hash.slice(1)).get("r");
  if (code) return joinByCode({ router, project, code });
  const { id, joinCode } = await createRoom({ router, project, joinCode: true, maxPlayers: 8 });
  location.hash = `r=${joinCode}`;
  return id;
}

const room = await connect({ router, project, room: await roomId(), schema });
await room.call("rename", { name: "Alice" });
room.on("message", (m) => console.log("wave from", (m as { from: string }).from));
document.querySelector("#wave")?.addEventListener("click", () => room.send({ type: "wave" }));

const others = room.interpolate(Player, ["x", "y"]);

function frame() {
  for (const me of room.entities.mine(Player)) {
    if (keys.has("ArrowRight")) me.x = Math.min(100, me.x + 1);
  }
  for (const p of room.entities.all(Player)) {
    const owner = room.entities.ownerOf(p);
    if (!owner) continue;
    const at = owner === room.player ? p : others.get(p);
    console.log(room.presence.get(owner)?.name ?? owner, at.x, at.y, p.score);
  }
  requestAnimationFrame(frame);
}
frame();
```

Owner writes show on the writing client at once and go to the room at
most once per tick. Remote players are drawn through `interpolate`, a
little behind, so they move smoothly between ticks. Games where movement
must be fair, such as shooters, should go further and send inputs to a
[stepper](/docs/guides/prediction) the room runs, rather than positions.

### Its tests

```ts
// room.test.ts
import { testRoom } from "@irt/testing";
import { expect, test } from "vitest";
import room from "./room.js";
import { Player } from "./schema.js";

test("a player moves itself, and the room limits how far", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  const bob = await t.connect({ player: "bob" });
  const [me] = alice.mine(Player);

  me!.x = 12;
  await t.host.tick(2);
  expect(bob.view(Player).find((p) => p.id === me!.id)).toMatchObject({ x: 12 });

  me!.x = 90;
  await t.host.tick(2);
  alice.expectCorrected(me!.id, "x");
  expect(me!.x).toBe(15);
});

test("the room scores a pickup, renames and forwards waves", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  const bob = await t.connect({ player: "bob" });
  t.live.state.coinX = 10;
  t.live.state.coinY = 10;
  await t.host.tick();
  expect(alice.mine(Player)[0]).toMatchObject({ score: 1 });

  const renamed = alice.client.call("rename", { name: "  Alice " });
  await expect(alice.client.call("rename", { name: "" })).rejects.toThrow("non-empty");
  await t.host.tick();
  await expect(renamed).resolves.toBe("Alice");
  expect(bob.client.presence.get("alice")?.name).toBe("Alice");

  alice.send({ type: "wave" });
  await t.host.tick();
  bob.expectMessage({ type: "wave", from: "alice" });
  expect(alice.messages).toEqual([]);
});
```

## What has no direct equivalent

**The host player.** Playroom picks one player's browser to run the
logic and moves the job when that player leaves. IRT has no host player:
the room is the authority, it keeps running while players come and go,
and it saves its state when everyone has left. Code under `isHost()`
moves to `onTick`, `onMessage` and call handlers, and code for host
changes goes away. If the game has a player in charge, such as a party
leader who picks the map, keep their ID in `room.state`, pass it on in
`onLeave`, and check it in the calls that need it.

**Client-authoritative state.** In Playroom any client can write any
player's state and the shared state. In IRT a client can write only the
writable fields of entities it owns, and its private state, and the
room's `onWrite` has the last word. Everything else is the room's, and
clients ask for changes with messages and calls. If you really want a
client to decide something, such as a value nobody else can check, make
the field writable and have `onWrite` return `next`.

**Physics on the host.** A Playroom game that simulates on the host and
shares the results should run the simulation in the room instead. Use
[`@irt/physics`](/docs/guides/physics) as the room's stepper, and clients
predict their own body with the same code.

**The lobby screen and profiles.** IRT shows no UI and has no player
profiles. Build your own menu with `createRoom`, `joinByCode`,
`listPublic` and `quickJoin` (see [Games without a backend](/docs/no-backend)),
and keep names in presence and colors or avatars in an entity or in
private state. Playroom's stream mode and platform integrations have no
counterpart.

**Unreliable state.** IRT sends entity changes reliably, once per tick,
as deltas. For values that are fine to lose, send
`room.send(msg, { unreliable: true })` and forward them with
`room.broadcast(msg, { unreliable: true })`.

**State that outlives the room.** An IRT room's state is kept when it
hibernates, for as long as `rooms.retention` says, but data that belongs
to a player across rooms, such as unlocks, needs your own backend and
[player tokens](/docs/player-tokens).

## Checklist

1. Create a project with `npx @irt/cli init` and write `schema.ts`: a
   kind per kind of thing, the global keys as `state`, per-player keys
   as fields of a player kind, secrets as `private`. Import it from room
   and client.
2. Move every `isHost()` branch into the room module, and delete host
   migration code.
3. For each `player.setState` the player should keep writing, make the
   field `writable`, give the player the entity in `onJoin`, and check
   values in `onWrite`. Move the rest into room code driven by messages,
   calls or a stepper.
4. Turn RPCs to the host that return a value into calls, and RPCs to
   everyone into a message the room forwards.
5. Replace `insertCoin` with your own room menu and `connect`; set
   `players.guests`, `players.createRooms` and `players.quickJoin` in
   `irt.config.ts` to match.
6. Replace `onPlayerJoin` and `getProfile` with `room.presence`.
7. Write tests with `@irt/testing` for moving, for each rule the host
   used to check, for a write the room must correct
   (`expectCorrected`), a dropped connection and a hibernation. The
   [testing guide](/docs/guides/testing) has a pattern for each.
8. Run it with `npx irt dev`, check rooms in the
   [inspector](/docs/dev-tools), then `npx irt deploy`, which serves the
   site from `<project>.irt-serve.com` with the room code it was built
   against.

---

# Migrating from Socket.IO

> Port a Socket.IO 4 game server to IRT rooms, with a concept map, a game ported side by side, what has no equivalent and a checklist that ends in tests.

A Socket.IO game server is usually one Node process holding every game in
a `Map`, with Socket.IO rooms as broadcast channels over it. On IRT each
game is a **room**, run by room code you write with `@irt/room`,
addressed by a room ID, with its own state that's synced to its clients
and saved when the room hibernates. The `Map`, the `"state"` events and
the seat bookkeeping go away, and what's left is the game's rules.

There is no compatibility layer. IRT doesn't speak the Socket.IO
protocol, and a Socket.IO server can't run in a room host: Socket.IO
rooms are channels inside one process, and IRT rooms hibernate and wake
in whichever room host has space. You rewrite the server's handlers as
room hooks and the client against `@irt/client`; handlers usually carry
over with small changes.

This page describes Socket.IO 4.

## Concept map

| Socket.IO 4 | IRT |
|---|---|
| `new Server()` and `io.on("connection", ...)` | A room module, `export default defineRoom({...})`. IRT runs it for each room on its own |
| `socket.join(roomId)` | `connect({ router, project, room: roomId })`: a connection belongs to one room. `room.leave()` leaves it |
| A socket in several rooms | A client in several rooms holds a connection to each |
| A `Map` of game state keyed by room | `room.state`, entities and private state, [declared in a schema](/docs/guides/state-sync) and synced to clients as deltas |
| `io.to(roomId).emit("state", game)` after each change | Nothing: changes to entities go out at the end of each tick |
| `socket.id` | `conn.id` for the connection, `conn.player` for the player, stable across reconnects |
| `socket.data` | `conn.data`, not saved |
| `socket.handshake.auth` and `io.use` middleware | [Player tokens](/docs/player-tokens) checked by the router; `conn.meta` holds their `meta` claim. `onJoin` can `room.kick(conn)` |
| `socket.on("event", handler)` | One `onMessage(room, conn, message)` hook; switch on a `type` field of your own |
| `socket.emit` from the server | `room.send(conn, msg)` |
| `io.to(roomId).emit` | `room.broadcast(msg)` |
| `socket.to(roomId).emit` | `room.broadcast(msg, { except: conn })` |
| An ack callback, or `emitWithAck`, from the client | [Calls](/docs/guides/calls): `await room.call(name, args)`, answered by `calls[name]` in the room |
| `socket.timeout(ms).emitWithAck(...)` | `room.call(name, args, { timeout: ms })`; 10 seconds by default |
| `socket.volatile.emit` | `send(msg, { unreliable: true })` |
| `socket.on("disconnect")` | `onLeave(room, conn)` |
| `setInterval` game loops | `tickRate` and `onTick(room, dt)` |
| Client `connect`, `disconnect` events and reconnection | `room.on("disconnected")`, `"restored"` and `"closed"`. Reconnecting and resyncing are automatic |
| Connection state recovery | Automatic: a reconnecting client gets the full state again |
| Long-polling, then upgrade to WebSocket | WebTransport, with WebSocket as the fallback. No long-polling |

## A game, ported

Tic-tac-toe in rooms named by an ID the players share. The first two
players take `x` and `o`, moves are acknowledged, and players can chat.

### In Socket.IO

```ts
// server.ts (Socket.IO 4)
import { Server } from "socket.io";

type Game = { cells: string[]; x?: string; o?: string; turn: "x" | "o"; winner: string };
const games = new Map<string, Game>();
const io = new Server(3000, { cors: { origin: "https://ttt.example.com" } });

io.on("connection", (socket) => {
  socket.on("join", (roomId: string, ack) => {
    let game = games.get(roomId);
    if (!game) games.set(roomId, (game = { cells: Array(9).fill(""), turn: "x", winner: "" }));
    const mark = !game.x ? "x" : !game.o ? "o" : null;
    if (!mark) return ack({ error: "room full" });
    game[mark] = socket.id;
    socket.data.roomId = roomId;
    socket.join(roomId);
    ack({ mark });
    io.to(roomId).emit("state", game);
  });

  socket.on("play", (cell: number, ack) => {
    const game = games.get(socket.data.roomId);
    if (!game || game.winner || game[game.turn] !== socket.id || game.cells[cell] !== "") {
      return ack({ error: "not your move" });
    }
    game.cells[cell] = game.turn;
    game.winner = winnerOf(game.cells);
    game.turn = game.turn === "x" ? "o" : "x";
    ack({ ok: true });
    io.to(socket.data.roomId).emit("state", game);
  });

  socket.on("chat", (text: string) => {
    socket.to(socket.data.roomId).emit("chat", { from: socket.id, text });
  });

  socket.on("disconnect", () => {
    const game = games.get(socket.data.roomId);
    if (game?.x === socket.id) game.x = undefined;
    if (game?.o === socket.id) game.o = undefined;
  });
});
```

```ts
// client.ts (socket.io-client 4)
import { io } from "socket.io-client";

const socket = io("https://ttt.example.com");
const { mark, error } = await socket.emitWithAck("join", "kitchen-table");
socket.on("state", (game) => render(game));
socket.on("chat", ({ from, text }) => console.log(from, text));

const reply = await socket.emitWithAck("play", 4);
if (reply.error) console.log(reply.error);
```

The `Map` is lost when the process restarts, a dropped player loses
their seat because `socket.id` changes on reconnect unless connection
state recovery restores it, and running a
second process needs an adapter and sticky sessions.

### In IRT

The schema, shared by room and client, declares the board and the `play`
call. `parse` checks the cell on the room before the handler sees it:

```ts
// schema.ts
import { defineCalls, defineSchema, entity, json } from "@irt/room";

export const Board = entity("board", {
  cells: json<string[]>(),
  x: "string",
  o: "string",
  turn: "string",
  winner: "string",
});

export const schema = defineSchema({
  state: Board,
  calls: defineCalls<{ play(args: { cell: number }): string }>({
    play(raw) {
      const cell = (raw as { cell?: unknown } | null)?.cell;
      if (typeof cell !== "number" || !Number.isInteger(cell) || cell < 0 || cell > 8) throw new Error("cell is 0 to 8");
      return { cell };
    },
  }),
});
```

The room. Seats are player IDs, so a player who reconnects, or reloads
the page, still has theirs. A third player watches:

```ts
// room.ts
import { defineRoom } from "@irt/room";
import { schema } from "./schema.js";

const LINES = [[0, 1, 2], [3, 4, 5], [6, 7, 8], [0, 3, 6], [1, 4, 7], [2, 5, 8], [0, 4, 8], [2, 4, 6]];

function winnerOf(cells: string[]): string {
  for (const [a, b, c] of LINES) if (cells[a!] && cells[a!] === cells[b!] && cells[a!] === cells[c!]) return cells[a!]!;
  return cells.every((m) => m) ? "draw" : "";
}

export default defineRoom({
  schema,
  onCreate(room) {
    room.state.cells = Array(9).fill("");
    room.state.turn = "x";
  },
  onJoin(room, conn) {
    const s = room.state;
    if (s.x === conn.player || s.o === conn.player) return;
    if (!s.x) s.x = conn.player;
    else if (!s.o) s.o = conn.player;
  },
  onMessage(room, conn, message) {
    const m = message as { type?: unknown; text?: unknown } | null;
    if (m?.type !== "chat" || typeof m.text !== "string") return;
    room.broadcast({ type: "chat", from: conn.player, text: m.text.slice(0, 200) }, { except: conn });
  },
  calls: {
    play(room, conn, { cell }) {
      const s = room.state;
      const mover = s.turn === "x" ? s.x : s.o;
      if (s.winner || mover !== conn.player || s.cells[cell] !== "") throw new Error("not your move");
      // A json field is sent when it's assigned, so build a new array.
      s.cells = s.cells.map((m, i) => (i === cell ? s.turn : m));
      s.winner = winnerOf(s.cells);
      s.turn = s.turn === "x" ? "o" : "x";
      return s.cells[cell]!;
    },
  },
});
```

The client. There's no join event: connecting is joining, and the
client reads its seat from the state. Rooms named by the players need
`players.createRooms` on, which is the default, so the first connection
creates the room:

```ts
// client.ts
import { connect, IrtError } from "@irt/client";
import { schema } from "./schema.js";

const router = location.hostname.endsWith(".irt-serve.com") ? "wss://eu.irt.io" : location.origin;

const room = await connect({ router, project: "tic-tac-toe", room: "kitchen-table", schema });
const mark = room.state.x === room.player ? "x" : room.state.o === room.player ? "o" : "watching";
console.log("you are", mark);

room.onTick(() => console.log(room.state.cells?.join(""), room.state.turn, room.state.winner));
room.on("message", (m) => console.log("chat", m));

export async function play(cell: number) {
  try {
    await room.call("play", { cell });
  } catch (e) {
    if (e instanceof IrtError) console.log(e.message);
    else throw e;
  }
}

export function chat(text: string) {
  room.send({ type: "chat", text });
}
```

A room ID anyone can guess is fine for a demo. For private tables, use
`createRoom({ joinCode: true })` and share the code; see
[Games without a backend](/docs/no-backend). To turn the third player
away instead of letting them watch, create rooms with `maxPlayers: 2`,
and a third connection closes with 4003.

### Its tests

```ts
// room.test.ts
import { testRoom } from "@irt/testing";
import { expect, test } from "vitest";
import room from "./room.js";

test("players take turns, and the room refuses moves out of turn", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  const bob = await t.connect({ player: "bob" });
  expect(t.live.state).toMatchObject({ x: "alice", o: "bob", turn: "x" });

  // The move's reply waits for the tick that saves it.
  const played = alice.client.call("play", { cell: 4 });
  await expect(alice.client.call("play", { cell: 0 })).rejects.toThrow("not your move");
  await expect(bob.client.call("play", { cell: 4 })).rejects.toThrow("not your move");
  await expect(bob.client.call("play", { cell: 9 })).rejects.toThrow("cell is 0 to 8");
  await t.host.tick();
  await expect(played).resolves.toBe("x");
  expect(bob.client.state.cells).toEqual(["", "", "", "", "x", "", "", "", ""]);
});

test("a player keeps their seat across a reconnect and a hibernation", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  await t.connect({ player: "bob" });
  alice.drop();
  await alice.reconnected();
  await t.connect({ player: "carol" });
  expect(t.live.state).toMatchObject({ x: "alice", o: "bob" });

  await t.hibernate();
  await t.connect({ player: "bob" });
  expect(t.live.state).toMatchObject({ x: "alice", o: "bob" });
});

test("chat goes to everyone else", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  const bob = await t.connect({ player: "bob" });
  alice.send({ type: "chat", text: "good luck" });
  await t.host.tick();
  bob.expectMessage({ type: "chat", from: "alice", text: "good luck" });
  expect(alice.messages).toEqual([]);
});
```

## What has no direct equivalent

**Namespaces.** IRT has no namespaces. Separate parts of a product that
share nothing, such as a game and its admin tools, become separate
[projects](/docs/concepts). Kinds of room within one game share one room
module, which tells them apart by a room ID prefix you choose, such as
`duel-` and `ffa-`.

**Cross-room messages and global broadcasts.** `io.emit` to every socket,
`io.to(otherRoom).emit` from a handler, `serverSideEmit` and
`fetchSockets` across rooms have no counterpart. IRT rooms don't message
each other, and a room's code sees only its own connections. Do it from
your backend: it lists rooms with `GET /projects/{p}/rooms`, sends a
message into any room with `POST /projects/{p}/rooms/{id}/messages`,
which the room answers in `onRequest`, and learns about joins and leaves
from [webhooks](/docs/webhooks). For something every player sees at once,
such as site-wide chat in a small game, every client can also hold a
connection to one shared room, up to its room size's connection limit.

**Acks from server to client.** The room can't call a client and wait
for its answer. Send a message, and have the client answer with a
message or a call.

**Many rooms per socket.** A Socket.IO socket can be in any number of
rooms and receive all their broadcasts over one connection. An IRT
connection is to one room. Hold a connection per room, or put the
channels into one room, such as one entity per channel with
[interest](/docs/guides/state-sync#interest) deciding who sees which.

**Arbitrary events and binary blobs as state.** Socket.IO sends whatever
you emit. IRT syncs state as typed entities, and messages are JSON or a
`Uint8Array`, at most 64 KB each. Big data, such as a map, goes in
`bytes` fields of chunk entities.

**Your own HTTP server.** IRT rooms don't serve HTTP, and a room can't
share an Express app with the socket server. Routes move to your backend,
which reaches rooms through the [HTTP API](/docs/http-api); static files
move to the project's [site](/docs/sites).

**Adapters and sticky sessions.** There's nothing to configure. The
router sends each connection to the room host running its room, wakes
hibernated rooms on connect, and many rooms share a room host.

## Checklist

1. Write `schema.ts`: each per-room object you kept in a `Map` becomes
   `state`, an entity kind, or private state for what one player alone
   should see. Import it from both the room and the client.
2. Move each `socket.on` handler into `onMessage`, or into a call if the
   client waited on an ack. Validate every field.
3. Delete every `emit` of state; set entity fields instead. Keep emits
   of events, such as chat, as `room.send` and `room.broadcast`.
4. Replace `socket.id` with `conn.player` wherever you meant the player,
   such as seats and scores.
5. Replace `setInterval` loops with `tickRate` and `onTick`.
6. Replace the join event with `connect`, and room choice with a room ID,
   `createRoom`, `joinByCode`, `listPublic` or `quickJoin`.
7. Move `io.use` authentication to [player tokens](/docs/player-tokens)
   your backend signs, or allow guests, and anything that crosses rooms
   to your backend and the HTTP API.
8. Write tests with `@irt/testing` for each message and call, a dropped
   connection (`drop()` and `reconnected()`), a crash (`t.host.crash()`)
   and a hibernation (`t.hibernate()`). The
   [testing guide](/docs/guides/testing) has a pattern for each.
9. Run it with `npx irt dev`, check rooms in the
   [inspector](/docs/dev-tools), then `npx irt deploy`.

---

# Deploying with the CLI

> Take a project from login to live with irt login, init, dev, test, build, deploy and logs.

The `irt` CLI covers the whole loop: log in, create a project, run it
locally, test it, deploy it and read its logs.

## Install

The CLI is the npm package `@irt/cli` (the name `irt` on npm belongs to
someone else). It needs Node 24 or later. Run it without installing:

```sh
npx @irt/cli <command>
```

or install it, globally or as a project devDependency, for the `irt`
command:

```sh
npm install -g @irt/cli
irt <command>
```

Every error is one line that says what to do, and the CLI exits with a
non-zero status. `irt help` lists every command, and `irt <command>
--help` one command's arguments and flags.

## Global options

| Option or variable | Meaning |
|---|---|
| `--project <slug>` | The project to act on; overrides `project` in `irt.config.ts` |
| `IRT_TOKEN` | A token to use instead of the stored login; set it to a project API key (`irt_key_...`) in CI |
| `IRT_API_URL` | The API base URL; default `https://api.irt.io/v1` |

## `irt.config.ts`

A project declares its config and settings in code, next to its room:

```ts
// irt.config.ts
import { defineConfig } from "@irt/cli/config";

export default defineConfig({
  project: "space-race",
  room: "src/room.ts",
  site: { dir: "dist", build: "npm run build:web", crossOriginIsolated: false },
  settings: {
    players: { guests: true, createRooms: true, listPublic: true },
    voice: { enabled: true, maxSpeakers: 8 },
    rooms: { size: "standard", retention: "7d", buildUpdate: "hibernate" },
  },
});
```

| Field | Meaning |
|---|---|
| `project` | The project's slug: a-z, 0-9 and -, its name in URLs and in `<slug>.irt-serve.com` |
| `room` | The room module; its default export is the result of `defineRoom`. It's one [room type](#room-types), named `default`. Give `room` or `rooms` |
| `rooms` | The project's room types by name; see [Room types](#room-types) |
| `site.dir` | Optional: the directory of built site files that's deployed |
| `site.build` | Optional: a shell command that builds the site into `site.dir`, run by `irt build`, `irt deploy` and `irt dev` |
| `site.crossOriginIsolated` | Optional, default `false`: serve the site with COOP and COEP |
| `settings` | Optional: the project's settings, below |

The CLI bundles the file with esbuild, loads it, and checks it before
building, so a bad value fails in one line naming the field and what it
allows, before anything is uploaded:

```
irt: irt.config.ts: settings.rooms.retention is "2y"; it must be "none", a number of hours or days such as "12h" or "7d" up to 365 days, or "forever"
```

### Room types

A project whose rooms run different code, such as a lobby and a match,
declares each as a [room type](/docs/concepts#rooms) in `rooms`
instead of `room`:

```ts
// irt.config.ts
import { defineConfig } from "@irt/cli/config";

export default defineConfig({
  project: "space-race",
  rooms: {
    default: "src/lobby.ts",
    match: { room: "src/match.ts", size: "large", maxPlayers: 8, retention: "1d" },
    chat: { native: true, size: "small" },
    world: { native: true, schema: "src/world.ts", tickRate: 20, size: "small" },
  },
});
```

| Entry | Meaning |
|---|---|
| `"path"` | The type's room module, whose default export is the result of `defineRoom` |
| `{room, size?, maxPlayers?, retention?}` | The module, with the type's own room size, cap on connections and retention, over the project's `rooms.size`, none and `rooms.retention` |
| `{native: true, schema?, tickRate?, lobby?, size?, maxPlayers?, retention?}` | A [native room](/docs/concepts#rooms), which runs no code of yours: it sends each message on to the other players and keeps presence and a leader. With `schema`, players also spawn, own and write the entities of the schema module's default export, under the rules each `entity()` declares, and it ticks `tickRate` times a second, 1 to 60, 20 by default. With `lobby`, it gathers players and hands them off to a room of another type; see [Lobbies and parties](/docs/guides/lobbies) |

A project has 1 to 32 types, each named with 1 to 32 characters of
`a-z`, `0-9` and `-`, starting with a letter. A standard type can't be
`small` until small has a price; a native type can. `maxPlayers` is 1
to its size's connection limit. A create, quick join or connection that
names no type gets the type named `default`; without one, every one of
them must name a type. Clients pass the type to `connect`,
`createRoom`, `quickJoin` and `listPublic` as `type`.

### Settings

`settings` has the same names as the project's settings in the
[HTTP API](/docs/http-api#project-settings) and the dashboard:

| Setting | Default | Allowed | Meaning |
|---|---|---|---|
| `players.guests` | `true` | boolean | Clients may join with no player token |
| `players.createRooms` | `true` | boolean | Clients may create rooms and use join codes |
| `players.listPublic` | `true` | boolean | Clients may list active public rooms |
| `players.quickJoin` | `false` | boolean | Clients may join any public room with space, or a new one |
| `players.listPublicWithoutToken` | `false` | boolean | Anyone may list public rooms with no token, even with `players.guests` off |
| `voice.enabled` | `false` | boolean | Connections get a voice token |
| `voice.maxSpeakers` | `64` | integer 1 to 64 | A ceiling on each room's own `voice.maxSpeakers`, applied from a room's next wake; see [Proximity voice](/docs/guides/proximity-voice#turning-it-on) |
| `rooms.size` | `"standard"` | `"standard"`, `"large"`, `"extra-large"` | Room size for new rooms |
| `rooms.retention` | `"7d"` | `"none"`, `"<n>h"`, `"<n>d"` up to 365 days, `"forever"` | How long a room is kept after it hibernates; `"none"` deletes it when it empties |
| `rooms.buildUpdate` | `"hibernate"` | `"restart"`, `"hibernate"` | Running rooms move to a new build at once, or on their next hibernate |
| `rooms.rollbackOnCrashLoop` | `true` | boolean | When a newly live build crash-loops, make the build it replaced live again, once per build; see [Builds](/docs/builds#automatic-rollback) |
| `data.player.clientWrite` | `[]` | player data keys | The keys a client may write for its own player |
| `data.collections.<name>` | none | 1 to 32 of `a-z 0-9 _ -`, from a letter; at most 32 | A collection, with `clientRead` (boolean, default `false`), `clientWrite` (`"own"`, default none), `maxOwn` (1 to 10,000, default 100) and `leaderboard` (`order` `"desc"` or `"asc"`, `keep` `"best"`, `"latest"` or `"sum"`, `periods` of `"all"`, `"day"`, `"week"`, `"month"`, default `["all"]`); see [Player data](/docs/guides/player-data) |

`irt deploy` sends the settings in the build. When the build goes live,
the settings it declares become the project's, and rolling back to an
older build rolls them back too. A setting the live build declares is
read-only in the dashboard. A setting the config leaves out keeps its
current value. `limits` and `webhookUrl` never come from code: they're
the account owner's, so a deploy can't raise a spending cap, and
`defineConfig` rejects them.

## `irt login` and `irt logout`

```sh
irt login
irt logout
```

`irt login` logs the CLI in with a device code:

1. The CLI shows a short code and opens `https://app.irt.io/device`.
2. You sign in to the dashboard with GitHub, if you aren't already, and
   enter the code.
3. The CLI receives a personal token and stores it in
   `~/.config/irt/credentials.json`, readable only by you (mode 600). The
   token acts for your tenant.

`irt logout` deletes the stored token. In CI, don't log in: set
`IRT_TOKEN` to an API key from the dashboard, which acts for one project
only.

## `irt init [dir] [--project <slug>]`

```sh
irt init my-game --project space-race
```

Creates a directory (default: the current one) with a minimal working
game for the project `--project` names. Without `--project`, the slug is
made from the directory's name: lowercased, with runs of other
characters turned into `-`. `init` prints the slug it used and what to
run next:

```text
created /home/you/my-game for the project space-race
the slug is `project` in irt.config.ts, which web/main.ts imports
next: cd my-game, npm install, npx @irt/cli projects create space-race, then npx @irt/cli dev
```

When you're logged in, `init` asks the API whether the project exists
and leaves `projects create` out of the next steps if it does. Logged
out, or when the API can't be reached, the step reads `npx @irt/cli
projects create space-race if it doesn't exist yet`.

To change the slug later, edit `project` in `irt.config.ts`; the
scaffolded `web/main.ts` imports it from there. Create the project itself
with `irt projects create <slug>`.

| File | Contents |
|---|---|
| `irt.config.ts` | The project's slug, entry points and settings |
| `build-web.mjs` | Bundles and minifies `web/main.ts` into `dist/` with esbuild, for `site.build`, with each dynamic `import()` in a chunk of its own, and hashed file names that it writes into `dist/index.html` |
| `src/schema.ts` | The schema, shared by the room and the client |
| `src/room.ts` | The room code |
| `src/room.test.ts` | A test with [`@irt/testing`](/docs/reference/testing) |
| `web/index.html`, `web/main.ts` | A plain TypeScript web client with no framework |

The generated `irt.config.ts` declares every setting at its default.
`irt dev` applies the settings locally: guests, room creation and public
listing as declared, and `rooms.retention: "none"` deletes a room when it
empties. Voice is off locally unless `IRT_LIVEKIT_URL` names a LiveKit
server; see [Proximity voice](/docs/guides/proximity-voice#turning-it-on).

## `irt dev [--port 7350]`

Runs the project on your machine: `irt-room-host` in local mode with each
room type's bundled room code, native types included, serving the client protocol and the site on one
origin, `http://127.0.0.1:<port>`, with the same headers the hosted site
gets. The scaffolded client uses `location.origin` as its router address
there, and `wss://eu.irt.io` on `irt-serve.com`. That includes COOP and COEP
when the site is cross-origin isolated, so `SharedArrayBuffer` behaves
locally as it does on `irt-serve.com`. It rebuilds and restarts the room
host when a file in the project changes, so connected clients reconnect,
and says which file it was. Without a `site.build` command, only the
room's own files and `site.dir` count; with one, any file can, since the
command may read it. It doesn't watch dot files and directories,
such as `.irt` and `.git`, `node_modules`, the site build's `site.dir`,
`*.log` files or editors' swap files, so `irt dev > dev.log` inside the
project doesn't rebuild it over and over. Ctrl-C, SIGTERM and SIGHUP
stop the room host with it; if the port is taken, as by a room host left
over from an `irt dev` that was killed with SIGKILL, it says so and
exits.
Room state is kept in `.irt/data` between runs. The inspector at
`/v1/dev/` shows each room's connections, state, entities, recent
messages and calls, and tick profile; see [Dev tools](/docs/dev-tools).

| Flag | Default | Meaning |
|---|---|---|
| `--port` | `7350` | Port of the local room host and site |

In local mode, as deployed, a room is created when a client first
connects to it, if `players.createRooms` is on.

## `irt test`

Runs the project's tests with Vitest. Tests use `@irt/testing`, which
runs rooms in process with test clients and a controlled clock; its
failure messages say what was expected, what happened, and in which
room, connection and tick.

`irt test` doesn't typecheck, since Vitest strips types without checking
them, so a test run stays fast. `irt build` and `irt deploy` do; to check
types while you work, run `npm run typecheck`, the scaffold's `tsc
--noEmit`.

## `irt simulate`

Runs the project's room locally, in process, with simulated players:
each a bot with a real `@irt/client` connection, driven by the built-in
behaviours or by the project's `irt.sim.ts`. After every tick it checks
invariants: no client sees an entity its interest excludes, predictions
aren't corrected too often, owned writes aren't silently lost, the room
logs no errors, room state stays within limits, reconnects restore the
room's state, and the script's own. It prints a line per invariant with
traffic per player and time per tick, writes a trace of JSON lines, and
exits with 1 when an invariant fails. It never runs against a deployed
project. See [Simulating players](/docs/guides/simulate).

| Flag | Default | Meaning |
|---|---|---|
| `--players` | 8 | Bots that join before the first tick |
| `--ticks`, `--seconds` | 30 seconds | How long to run, in ticks or seconds of room time |
| `--seed` | 1 | Seeds the bots, the network and `Math.random` in room code |
| `--script` | `irt.sim.ts` if it exists | The simulation script |
| `--behaviour` | `walk` | Built-in behaviours for every bot: `walk`, `chat`, `idle`, or several joined by commas |
| `--rtt`, `--jitter`, `--loss` | none | A simulated network for every bot: round trip and jitter in milliseconds, and the fraction of unreliable messages lost |
| `--drops` | 0 | Connections to drop at random ticks, to check reconnects |
| `--trace` | `.irt/simulate/trace.jsonl` | Where to write the trace |
| `--type` | `default` | The [room type](#room-types) to simulate, without a script; a script names its own room |

Flags override the script's own settings.

## `irt build [--out dir] [--no-typecheck]`

Typechecks the project, bundles the room module with esbuild into one
file, runs the site's `site.build` command if `irt.config.ts` has one,
and writes the build tarball. It prints each room type's schema hash:

```text
built .irt/build/build.tar.gz (9 files)
  room type default: schema 0x1f2e3d4c
  room type match: schema 0x5a6b7c8d, large, max 8 players, retention 1d
  room type chat: native, schema 0x9437de34, small
```

The typecheck is `tsc --noEmit` with the project's `tsconfig.json`, so it
covers whatever that file includes: the scaffold's covers `src`, `web` and
`irt.config.ts`. Any error fails the build after printing tsc's errors. A
project without `tsconfig.json` isn't checked, and one with it but no
`typescript` installed fails until you install it. `--no-typecheck` skips
the check, such as to deploy a fix while an unrelated file has errors.

The tarball:

| Path | Contents |
|---|---|
| `irt-build.json` | `{format: 2, sdk, site: {crossOriginIsolated}, settings, types}`, with each room type's `{entry, schemaHash, schema, stateVersion}` or `{native, schemaHash, schema, stateVersion, tickRate, lobby?}`, `lobby` with every default filled in, and its own `size`, `maxPlayers` and `retention`; `schemaHash` is `0x` and 8 hex digits, `stateVersion` is the type's `version`. See [Builds](/docs/builds#whats-in-a-build) |
| `room/` | Each standard room type's bundled room code, as `{type}.mjs` |
| `site/` | The site's files, if the project has a site |

| Flag | Default | Meaning |
|---|---|---|
| `--out` | `.irt/build` | Directory to write `build.tar.gz` to |
| `--no-typecheck` | off | Build without running `tsc` |

The unpacked files stay in `stage/` under that directory, which
`irt-room-host` runs directly; see [Self-hosting](/docs/self-hosting).

## `irt deploy [--no-live] [--no-typecheck]`

Builds as `irt build` does, typecheck included unless `--no-typecheck`
is given, uploads the build to the project, and makes it live unless
`--no-live` is given. Then it prints where the site is served and the
router address its clients pass to `connect`, from the project's client
config:

```text
deployed build b_01J9Z3 to space-race; it's live
room state of type default: compatible, at version 1; rooms wake from the live build's room state without a migration:
  added player.score (u32); room state without it loads with its default value
  site:   https://space-race.irt-serve.com
  router: wss://eu.irt.io (pass it to connect() as `router`)
```

The `room state of type` lines are the control server's
[schema check](/docs/builds#the-schema-check-at-deploy): how each room
type's schema and `version` compare with the same type in the build it
replaces, and each change.
A build whose changes old room state can't load, at the same `version`,
is refused. It stays uploaded, the live build stays live, and the CLI
lists each change and exits with 1:

```text
build b_01J9Z4 isn't live; these changes to room type default's room state need a version bump and a migration:
  removed player.hp (u8), so room state that has it won't load
irt: build b_01J9Z4 can't replace the live build b_01J9Z3: it changes room state without a version bump, both builds being at version 1: removed player.hp (u8), so room state that has it won't load. Bump `version` in defineRoom to 2 and add a migration, `migrations: { 2: (data) => ... }`, that converts room state from version 1
```

There's no flag to skip the check: rooms would fail to wake on the build.
A build that drops a room type while rooms of it have records is refused
the same way, naming the type; see
[Adding and removing room types](/docs/builds#adding-and-removing-room-types).

Making a build live does two things at once:

- the site at `<slug>.irt-serve.com` switches to the build's site, and
- rooms move to the build's room code according to the project's
  `buildUpdate` setting: on their next hibernate, or with `restart`
  straight away, a few a second on each host. See
  [New builds](/docs/hibernation#new-builds).

Because the site and room code go live together, a client always finds
the room build it was built against. A client loaded from an older build
that connects to a room on a newer one gets close code 4004 and should
reload. A room still on an older build refuses newer clients with 4004
too, until it hibernates and moves. See [Builds and deploys](/docs/builds) for the schema hash rule,
migrations and rollbacks.

A site marked cross-origin isolated in `irt-build.json` is served with
COOP and COEP. `SharedArrayBuffer` needs them, and they stop the site
loading cross-origin resources that don't opt in. See [Sites](/docs/sites).

The dashboard lists builds and can make an earlier build live again,
as `irt rollback` does.

## `irt rollback [build-id]`

```sh
irt rollback
irt rollback b_01J9Z3
```

Makes the build before the live one live again, or the build you name.
The site and the build's declared settings switch at once, and running
rooms move to it as `rooms.buildUpdate` says. The CLI prints which:

```text
rolled space-race back to build b_01J9Y8; it's live, with its site and its declared settings
  room type default: schema 0x1f2e3d4c
running rooms stay on build b_01J9Z3 until they next hibernate, then wake on build b_01J9Y8 (rooms.buildUpdate is hibernate)
```

When the older build has an older room state `version`, rooms that
migrated past it can't run on it, and the CLI prints a `room state of
type default: version 2 to 1, a rollback` line saying so. Each such room wakes from
the room state kept from before its migration, losing progress since
then, and your backend gets a [`room.restored`](/docs/webhooks) webhook.
Room state from before a migration is kept for 7 days. A room with none
kept, such as one created on the newer build, fails to wake until a
build at its version is live again; `irt logs` says why.

A rollback goes through the same schema check as a deploy. Rolling back
to a build at the same `version` that lacks a field or kind the live
build added is refused, since rooms that woke on the live build saved
room state with it. Deploy a new build instead.

## `irt restart [room-id]`

```sh
irt restart
irt restart forest-7
```

Moves the project's running rooms, or the one named, onto the live
build now, whatever `rooms.buildUpdate` says. Each room hibernates,
saving its room state, and wakes on the live build, even when it runs
that build already, so a restart also clears whatever a room host held
in memory. Clients close with 4008 and reconnect at once. Rooms move 20
a second on each host. Hibernated rooms aren't touched: they wake on the
live build anyway. Naming a room that isn't running is an error.

## `irt logs [--follow]`

Prints the output of the project's room hosts; with `--follow`, keeps
printing as new lines arrive. The same stream is in the dashboard. It
holds what room code prints, errors the room SDK logs, such as a hook
that threw, and the host daemon's notes about a room, such as why it
can't wake or that its room state nears 32 MB. A room that runs without
printing or failing writes nothing, and `irt logs` then says it found no
lines. Each host keeps the last 1 MB of a project's lines, in memory.

## `irt rooms`

```sh
irt rooms list [--public] [--all]
irt rooms show <id>
irt rooms profile <id>
irt rooms create [id] [--type <room type>] [--public] [--join-code] [--retention <value>]
irt rooms delete <id>
irt rooms send <id> '<json>'
```

`profile` prints an active room's tick profile over the last second, as
its room host measured it: per phase, such as `stepper`, `onTick`,
`interest` and `flush`, how many ran and their p50, p95 and max in
milliseconds. It doesn't wake a hibernated room.

`list` prints each room's ID, status and players. It lists only active
rooms, so a room that emptied and hibernated drops out of it until it
wakes; use `--all` to list every room the project keeps, with
hibernated ones shown as `hibernated`. `--public` lists only public
rooms. `show` prints one room's status, players, build, size and room
state size as last saved to object storage, which for a running room
trails by up to 30 seconds. `create --type` sets the new room's
[room type](#room-types), default `default`. `create --retention` gives the room a
retention of its own, such as `forever` or `30d`, which wins over the
project's `rooms.retention`; see [Retention](/docs/hibernation#retention).
`send` delivers a server API message to the room's `onRequest` and prints
the reply. A message to a hibernated room wakes it.

## `irt secrets`

```sh
irt secrets list
irt secrets set <name> <value>
irt secrets unset <name>
```

Secrets reach room code as environment variables, read with
`process.env`. A room host reads them when it starts, so a changed
secret reaches rooms on room hosts started after the change: `irt deploy`
starts new ones for the new build, and rooms move to them as the
project's `rooms.buildUpdate` setting says. Their values are never shown again
after they are set; `list` shows names only. Names are 1 to 64 letters,
digits and underscores; `PATH`, `NODE_OPTIONS`, `HTTPS_PROXY`,
`NODE_USE_ENV_PROXY` and names starting with `IRT_` are reserved for
IRT.

## `irt bans`

```sh
irt bans list
irt bans add <player> [--reason <text>] [--for <30m|12h|7d>]
irt bans remove <player>
```

`add` bans a player from every room of the project, permanently or for
`--for` minutes, hours or days. Their connections close with 4013 within
a few seconds. See [Moderation](/docs/moderation).

## `irt projects`

```sh
irt projects list
irt projects create <slug> [name]
irt projects delete <slug> --yes
```

Deleting a project stops its site and rooms for good. Its slug is never
reused, not even by you, so `delete` asks for `--yes`.

## `irt api-keys`

```sh
irt api-keys list
irt api-keys create <name>
irt api-keys delete <id>
```

API keys act for one project, for backends and CI. `create` prints the
key once; it can't be shown again. `list` shows each key's ID, name and
first characters.

## `irt signing-keys`

```sh
irt signing-keys list
irt signing-keys create
irt signing-keys delete <id>
```

Signing keys sign [player tokens](/docs/player-tokens). `create` prints
the new key's ID and its secret once; it can't be shown again, so store
it on your backend. `list` shows each key's ID and when it was created.
A project has at most 5. Deleting a key stops the player tokens it
signed from connecting; to rotate, create a new key, move your backend
to it, then delete the old one. These commands need `irt login`: an API
key can't manage signing keys.

## `irt webhooks`

```sh
irt webhooks show
irt webhooks set <url>
irt webhooks unset
irt webhooks rotate-secret
```

`set` and `unset` change the project's `webhookUrl`, where
[webhook](/docs/webhooks) events go. `rotate-secret` makes a new signing
secret and prints it once; it signs every event from then on, so update
your backend straight away. Events are sent only once the project has
both a URL and a secret. These commands need `irt login`: an API key
can't change where events go.

## `irt whoami`, `irt status` and `irt usage`

```sh
irt whoami
irt status
irt usage [--from 2026-11-01] [--to 2026-11-30]
```

`whoami` shows the user, tenant and credit balance the login acts for.
`status` shows the project, its live build with its room types, the latest build that was
[rolled back](/docs/builds#automatic-rollback) for crash-looping and
why, and its active rooms and players. `usage` prints room-hours by room size, traffic and cost by
day, and the total; dates are UTC and inclusive, and default to the last
30 days.

## `irt stats`

```sh
irt stats [--from 2026-11-03T00:00:00Z] [--to 2026-11-04T00:00:00Z]
irt stats --build <id> [--from <time>] [--to <time>]
```

Prints each build's peak players and rooms, reconnects, and the errors,
ticks and average and longest tick that its rooms report, over a range
of at most 14 days, by default the last 24 hours. With `--build`, it
prints that build's numbers minute by minute, over at most 24 hours, by
default the last hour. Times are RFC 3339, in UTC. These are the
numbers of [Stats and usage alerts](/docs/stats). Tick cost there is per
build; per room and per hook it's only in the
[`irt dev` inspector](/docs/dev-tools).

## `irt skill install [--dir <path>] [--force]`

```sh
irt skill install
```

Writes the IRT skill for coding agents, the integration rules, common
mistakes and which `irt` commands to run, to `.claude/skills/irt/SKILL.md`
in the project: the nearest directory with `irt.config.ts`, or the
current one. Claude Code loads it when it works on the project. `--dir`
writes `SKILL.md` into that directory instead, such as
`~/.claude/skills/irt` for every project.

A file that's already the same is left alone. One that differs, because
you edited it or an older CLI wrote it, isn't replaced unless you pass
`--force`. The skill points agents to the
[guide for coding agents](/docs/guides/agents).

## `irt mcp [--allow-writes]`

```sh
claude mcp add irt -- npx -y @irt/cli mcp
```

Runs an MCP server on stdio for coding agents, with tools that search
and read the IRT docs and read the project's status, builds, rooms, room
state, logs, usage and bans with your login. `--allow-writes` adds tools
that create and delete rooms, send rooms messages, make builds live and
ban players. See [MCP server](/docs/reference/mcp) for setup in other
clients and the full tool list.

## Without the CLI

Everything the CLI does goes through the [HTTP API](/docs/http-api), so a
CI pipeline can upload builds and make them live with an API key.

---

# Builds and deploys

> What a build holds, why clients must match its schema hash, how rooms move to a new build, and how room state versions and migrations work.

A **build** is one deployable version of a project: the bundled room
code of each of its [room types](/docs/concepts#rooms), its site if
it has one, and the settings `irt.config.ts` declares.
`irt deploy` makes one and makes it live; the commands themselves are in
[Deploying with the CLI](/docs/cli#irt-build---out-dir). This page is
about what happens to clients and rooms when a build goes live.

## What's in a build

`irt build` writes `.irt/build/build.tar.gz`:

| Path | Contents |
|---|---|
| `irt-build.json` | The manifest, below |
| `room/{type}.mjs` | Each standard room type's module and everything it imports, bundled with esbuild for Node 24 |
| `site/` | The output of `site.build`, copied from `site.dir`, when the project has a site |

```json
{
  "format": 2,
  "sdk": "0.1.0",
  "site": { "crossOriginIsolated": false },
  "settings": { "players": { "guests": true } },
  "types": {
    "default": {
      "entry": "default.mjs",
      "schemaHash": "0x1f2e3d4c",
      "schema": [
        { "name": "board", "fields": [{ "name": "moves", "type": "u32", "writable": false }] },
        { "name": "mine", "fields": [{ "name": "moves", "type": "u32", "writable": false }] },
        { "name": "player", "fields": [{ "name": "owner", "type": "string", "writable": false }] }
      ],
      "stateVersion": 1
    },
    "match": { "entry": "match.mjs", "schemaHash": "0x5a6b7c8d", "schema": [], "stateVersion": 3, "size": "large", "maxPlayers": 8, "retention": "1d" },
    "chat": { "native": true, "schemaHash": "0x9437de34", "schema": [], "stateVersion": 1, "tickRate": 20, "size": "small" }
  }
}
```

- `types` has one entry per room type in `irt.config.ts`: 1 to 32,
  named with 1 to 32 characters of `a-z`, `0-9` and `-`, starting with a
  letter. A project with `room` in its config has one type, `default`.
- A standard type has an `entry` in `room/`. A native type has
  `native: true` and no entry, its schema's hash, its `schema` with each
  entity kind's `rules`, state version 1 and its `tickRate`; the schema
  module isn't in the build. Without a schema module it has the empty
  schema's hash and kinds.
- `size`, `maxPlayers` and `retention` are the type's own, when its
  config sets them, over the project's `rooms.size`, no cap and
  `rooms.retention`.
- `schemaHash` is the hash clients of that type send when they connect,
  `0x` and 8 hex digits. `irt build` gets it by loading each bundled room
  in a child process, so a room module that throws at import fails the
  build.
- `schema` lists every kind with its fields, types and writable fields:
  the shared state first, then the private state, then the entity kinds
  in declared order. The control server compares it with the live
  build's when the build goes live; see
  [The schema check at deploy](#the-schema-check-at-deploy).
- `stateVersion` is the type's `version`, the
  [room state version](#room-state-versions) its code writes.
- `settings` is what `irt.config.ts` declares; it becomes the project's
  when the build goes live. See [Settings](/docs/cli#settings).

An upload is refused when the tarball is over 100 MB, unpacks to more
than 250 MB or 5,000 files, or `room/` is over 50 MB.

## The schema hash

A client connects with the hash of the schema it was built with, and is
closed with 4004 unless the hash is exactly that of its room's type in
its room's build: the live build's, or an older build's for a room that
still runs one.
There is no compatibility between schemas: adding a field, renaming one,
changing a type, a writable list or the order of `entities` all change
the hash.

That's safe for a web client because **a build's site goes live with its
room code**. A page loaded before a deploy has the old client; when it
next connects, or reconnects, it gets 4004, and reloading loads the new
site, which matches. So a web client handles a deploy like this:

```ts
// deploy-reload.ts
import { CloseCode, connect, defineSchema, IrtError, reloadForNewBuild } from "@irt/client";

const schema = defineSchema({});

async function join(room: string) {
  try {
    const client = await connect({ router: "wss://eu.irt.io", project: "my-game", room, schema });
    client.on("closed", (e) => {
      if (e.code === CloseCode.SchemaMismatch) reloadForNewBuild();
    });
    return client;
  } catch (e) {
    if (e instanceof IrtError && e.code === CloseCode.SchemaMismatch) reloadForNewBuild();
    throw e;
  }
}

await join("main");
```

A build that doesn't change the schema keeps its hash, so connected
clients carry on through it.

Clients that don't come from the site, such as bots, load tests and
native clients, must be rebuilt against the new schema and deployed with
it. Import the room's own schema module in them; see
[Node clients and bots](/docs/guides/node-client).

A room still running an older build, under `buildUpdate: "hibernate"`,
keeps accepting the old site's clients and refuses the new site's with
4004, naming both hashes, until it moves to the live build. Rooms move
once they hibernate, 30 seconds after their last player leaves. Reloading
doesn't help a new client in that window, since it loads the same site,
so reload once for 4004 rather than in a loop: `reloadForNewBuild()`, as
above, reloads at most once until a connection succeeds. If a build changes the
schema, have the room call `room.requestHibernate()` between rounds to
move sooner; see [When a build goes live](#when-a-build-goes-live).

## When a build goes live

Making a build live, with `irt deploy`, the dashboard or
`POST /projects/{p}/builds/{id}/live`, does three things:

1. The site at `<slug>.irt-serve.com` serves the new build's files. Every
   edge server picks it up within 10 seconds; see [Sites](/docs/sites).
2. The settings the build declares become the project's.
3. Every room that wakes from then on wakes on the new build.

Running rooms follow `rooms.buildUpdate`:

| Value | Running rooms |
|---|---|
| `"hibernate"` (default) | Stay on their build until they next hibernate, then wake on the new one |
| `"restart"` | Hibernate and wake on the new build straight away; clients reconnect with 4008 |

With `"restart"`, each room saves its room state as it hibernates, as it
would when idle, so nothing is lost. Rooms move a few at a time, 20 a
second on each host, so a deploy doesn't stall every room at once. A room
that is waking or hibernating as the build goes live still ends up on the
new build. A client loaded from the old site reconnects to the room on
the new build; if the schema changed it gets 4004 and reloads.

A room on an old build keeps running it as long as players stay. A game
that needs everyone on the new build soon after a deploy can have the room
call `room.requestHibernate()` when it's between rounds; its clients
close with 4011 and the next connection wakes it on the new build.

To move running rooms onto the live build whenever you choose, run
`irt restart`, use **Restart rooms** in the dashboard, or call
`POST /projects/{p}/restart` with `{}` or `{"room": "<id>"}`. It works
like `"restart"` above whatever `rooms.buildUpdate` says, and also
restarts rooms already on the live build.

## Room state versions

Room state carries a version, `version` in `defineRoom`, default 1. A
build that changes what's saved in a way old room state doesn't fit
increments it and adds an up migration:

| Change | Migration needed |
|---|---|
| Add a field to a kind | No; old room state loads with the field's default |
| Add a kind | No |
| Widen a number type: `u8` to `u16`, `u32`, `i16`, `i32`, `f32` or `f64`; `u16` to `u32`, `i32`, `f32` or `f64`; `i8` to `i16`, `i32`, `f32` or `f64`; `i16` to `i32`, `f32` or `f64`; `u32`, `i32` or `f32` to `f64` | No; every old value fits |
| Change which fields are writable or owner-only | No |
| Rename the shared or private state's kind | No; room state stores them by position |
| Remove or rename a field | Yes: old room state has a field the build doesn't declare |
| Remove or rename an entity kind | Yes; convert or drop those entities |
| Any other type change, such as `u16` to `u8` or `string` to `json` | Yes |
>>>

| Change what the stepper's `save` returns | Yes; convert `data.stepper` |

The control server enforces the rows that say yes, except the stepper's,
which it can't see; see
[The schema check at deploy](#the-schema-check-at-deploy). Any schema
change still changes the hash, migration or not.

A migration takes the room state as plain data at one version and
returns it at the next. `migrations[2]` turns version 1 into version 2:

```ts
// room-v3.ts
import { defineRoom, defineSchema, entity, json } from "@irt/room";

// v1: player { hp: "u8" }. v2: hp renamed to health, a u16.
// v3: the shared state's scores, a json map, gains a round counter.
const Player = entity("player", { owner: "string", health: "u16" });
const Match = entity("match", { scores: json<Record<string, number>>(), round: "u16" });

export default defineRoom({
  schema: defineSchema({ state: Match, entities: [Player] }),
  version: 3,
  migrations: {
    2: (data) => ({
      ...data,
      entities: data.entities.map((e) =>
        e.kind === "player" ? { ...e, values: { owner: e.values.owner, health: e.values.hp } } : e,
      ),
    }),
    3: (data) => ({ ...data, state: { ...data.state, round: 1 } }),
  },
});
```

`RoomData` is in the [Room SDK reference](/docs/reference/room-sdk#room-state-and-migrations):
`state`, `private` by player ID, `entities` with `id`, `kind`, `values`
and `owner`, `stepper`, and the tick and IDs. Room state records the
declarations it was written with, so a migration sees the old field
names and values.

When a room wakes on a build whose `version` is higher than its room
state's, each migration runs in turn, before `onWake`. A migration that
throws, a missing step, or a result that doesn't fit the build's
declarations stops the room with a reason saying which; see
[Errors](/docs/reference/errors#in-the-room). Migrations run only on
wake, so a room that never wakes again is never migrated.

Test a migration by waking a room from old room state; see
[Testing rooms](/docs/guides/testing#migrations).

### The schema check at deploy

When a build goes live, from `irt deploy`, `irt rollback`, the dashboard
or the API, the control server compares each room type's `schema` and
`stateVersion` with the live build's type of the same name. Shared and private state are compared by
position, entity kinds and fields by name, so reordering them changes
nothing. The result is one of:

| Result | When | Goes live |
|---|---|---|
| `unchanged` | Same `version`, and nothing room state depends on changed | Yes |
| `compatible` | Same `version`, and only changes the table above needs no migration for | Yes |
| `migrated` | A higher `version`; the build's migrations convert room state on wake | Yes |
| `rollback` | A lower `version`; see [Rolling back](#rolling-back) | Yes |
| `unchecked` | One of the builds was uploaded before builds carried their schema | Yes |
| `no_room_state` | Same `version`, and a change that needs a migration, but no room the project keeps holds room state at that version: every room is new, deleted, or hibernated at an older version, which the build's migrations convert | Yes |
| refused | Same `version`, a change that needs a migration, and a room that holds room state at that version or may be running | No: `409`, code `schema_change` |

`irt deploy` prints the result for each type and each change:

```text
deployed build b_01J9Z3 to space-race; it's live
room state of type default: version 1 to 2; rooms run this build's migrations when they wake:
  removed player.hp (u8), so room state that has it won't load
  added player.health (u16); room state without it loads with its default value
```

A refused build stays uploaded and the live build stays live. The error
names each breaking change and the fix: bump `version` in `defineRoom`
and add the migration to it. A renamed field or kind shows as a removal
plus an addition, so the migration moves the old values to the new name.
A higher `version` with no schema change is fine, for a migration that
changes values only.

The check can't tell whether your migrations exist or are right; a room
whose migration is missing stops on wake. Test them as above.

### Adding and removing room types

A room's type is set when it's created and never changes, so each type's
room state is checked against its own earlier versions only. A build
may add types freely. A build that drops a type is refused with `409`,
code `type_removed`, naming the type, while any room of that type has a
record, since those rooms could never wake; delete them first, or keep
the type. Renaming a type is dropping one and adding another.

### What's kept

When a room first saves room state after a migration, IRT copies the
room state from before the migration aside and keeps the copy for 7
days. If you roll back to a build with a lower `version`, rooms restore
it on their next wake, losing what happened in the room since; see
[Rolling back](#rolling-back).

## Rolling back

`irt rollback` makes the build before the live one live again, or the
build you name; the dashboard can too. The site and the settings roll
back with it, and rooms then wake on the earlier build.

Migrations only go up, so a room that already woke on a build with a
higher `version` holds room state the earlier build can't read. On its
next wake it starts instead from the room state kept from before its
migration, losing progress since then, and the project gets a
`room.restored` [webhook](/docs/webhooks). A room with none kept,
because it was created on the newer build or its copy is over 7 days
old, fails to wake with the reason in `irt logs` until a build that reads
its version is live again.

To keep rooms' progress across a rollback past a version change, deploy
a new build with the old code and the new `version` and its migrations
instead.

Rolling back to a build at the same `version` is safe when the schema
check allows it. Rolling back past a build that added a field or kind,
without a `version` bump, is refused: rooms that woke on it saved room
state with that field, which the earlier build can't load. Deploy a new
build with the old code and the new schema instead.

## Automatic rollback

A build that crashes over and over soon after it goes live is rolled
back for you: the build it replaced goes live again, through the same
make-live as `irt rollback`, with the same schema check and room state
restore.

A crash is tenant code failing: a room stopped by an exception in room
code, or a room host that exited, such as from a throw while the room
code loads. Our own stops, such as a host draining for an upgrade or an
idle VM stopping, don't count. A build crash-loops when it has 5 crashes
within 5 minutes, counted across the region, in its first hour live.

The rollback happens only when:

- `rooms.rollbackOnCrashLoop` is on, as it is by default. Turn it off in
  the dashboard or with `settings: { rooms: { rollbackOnCrashLoop: false } }`
  in `irt.config.ts`.
- The build it replaced ran clean: it never crash-looped itself, and it
  had fewer than 5 crashes in its last 5 minutes live.
- The live build hasn't been rolled back before. Each build rolls back
  at most once, so making it live again by hand sticks.

The build is marked rolled back, with the reason, in the dashboard's
builds list, in `irt status` and as `rolledBack` in
`GET /projects/{p}/builds`, and your backend gets a
[`build.rolled_back`](/docs/webhooks) webhook. Running rooms move as
`rooms.buildUpdate` says; rooms whose code crashes restart on the build
that's live when they wake again, so crashing rooms move straight away.
Fix the bug and deploy a new build.

## Deploying from CI

Run tests, then deploy with a project API key from the dashboard in
`IRT_TOKEN`. The key acts for its one project.

```yaml
# .github/workflows/deploy.yml
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
      - run: npm ci
      - run: npx irt test
      - run: npx irt deploy
        env:
          IRT_TOKEN: ${{ secrets.IRT_TOKEN }}
```

`irt deploy --no-live` uploads without going live, so a later step, or a
person in the dashboard, can make it live.

## Common mistakes

- **Deploying the room without its site.** A site client built against
  the old schema gets 4004 from every room on the new build. Keep the site
  in the same build: set `site` in `irt.config.ts`.
- **Reloading on every close.** Only 4004 means a new build; see
  [Errors](/docs/reference/errors).
- **Renaming or removing a field without a migration.** The control
  server refuses the build. Bump `version` and convert the room state in
  a migration.
- **Editing an old migration.** Rooms that already ran it won't run it
  again. Add a new version instead.
- **Rolling back past a version change.** Migrated rooms stop on the old
  build. Roll forward instead.
- **Expecting `"restart"` to be instant.** Rooms move at 20 a second on
  each host; a host with 2,000 rooms of the project takes 100 seconds.

---

# Sites

> How a build's web client is served from <project>.irt-serve.com and by irt dev, with caching, single-page app routes, cross-origin isolation and the reserved /api path.

A build can carry the project's **site**: its web client's static files.
The live build's site is served at `https://<slug>.irt-serve.com`, and
`irt dev` serves it locally the same way, so a client always finds the
room code it was built against.

## Adding a site

```ts
// irt.config.ts
import { defineConfig } from "@irt/cli/config";

export default defineConfig({
  project: "space-race",
  room: "src/room.ts",
  site: { dir: "dist", build: "npm run build:web", crossOriginIsolated: false },
});
```

`irt build`, `irt deploy` and `irt dev` run `site.build`, if given, from
the project's directory, then take every file under `site.dir`. Use any
bundler: Vite, esbuild, or none. A project without `site` deploys room
code only.

## How files are served

- `/` and any path ending in `/` serve that directory's `index.html`.
- A path with no file extension that isn't a file, such as
  `/rooms/forest-7`, serves `/index.html`, so a single-page app's client
  side routes work. A missing path with an extension is a 404.
- Only `GET` and `HEAD`; anything else is 405.
- Content types come from the extension: HTML, JavaScript, CSS, JSON,
  source maps, images, fonts, audio, video, `.wasm`, and `.glb` and
  `.gltf` models. Other files are `application/octet-stream`. Every
  response has `X-Content-Type-Options: nosniff`.
- HTML is served with `Cache-Control: no-cache`, so browsers check for a
  new version on every load; everything else with `public, max-age=300`.
  Give bundles hashed file names, as most bundlers do, so a new build's
  HTML never loads an old build's scripts.
- When a build goes live, every edge server serves it within 10 seconds.

`irt-serve.com` is the user content domain: tenant content is never
served from `irt.io`. Custom domains aren't available yet.

### Cookies and storage

Until `irt-serve.com` is on the Public Suffix List, browsers treat every
`*.irt-serve.com` project as one site for cookies: another project's
page can set a cookie that yours receives. Name your own cookies with the
`__Host-` prefix, which a sibling subdomain can't set. `localStorage` and
other storage are per origin, so they're your project's alone already.

## Cross-origin isolation

`site.crossOriginIsolated: true` serves the site with

```text
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
```

which make the page cross-origin isolated. That's what
`SharedArrayBuffer`, Wasm threads and precise timers need, such as for a
physics engine running in workers. The cost: the page can then load a
cross-origin resource only if it opts in, with
`Cross-Origin-Resource-Policy: cross-origin` or CORS and a `crossorigin`
attribute. Fonts, images and scripts from a CDN that doesn't send those
headers stop loading, and so do iframes and popups from other origins.
Serve such files from the site itself, or leave the flag off.

The flag is part of the build, so it changes when a build goes live and
rolls back with it.

## /api is reserved

`/api` and every path under it answer 404 with

```json
{ "error": { "code": "not_found", "message": "No backend is deployed for this project" } }
```

whatever files the site has. The path is kept for backends hosted on the
site's own origin, so don't put site files under `/api/`; a file there is
never served.

## irt dev

`irt dev` serves the site and the local room host on one origin,
`http://127.0.0.1:7350` by default (`--port` changes it):

| Path | Serves |
|---|---|
| `/v1/ws` | The client protocol over WebSocket |
| `/v1/rooms`, `/v1/codes/...` | The client HTTP API that `createRoom`, `joinByCode` and `listPublic` use |
| `/api`, `/api/...` | 404, as deployed |
| anything else | The site, as deployed: `index.html` fallback and COOP and COEP when the build asks for them |

Locally every response is `Cache-Control: no-store`, so a rebuild shows
on the next reload. `irt dev` reruns `site.build` and restarts the room
host when a project file changes; connected clients reconnect. Paths
under `/v1/` belong to the room host, so keep site files out of a `v1`
directory.

Because both are on one origin, a client can pick its router by where
it's served from:

```ts
// router.ts
export const router = location.hostname.endsWith(".irt-serve.com") ? "wss://eu.irt.io" : location.origin;
```

`irt deploy` prints the router the project's clients use.

## Common mistakes

- **Hard-coding `http://127.0.0.1:7350` as the router.** The deployed site
  then can't connect. Choose by `location`, as above.
- **Turning on `crossOriginIsolated` with assets on another origin.**
  They stop loading unless they send CORP or CORS headers.
- **Bundles without hashed names.** They're cached for 5 minutes, so a
  page can mix a new `index.html` with old scripts.
- **Files under `/api/`.** They're never served.
- **Deploying the site separately from the room.** Sites deploy only with
  their build, which is what keeps clients and rooms on one schema; see
  [Builds and deploys](/docs/builds#the-schema-hash).

---

# Moderation

> Kick and ban players from room code, ban them from a project, and kick or mute them from your backend, the dashboard or the CLI.

A room can kick a connection and ban a player from itself in room code,
which suits games where players run their own rooms. To act from outside
a room, from your backend, the dashboard or the CLI, use bans, kicks and
voice moderation through the [HTTP API](/docs/http-api). Each takes an
API key, a personal token or a dashboard session.

Players are named by their player ID: your [player
token's](/docs/player-tokens) `sub`, or a guest's `guest:` ID. A room
sees it as `connection.player`.

## In room code

| Call | Close code | Kept | Scope |
|---|---|---|---|
| `room.kick(conn, reason?)` | 4006 | no; the player can join again | one connection |
| `room.ban(player, { reason?, expiresAt? })` | 4014 | in room state, across hibernation | this room |
| A project ban, below | 4013 | by the control server | every room of the project |

The client sees the code as `IrtError.code` and the room's `reason` as
`IrtError.reason`, so it can say why. A banned player is turned away
before `onJoin` runs, and never shows in other clients' presence; so is a
connection the room kicks in `onJoin` before any `await`.

This room lets its owner, the player whose token says so, kick and ban,
and turns banned players away with a message:

```ts
// moderated-room.ts
import { CallRejected, defineCalls, defineRoom, defineSchema, entity } from "@irt/room";

const calls = defineCalls<{
  ban(args: { player: string; reason: string; hours?: number }): null;
  unban(args: { player: string }): boolean;
}>();
const schema = defineSchema({ state: entity("lobby", { topic: "string" }), calls });

const isOwner = (meta: unknown) => (meta as { owner?: boolean } | null)?.owner === true;

export default defineRoom({
  schema,
  calls: {
    ban(room, conn, { player, reason, hours }) {
      if (!isOwner(conn.meta)) throw new CallRejected("only the room's owner can ban");
      room.ban(player, { reason: reason.slice(0, 100), expiresAt: hours ? Date.now() + hours * 3600_000 : undefined });
      return null;
    },
    unban(room, conn, { player }) {
      if (!isOwner(conn.meta)) throw new CallRejected("only the room's owner can unban");
      return room.unban(player);
    },
  },
});
```

On the client, tell kicked and banned players apart:

```ts
// closed.ts
import { CloseCode, type RoomClient } from "@irt/client";

export function onClosed(room: RoomClient, show: (text: string) => void) {
  room.on("closed", (e) => {
    if (e.code === CloseCode.RoomBanned) show(`You're banned from this room${e.reason ? `: ${e.reason}` : "."}`);
    else if (e.code === CloseCode.Kicked) show(`You were removed${e.reason ? `: ${e.reason}` : ""}. You can rejoin.`);
    else if (e.code === CloseCode.Banned) show("You're banned from this game.");
  });
}
```

To hide players from each other, such as after a block, give the room
`seesPresence(room, viewer, entry)` beside an interest `sees`: presence
then follows the same rule as entities. See
[Presence](/docs/reference/room-sdk#presence).

Room code mutes a player's voice with `room.muteVoice(player, {
expiresAt })`, kept in room state like a ban: the room leaves the player
out of every listener's speakers, and the voice server stops it
publishing until the mute ends. See
[Proximity voice](/docs/guides/proximity-voice#muting-a-player). Room
code has no call for project bans; call the HTTP API from your backend.

## Bans

A ban keeps a player out of every room of the project, for good or until
it expires.

```sh
curl -X POST https://api.irt.io/v1/projects/my-game/bans \
  -H "Authorization: Bearer $IRT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"player": "u_42", "reason": "cheating", "expiresAt": "2026-11-11T00:00:00Z"}'
```

- The router refuses a banned player's connections with close code
  4013, which the client SDK doesn't retry. Connections the player has
  when the ban is made close with 4013 within a few seconds.
- With a banned player's token, the client HTTP API's room creation,
  join code lookup and public room list answer `403` with code `banned`.
- `expiresAt` is optional; without it the ban is permanent. Once it
  passes, the player can connect again.
- Banning a player again replaces the ban's reason and expiry.
- A project can have 10,000 active bans. Expired bans don't count.

Banning a guest keeps out only that guest ID, and a guest gets a new one
by clearing the browser's storage. A game that needs bans to stick should
sign its own player tokens and turn guests off.

On the client, tell a banned player why they can't join:

```ts
// banned.ts
import { CloseCode, connect, defineSchema, entity, IrtError } from "@irt/client";

const schema = defineSchema({ state: entity("table", { players: "u8" }) });

try {
  const room = await connect({ router: "wss://eu.irt.io", project: "my-game", room: "main", schema });
  room.on("closed", (error) => {
    if (error.code === CloseCode.Banned) console.log("you were banned from this game");
  });
} catch (e) {
  if (e instanceof IrtError && e.code === CloseCode.Banned) console.log("you are banned from this game");
  else throw e;
}
```

## Kicks

A kick closes a player's connection to one room with close code 4006,
the same as `room.kick`. The client doesn't reconnect by itself, but the
player can join again; ban them to keep them out.

```sh
curl -X POST https://api.irt.io/v1/projects/my-game/rooms/forest-7/kick \
  -H "Authorization: Bearer $IRT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"player": "u_42"}'
```

It answers `204`, or `404` when the player isn't connected to the room.

## Voice

With [proximity voice](/docs/guides/proximity-voice) on, a player's voice
can be muted for everyone in a room, or the player disconnected from the
room's voice:

| Path | Body | Does |
|---|---|---|
| `POST /projects/{p}/rooms/{id}/voice/mute` | `{player, muted}` | Mutes or unmutes the player's microphone |
| `POST /projects/{p}/rooms/{id}/voice/remove` | `{player}` | Disconnects the player from the room's voice |

Both answer `204`, or `404` when the player isn't in the room's voice.
The mute applies to the player's tracks as they are, and its client can
unmute them; for a mute that holds, have the room call `room.muteVoice`.
Removing a player from voice doesn't stop them rejoining it with their
voice token; kick or ban them for that.

## In the dashboard and the CLI

The dashboard's Bans tab lists a project's bans and adds and removes
them, and each active room on the Rooms tab has a Moderate panel for
kicks and voice. In a terminal:

```sh
irt bans list
irt bans add u_42 --reason cheating --for 7d
irt bans remove u_42
```

---

# Player tokens

> How your backend tells IRT who a player is, with JWTs signed by the project's signing keys, and how guests work without one.

A player token tells the router who a player is and what they may join.
Your backend signs it after it has authenticated the player its own way;
IRT never sees your users' passwords or sessions.

Projects without a backend can let players join as guests instead.

## The token

A player token is a JWT signed with HS256 using one of the project's
signing keys.

| Claim | Required | Meaning |
|---|---|---|
| `sub` | yes | The player ID you choose: 1 to 128 bytes, not starting with `guest:` |
| `prj` | yes | The project's slug |
| `exp` | yes | Expiry, at most 24 hours after `iat` |
| `iat` | yes | When the token was issued |
| `room` | no | The only room this token may join |
| `meta` | no | JSON up to 1 KB, passed to the room's `onJoin` |

The player ID is how the room, webhooks and voice know the player, and it
stays the same across reconnects. A player has one connection per room:
when the same player ID connects again, the older connection is closed.

Player IDs are public. Other players in the room see them as entity
owners, as voice identities and in anything the room sends. If your
backend knows players by email address or an internal account ID, give
each player an opaque ID for `sub` instead.

Use `room` when your backend decides who goes where, so a token for one
room can't be used to join another. Use `meta` for data the room needs
on join and shouldn't trust from the client, such as a display name or a
team.

## Signing keys

Create signing keys in the dashboard, under the project's keys, with
`irt signing-keys create`, or with `POST /projects/{p}/signing-keys`.
The secret is shown once. Store it on
your backend.

To rotate, create a second key, move your backend to it, then delete the
first. Tokens signed with either key are accepted while both exist.

## Signing a token

`@irt/server` signs tokens with WebCrypto, so it runs in Node, Deno, Bun
and edge workers:

```ts
import { playerToken } from "@irt/server";

export function tokenFor(player: { id: string; name: string }, room?: string): Promise<string> {
  return playerToken({
    key: process.env.IRT_SIGNING_KEY!,
    project: "my-game",
    player: player.id,
    room,
    meta: { name: player.name },
  });
}
```

`room` and `meta` are optional. The token lasts 24 hours unless
`lifetime` sets fewer seconds; the client SDK reconnects with the same
token, so a short lifetime ends a long session at its next reconnect.
`playerToken` throws a `TypeError` for a player ID, `meta` or lifetime
the router would refuse. Any JWT library that does HS256 works too, with
the secret's UTF-8 bytes as the key.

Hand the token to your client, which passes it to the client SDK when it
connects. A token that is invalid or expired closes the connection with
close code 4001.

## Guests

When the project's `players.guests` setting is on, a client can connect with
no token. The router then creates a guest player ID, starting with
`guest:`, and returns a guest token to the client. The client SDK keeps
it in the browser's `localStorage` and sends it on every connect, so a
guest keeps the same player ID across reconnects, tabs and browser
restarts, and with it the entities it owns, its private state and its
voice identity. The token lasts 30 days and is renewed on each connect;
a guest away longer than that comes back as a new guest.

Guests suit games with no accounts. Turn `players.guests` off when every
player must come through your backend.

## Rooms without a backend

Three more settings let clients manage rooms themselves:

- `players.createRooms`: clients may create rooms and join them by a 6-character
  join code, and connecting to a room that doesn't exist creates it.
- `players.listPublic`: clients may list active public rooms, with their player
  count and `meta`. Hibernated rooms have no players and aren't listed.
  With `players.guests` off, listing needs a player token too, unless
  `players.listPublicWithoutToken` is on, which lets anyone list them.
- `players.quickJoin`, off by default: clients may join any public room with
  space whose `meta` matches, or a new public room when none has space. See
  [quickJoin](/docs/reference/client-sdk#http-helpers-for-games-without-a-backend).
  It's for filling rooms with whoever comes; matchmaking by skill, parties
  and queues is your backend's.

With `players.createRooms` off, only your backend creates rooms, through the
[HTTP API](/docs/http-api#rooms). [Games without a backend](/docs/no-backend)
shows how a client uses these settings.

---

# Games without a backend

> Ship a game with no server of your own, with guest players, rooms clients create, join codes and a list of public rooms.

A game doesn't need a backend on IRT. Players join as **guests**, and
clients create rooms, share join codes and browse public rooms
themselves, through three helpers in `@irt/client`. Each part is a
project setting, on by default:

| Setting | Default | Lets clients |
|---|---|---|
| `players.guests` | `true` | Connect, and use the helpers below, with no player token |
| `players.createRooms` | `true` | Create rooms with `createRoom`, or by connecting to a room ID that doesn't exist, and find them with `joinByCode` |
| `players.listPublic` | `true` | List active public rooms with `listPublic` |

Listing needs a player token when guests are off. A game whose rooms
require a login but whose room directory is public, such as a lobby
page, turns on `players.listPublicWithoutToken`: then `listPublic` works
with no token, while connecting still needs one.

Set them in [`irt.config.ts`](/docs/cli#settings). Turn one off and the
matching calls fail with 403, or 4001 for a guest's connection, so a
project can move to a backend one part at a time.

A player's progress, what players make and high score tables need no
backend either: [player data, collections and
leaderboards](/docs/guides/player-data) are kept per project, and a
guest is the same player in rooms and in data calls.

## Guests

A client that connects without a `token` is a guest. The router gives it
a player ID starting with `guest:` and a guest token, which the client
SDK keeps and sends on every connect:

- It's kept in `localStorage` under `irt.guest.<project>`, so a guest is
  the same player across reconnects, reloads, tabs and browser
  restarts, and keeps its private state, the entities it owns and its
  voice identity.
- It lasts 30 days, and each connect renews it with the same player ID,
  so only a guest away for 30 days comes back as a new one. A token that
  has expired, or that the router can't verify, starts a new guest
  rather than failing.
- Where `localStorage` is missing or blocked, as in Node or some private
  windows, the token is kept in memory: the guest lasts as long as the
  client object, across its reconnects.

Because every tab of a browser is the same guest, two tabs in one room
are one player: the newer connection closes the older with 4012. Test
two players with a private window or another browser, and tell players
who see 4012 that they're playing elsewhere.

Guests are anonymous. Anyone can become a new guest at any time by
clearing storage, so don't give a guest anything worth farming, and
treat what a guest sends as untrusted, as you would any client's.

## Creating and joining rooms

With `players.createRooms` on, connecting to a room ID that doesn't
exist creates the room, deployed as under `irt dev`: a private room with
no join code at the project's `rooms.size`. The connection waits while
the room starts, as for a wake. It counts against the address's 10
creates a minute, like `createRoom`; past that the connection closes
with 4005 and the client retries after backoff. With the setting off,
connecting to a room that was never created closes with 4002, and rooms
are created by you with `irt rooms create <id>` or by a backend through
the [HTTP API](/docs/http-api#rooms).

Use `createRoom` for a room with a join code, a public room, `meta` or
`maxPlayers`:

```ts
function createRoom(opts: {
  router: string; project: string; token?: string;
  id?: string;           // default: a random 12-character ID
  type?: string;         // the room type; default the build's type named default
  public?: boolean;      // listed by listPublic while it's active; default false
  joinCode?: boolean;    // give it a 6-character join code; default false
  meta?: unknown;        // JSON up to 1 KB, returned by listPublic
  maxPlayers?: number;   // cap on connections, 1 to the room size's limit; default the limit
}): Promise<{ id: string; joinCode: string | null }>;

function joinByCode(opts: { router: string; project: string; token?: string; code: string }): Promise<string>;
function listPublic(opts: { router: string; project: string; token?: string; type?: string }): Promise<PublicRoom[]>;
// maxPlayers is the room's own limit, else its size's connection limit
interface PublicRoom { id: string; type: string; players: number; maxPlayers: number; meta: unknown }
```

A room menu with all three:

```ts
// rooms-menu.ts
import { connect, createRoom, joinByCode, listPublic, type RoomClient } from "@irt/client";
import { schema } from "./schema.js";

const router = location.hostname.endsWith(".irt-serve.com") ? "wss://eu.irt.io" : location.origin;
const project = "my-game";

/** Creates a private room and returns its join code for the host to share. */
export async function host(): Promise<{ room: RoomClient; code: string }> {
  const { id, joinCode } = await createRoom({ router, project, joinCode: true });
  return { room: await connect({ router, project, room: id, schema }), code: joinCode! };
}

/** Joins the room a friend's code names. */
export async function join(code: string): Promise<RoomClient> {
  return connect({ router, project, room: await joinByCode({ router, project, code }), schema });
}

/** Opens a public room others can find, described by its meta. */
export async function open(mode: string): Promise<RoomClient> {
  const { id } = await createRoom({ router, project, public: true, meta: { mode } });
  return connect({ router, project, room: id, schema });
}

/** The public rooms with space, fullest first. */
export async function browse(max: number) {
  const rooms = await listPublic({ router, project });
  return rooms.filter((r) => r.players < max).sort((a, b) => b.players - a.players);
}
```

```ts
// schema.ts
import { defineSchema, entity } from "@irt/client";

export const schema = defineSchema({ state: entity("scoreboard", { round: "u16" }) });
```

- **Room IDs.** Leave out `id` and the router picks a random one, which
  is hard to guess. Anyone who knows a room's ID can connect to it while
  guests are allowed, so a private room's ID should stay private; share
  its join code instead.
- **Join codes** are 6 characters of `A-H`, `J-N`, `P-Z` and `2-9`, with
  no `I`, `O`, `0` or `1`. `joinByCode` takes them in any case and with
  spaces around them. A code lasts as long as its room; after the room is
  deleted the code gives 404. Room code reads it as `room.joinCode`, for
  example to put it in `room.state` so players who join later, and a
  host who reloads, can show it in the lobby.
- **Public rooms** are listed only while active, with their player count
  and `meta`. A hibernated room has no players and isn't listed, so a
  public room that empties drops off the list until someone connects to
  it again. `meta` is set at creation and doesn't change; keep what
  changes, such as a round or a map, in `room.state`.
- **Who's in a room** is the room's business: the room decides in
  `onJoin` whether to keep a connection, and can `room.kick` it, which
  closes it with 4006. Room size caps the connections, and `maxPlayers`
  caps them lower, such as 2 for a duel; past either clients get 4003.
  A player who reconnects takes their own place and doesn't count twice.

## A ready-made room screen

For a room screen without writing one, the [UI kit](/docs/ui-kit) in
`@irt/client/ui` has custom elements that use the helpers above:
`<irt-room-panel>` with create, join by code and quick join buttons, the
room's join code with a share link and QR code, the connection status,
the players and a name field; `<irt-room-browser>` for the public rooms;
`<irt-invite>`, `<irt-lobby>`, voice controls, a network indicator and a
join loader. They show the router's message when a setting is off.

## Rooms that come and go

Client-created rooms pile up unless something deletes them.
`rooms.retention` deletes a room after it has been hibernated that long:

| `rooms.retention` | Suits |
|---|---|
| `"none"` | Rooms that matter only while players are in them, such as a single round; deleted 30 seconds after the last player leaves |
| `"7d"` (default), `"<n>h"`, `"<n>d"` | Rooms players come back to, such as a party's room or a saved game |
| `"forever"` | Rooms that are places, such as a persistent world |

A project can hold at most `limits.maxRooms` rooms, 1,000 by default, so
retention matters most for games where every round creates a room. Over
it, `createRoom` fails with 429 until rooms expire. See
[Limits](/docs/limits#project-settings-with-limits).

## Errors

Each helper rejects with an `IrtError` whose `code` is the HTTP status:
403 when the setting is off, 404 for an unknown join code, 409 for an
`id` that's taken, 429 when rate limited or at `maxRooms`. The full list
is in [Errors and close codes](/docs/reference/errors#the-http-helpers).

## Testing

`@irt/testing`'s host has the same three calls, with the project's
settings applied, so a test can walk through a room menu without a network:

```ts
// rooms-menu.test.ts
import { defineRoom, defineSchema, entity } from "@irt/room";
import { createTestHost } from "@irt/testing";
import { expect, test } from "vitest";

const room = defineRoom({ schema: defineSchema({ state: entity("scoreboard", { round: "u16" }) }) });

test("a friend joins by code, and a public room is listed while it's active", async () => {
  const host = createTestHost(room);
  const { id, joinCode } = await host.createRoom({ joinCode: true });
  const alice = await host.room(id).connect({ player: "alice" });
  const bob = await host.room(await host.joinByCode(joinCode!.toLowerCase())).connect({ player: "bob" });
  expect(bob.client.connection).not.toBe(alice.client.connection);

  const open = await host.createRoom({ public: true, meta: { mode: "duel" } });
  expect(await host.listPublic()).toEqual([]);
  await host.room(open.id).connect({ player: "carol" });
  expect(await host.listPublic()).toEqual([{ id: open.id, players: 1, maxPlayers: 64, type: "default", meta: { mode: "duel" } }]);
});

test("clients can't create rooms when the setting is off", async () => {
  const host = createTestHost(room, { settings: { players: { createRooms: false } } });
  await expect(host.createRoom()).rejects.toMatchObject({ code: 403 });
});
```

See [Testing rooms](/docs/guides/testing) for more.

## Adding a backend later

Accounts come from your own backend, which signs
[player tokens](/docs/player-tokens). Pass a token to `connect` and to the
helpers, and that client is a known player rather than a guest. Turning
`players.guests` off then requires one; turning `players.createRooms`
off leaves room creation to the backend, through the HTTP API.

## Common mistakes

- **Turning `players.createRooms` off and connecting to a fixed room ID.**
  Nothing creates the room any more, so connecting gives 4002. Create it
  with `irt rooms create` or from your backend.
- **Testing two players in two tabs.** They're the same guest; the newer
  tab closes the older with 4012. Use a private window.
- **Expecting a public room to stay listed while empty.** It hibernates
  30 seconds after its last player leaves and drops off the list.
- **Trusting a guest.** A guest ID costs nothing to replace. Validate
  messages in the room and keep anything valuable behind player tokens.
- **Leaving retention at 7 days for throwaway rooms.** Every such
  room counts toward `maxRooms` until it expires. Use `"none"`.

---

# UI kit

> Framework-free custom elements for the screens every multiplayer project needs: invites, a room browser, a room panel, a lobby, voice settings and voice chat, a network indicator and a join loader, sharing one theme and opening inline or as a dialog.

The UI kit is a set of custom elements for the screens a project
without a backend needs, and that are easy to get subtly wrong:
inviting friends, finding a room, a lobby, voice controls, a loading
state and a sign that the connection is bad. Each works in plain HTML
and in any framework that renders custom elements, renders in a shadow
root, is built for phones as well as desktops, and shares one theme
with the others.

| Element | Shows | Entry |
|---|---|---|
| `<irt-invite>` | The join code, a copy button for the share link, and optionally a QR code | `@irt/client/ui/invite` |
| `<irt-room-browser>` | The project's public rooms of a type, with players out of max, and refresh, join, create and quick join | `@irt/client/ui/room-browser` |
| `<irt-room-panel>` | An invite, the connection status, the players, a name field, and create, join and quick join | `@irt/client/ui/room-panel` |
| `<irt-lobby>` | An invite, the lobby's players, ready flags and leader, ready, start and cancel, the countdown and failures | `@irt/client/ui/lobby` |
| `<irt-voice-settings>` | Microphone on or off, devices, an input level meter, push-to-talk and its key | `@irt/client/ui/voice-settings` |
| `<irt-voice-chat>` | The other players in voice, each with a speaking indicator, a volume slider and a mute button | `@irt/client/ui/voice-chat` |
| `<irt-network>` | Signal bars and the round trip; opened, the transport, round trip, jitter and traffic | `@irt/client/ui/network` |
| `<irt-join-loader>` | A small animation while joining, then how long it took | `@irt/client/ui/join-loader` |

Each element below has a screenshot in the light and dark defaults, and
the [gallery](/docs/ui-kit/gallery) runs them all live in the browser,
with a made-up room, lobby and voice.

`@irt/client/ui` defines them all and exports `open`. Import an
element's own entry to pay only for what you use. `@irt/client/panel`
and `@irt/client/lobby` still define the room panel and the lobby.

Coming from the room panel page: `<irt-lobby>` now holds an
`<irt-invite>`, as `el.invite`, in place of its name field and create
and join buttons, and the `--irt-panel-*` custom properties are now the
`--irt-*` properties every element shares, under [Theming](#theming).

Every element takes its client, or its voice, as a property, its text as
`labels`, and fires events that bubble and cross the shadow root.

## Usage

The room panel finds the room and the project connects to it: on
`room-join`, create the `RoomClient` and give it to the panel, which
then shows its status and players. The network indicator and join
loader take the same client.

```html
<irt-room-panel router="wss://eu.irt.io" project="my-project" qr></irt-room-panel>
<irt-join-loader></irt-join-loader>
<irt-network style="position: fixed; top: 8px; right: 8px"></irt-network>
<script type="module" src="./main.js"></script>
```

```ts
// web/main.ts
import { type ReadyRoomClient, RoomClient } from "@irt/client";
import "@irt/client/ui";
import { schema } from "./schema.js";

const panel = document.querySelector("irt-room-panel")!;
const loader = document.querySelector("irt-join-loader")!;
const network = document.querySelector("irt-network")!;

panel.addEventListener("room-join", (e) => {
  panel.client?.leave();
  const client = new RoomClient({ router: panel.router, project: panel.project, room: e.detail.room, schema });
  panel.client = loader.client = network.client = client;
  client.ready.then(() => start(client as ReadyRoomClient<any, any, any>), () => {});
});

function start(client: ReadyRoomClient<any, any, any>): void {
  client.onTick((tick) => (document.title = `Round ${client.state.round} (tick ${tick})`));
}
```

```ts
// web/schema.ts
import { defineSchema, entity } from "@irt/client";

export const schema = defineSchema({ state: entity("scoreboard", { round: "u16" }) });
```

Give the elements a client made with `new RoomClient` rather than
awaiting `connect`, so they show the connection while it's still
connecting or starting the room, and why it failed if it does.

## Inline or dialog

Placed in the page, an element renders where it is. With the `dialog`
attribute it renders inside a `<dialog>` in its shadow root, closed
until `show()`, with a close button. `show()` opens it with
`showModal()`, so focus stays in it, the page behind is inert and Escape
closes it; focus returns to where it was. `close()` closes it, and the
element fires `close`.

For a one-off dialog, `open` appends the element to `<body>` as a
dialog, sets the properties given, shows it, and removes it on close.
It takes any element but `<irt-network>`:

```ts
// web/browse.ts
import { open } from "@irt/client/ui";

const browser = open("irt-room-browser", { router: "wss://eu.irt.io", project: "my-project" });
browser.addEventListener("room-join", (e) => {
  browser.close();
  console.log("joining", e.detail.room);
});
```

`<irt-network>` is the exception: it's small enough to sit in a corner
of the canvas, and clicking it opens its details in a popover.
`show()` and `close()` open and close that popover, and it takes no
`dialog` attribute.

## The elements

### `<irt-invite>`

![The invite, light](/ui-kit/invite-light.png) ![The invite, dark](/ui-kit/invite-dark.png)

The room's join code and share link, with a copy button, and with the
`qr` attribute a QR code for the link. The link is the current page
with `?code=<join code>`, or `?room=<room ID>` for a room without a
code, such as one from quick join. When the page opens with either, the
invite looks the room up and fires `room-join`, so the link a friend
scans lands in the room. The QR code is drawn as SVG by an encoder in
the package.

| Attribute or property | |
|---|---|
| `router`, `project` attributes | The router address, as for `connect`, and the project's slug, to look up a code |
| `qr` attribute | Show a QR code for the share link |
| `room`, `code` properties | The room ID and join code shown and linked to |
| `link` property | The share link, read-only |

Event: `room-join`, `{ room: string; joinCode: string | null }`.

Labels: `code`, `link`, `copy`, `copied`, `copyFailed` (the browser
refused the clipboard), `qr` (the QR code's accessible name) and
`close`. Parts: `room`, `code`, `share-link`,
`copy`, `qr` and `error`. `--irt-qr-fg` and `--irt-qr-bg`, `#000` and
`#fff` by default, color the QR code; keep them dark on light so every
phone can scan it.

### `<irt-room-browser>`

![The room browser, light](/ui-kit/room-browser-light.png) ![The room browser, dark](/ui-kit/room-browser-dark.png)

The project's active public rooms of its `type` attribute, else of every
type, each with its players out of its maximum and a join button,
"Full" and disabled at the maximum. A room's `meta.name`, when it's a
string, labels it, else its ID. Below the list are the create, join by
code and quick join buttons the room panel has; the browser creates
public rooms of its type and quick joins its type.

`listPublic` is limited to 60 requests a minute per address, so the
browser lists the rooms when it's added to the page, or for a dialog
when it opens, and when the player presses refresh, never on a timer.
Call `refresh()` to list them again yourself.

| Attribute or property | |
|---|---|
| `router`, `project` attributes | As for the invite |
| `type` attribute | The room type to list, create and quick join |
| `rooms` property | The rooms last listed, read-only; undefined before the first list |

Event: `room-join`, with `joinCode` null for a room joined from the list.

Labels: `title`, `refresh`, `loading`, `empty`, `players` (with `{n}`
and `{max}`), `joinRoom`, `full`, `create`, `joinCode`, `join`,
`quickJoin` and `close`. Parts: `header`, `title`, `refresh`, `empty`,
`rooms`, `room`, `room-name`, `room-players`, `join-room`, `actions`,
`create`, `join-form`, `join-code`, `join`, `quick-join` and `error`.

### `<irt-room-panel>`

![The room panel, light](/ui-kit/room-panel-light.png) ![The room panel, dark](/ui-kit/room-panel-dark.png)

The whole room screen as one element: an `<irt-invite>`, the connection
status, the players in the room from [presence](/docs/guides/presence),
a name field for the local player, and the create, join by code and
quick join buttons.

- **Create room** calls `createRoom` with `joinCode: true`, so the room
  can be shared without giving out its ID. **Join** looks the code up
  with `joinByCode`, in any case. **Quick join** calls `quickJoin`. Each
  fires `room-join` with the room ID and join code.
- **Status** is one of connecting, waking, open, reconnecting and
  closed, with the close reason, in a live region screen readers
  announce.
- **Players** each show their name, `(you)` for the local player and
  `(away)` while disconnected, for the 10 seconds before their entry
  leaves.
- **Settings.** The buttons don't know the project's settings. When one
  is off, as `players.quickJoin` is by default, the router's 403 message
  is shown under the buttons. Hide a button you don't use with
  `irt-room-panel::part(quick-join) { display: none; }`.

The buttons are hidden while the panel has a client that isn't closed.

| Attribute or property | |
|---|---|
| `router`, `project` attributes | As for the invite |
| `qr` attribute | Passed to the invite |
| `client` property | The `RoomClient` to show; set it on `room-join` |
| `room`, `code` properties | The invite's; the panel sets them, or set them for a room found another way |
| `invite` property | The `<irt-invite>` inside |
| `playerName` property | The saved name, read-only |
| `link` property | The share link, read-only |

Events: `room-join`, and `name-change` with `{ name: string }`, trimmed,
at most 64 characters.

Labels: the invite's and the buttons', and `idle`, `connecting`,
`waking`, `open`, `reconnecting`, `closed` (followed by `: ` and the
reason), `name`, `saveName`, `players`, `you`, `away` and `unnamed`.
Parts: `status` (with `data-status`), `invite`, the invite's `room`,
`code`, `share-link`, `copy` and `qr`, `name-form`, `name`, `save-name`,
`players-section`, `players-label`, `players`, `player` (also `you` and
`away`), the buttons' parts as in the room browser, and `error`.

**Names.** A presence entry's `name` is set by the room, and its
`status` by the player, so the panel puts the name the player types in
its presence status as `name`, next to any other fields the project
keeps there. It saves the name in `localStorage` under
`irt.name.<project>` and sends it again whenever the client connects or
resyncs. Each player is shown by the room's `name` when it has set one,
else by the `name` in their status, else as "Player". A room that wants
a say checks the claimed name and makes it the presence name, which
then wins:

```ts
// src/room.ts
import { defineRoom } from "@irt/room";

export default defineRoom({
  onTick(room) {
    for (const p of room.presence) {
      const claimed = (p.status as { name?: unknown } | null)?.name;
      if (typeof claimed !== "string") continue;
      const name = claimed.replace(/[^\p{L}\p{N} _-]/gu, "").slice(0, 32);
      if (name && name !== p.name) room.presence.set(p.player, { name });
    }
  },
});
```

A project with player tokens can pass the name in the token's `meta`
instead, which is the presence name from the start; see
[Player tokens](/docs/player-tokens).

### `<irt-lobby>`

![The lobby, light](/ui-kit/lobby-light.png) ![The lobby, dark](/ui-kit/lobby-dark.png)

A [lobby](/docs/guides/lobbies): an `<irt-invite>` for the code, share
link and QR code, the lobby's players with who is ready and who leads,
a ready button, start and cancel buttons for the leader, the countdown,
and why a handoff failed. The leader also gets a "Make leader" button
beside each other connected player, which passes the lead with
`client.lead`. Give it the lobby's client, and take the new room's
client from its `handoff` event; see
[the lobbies guide](/docs/guides/lobbies#the-lobby-element).

| Attribute or property | |
|---|---|
| `router`, `project`, `qr` attributes | Passed to the invite |
| `client` property | The lobby's `RoomClient` |
| `invite` property | The `<irt-invite>` inside, for its `room` and `code` and its `room-join` |

Event: `handoff`, with the client's `Handoff`.

Labels: the invite's, and `waiting`, `countdown` (with `{n}` for the
seconds left), `handingOff`, `ready`, `notReady`, `isReady`, `start`,
`cancel`, `you`, `bot`, `leader`, `makeLeader`, `unnamed`, `moving`,
`players` and `failed`, an object with a text for each handoff failure.
Parts: `invite`, `lobby`, `phase` (with `data-phase`), `players-label`,
`lobby-players`, `lobby-player` (also `you`, `bot`, `is-ready` and
`leader`), `make-leader`, `ready`, `start`, `cancel` and `failed`.

### `<irt-voice-settings>`

![The voice settings, light](/ui-kit/voice-settings-light.png) ![The voice settings, dark](/ui-kit/voice-settings-dark.png)

The local player's voice controls, for a `Voice` from
[`joinVoice`](/docs/guides/proximity-voice): the microphone on or off,
the microphone and speaker devices, an input level meter, and
push-to-talk or open mic with the push-to-talk key. The speaker select
shows only where the browser can pick an output device (`setSinkId`).
Device names appear once the player has allowed the microphone. Set the
voice as its `voice` property, and keep the element in the page with
the `dialog` attribute, opening it with `show()`:

```html
<irt-voice-settings dialog></irt-voice-settings>
```

```ts
// web/voice.ts
import { joinVoice } from "@irt/client/voice";
import "@irt/client/ui/voice-settings";

const settings = document.querySelector("irt-voice-settings")!;
settings.voice = joinVoice(client);
document.querySelector("#voice-settings")!.addEventListener("click", () => settings.show());
```

While the element is in the page and push-to-talk is on, it binds the
push-to-talk key, `key`, a `KeyboardEvent.code` (default `KeyV`), and
ignores it while focus is in a text field. It keeps binding it while its
dialog is closed, which is why it stays in the page rather than coming
from `open()`, which removes it on close. The player picks another key
with the key button; Escape cancels picking one. The key the player
picks is kept in `localStorage` under `irt.pttKey.<project>`, for the
voice's project, and wins over `key`, which sets the key for players
who haven't picked one. Where the browser blocks storage it lasts for
the page.

When the microphone fails to start, whether the player turned it on or
it was on when voice joined, it's turned off again and the element says
why: `micBlocked` when the browser refused it, else `micFailed`. The
voice reports the same failures on its `micError` event.

Labels: `title`, `micOn`, `micOff`, `micBlocked` (the browser refused
the microphone), `micFailed`, `input`, `output`, `defaultDevice`,
`level`, `mode`, `openMic`, `pushToTalk`, `key`, `pressKey` and `close`.
Parts: `title`, `mic` (with `aria-pressed`), `error`, `level`,
`level-bar`, `input-field`, `input`, `output-field`, `output`, `mode`,
`key-field`, `key`, `close` and `link`.

### `<irt-voice-chat>`

![The voice chat, light](/ui-kit/voice-chat-light.png) ![The voice chat, dark](/ui-kit/voice-chat-dark.png)

The other players on the voice server, from the voice's `participants`,
each by their presence name, with a speaking indicator, a volume slider
and a mute button. A player in the room who hasn't joined voice isn't
listed. Volume and mute
are the local player's own, through the voice's `setVolume` and
`setBlocked`: a volume from 0 to 1 multiplies the room's distance
attenuation, and a muted player is unsubscribed, so they cost no
bandwidth. Both are kept per project in `localStorage` by player ID, a
volume once the slider is let go, so a player muted in one room stays
muted in the next. Set its `voice` and
its `client`, whose presence names the players.

When the page listens for `report` on the element, each player also gets
a report button, and the event carries `{ player, name }`. IRT keeps no
reports and does no moderation: what a report does is up to the project.

```ts
// web/voice-chat.ts
import { joinVoice } from "@irt/client/voice";
import "@irt/client/ui/voice-chat";

const chat = document.querySelector("irt-voice-chat")!;
chat.client = client;
chat.voice = joinVoice(client);
chat.addEventListener("report", (e) => void fetch("/api/report", { method: "POST", body: JSON.stringify(e.detail) }));
```

Event: `report`, with `{ player, name }`.

Labels: `title`, `empty`, `unnamed`, `speaking`, `muted` (their
microphone is off), `volume`, `block`, `unblock`, `report` and `close`.
Parts: `title`, `players`, `player` (with `data-player`, and
`data-speaking`, `data-muted` and `data-blocked` while they hold),
`speaking`, `name`, `volume`, `block` (with `aria-pressed`), `report`,
`empty`, `close` and `link`.

### `<irt-network>`

![The network indicator, opened, light](/ui-kit/network-light.png) ![The network indicator, opened, dark](/ui-kit/network-dark.png)

Signal bars and the round trip, for a corner of the canvas: 4 bars under
80 ms, 3 under 150, 2 under 250, 1 above, and none while reconnecting.
Clicked, it opens a popover with the transport, WebTransport or
WebSocket, the round trip, the jitter and the traffic in and out per
second, measured from `client.stats` over one-second windows. Set its
`client` property.

Labels: `signal` (the bars' accessible name, with `{n}`), `offline`,
`details`, `transport`, `rtt`, `jitter`, `in`, `out`, `kinds`, an object
with `webtransport`, `websocket` and `unknown`, and `close`. Parts:
`indicator` (with `data-signal`), `bars`, `bar` (also `lit`),
`rtt-short`, `details`, `title`, `transport`, `rtt`, `jitter`, `in`,
`out`, `close` and `link`.

### `<irt-join-loader>`

![The join loader after a join that started the room, light](/ui-kit/join-loader-light.png) ![The join loader after a join that started the room, dark](/ui-kit/join-loader-dark.png)

A small animation while its client connects, reconnects or waits for
the room to start, then "Joined in 180 ms", or "Room started in 1.4 sec"
when the router started or woke the room on the way, from
`client.joinTime`. The message fades after 3 seconds, and the loader
disappears if the client closes. Set its `client` property.

Labels: `connecting`, `waking`, `reconnecting`, `joined` and `started`
(each with `{time}`), and `close`. Parts: `spinner` and `text`, and
`frame` with `data-state`: `idle`, `joining`, `joined` or `faded`.

## Labels

Each element's English text is its `default…Labels` export, such as
`defaultRoomPanelLabels`. Set `labels` to replace any of them by key;
the rest stay English. Numbers and times are formatted with
`Intl.NumberFormat` in the page's language, from `<html lang>`, else
the browser's.

```ts
// web/labels.ts
import type { RoomPanelLabels } from "@irt/client/ui";

const french: Partial<RoomPanelLabels> = {
  idle: "Pas dans une salle",
  connecting: "Connexion…",
  waking: "Démarrage de la salle…",
  open: "Connecté",
  reconnecting: "Reconnexion…",
  closed: "Déconnecté",
  create: "Créer une salle",
  join: "Rejoindre",
  quickJoin: "Partie rapide",
  name: "Ton nom",
};

if (navigator.language.startsWith("fr")) document.querySelector("irt-room-panel")!.labels = french;
```

Close reasons and the router's errors stay in English.

## Theming

The elements read one set of custom properties, inherited through their
shadow roots, so set them once on `:root` or on any ancestor:

| Custom property | Light default | Dark default | |
|---|---|---|---|
| `--irt-bg`, `--irt-fg` | `#fff`, `#1a1a1a` | `#1f1f22`, `#ececec` | Background and text |
| `--irt-muted` | `#666` | `#a3a3a3` | Labels, away players, the irt.io link |
| `--irt-accent`, `--irt-accent-fg` | `#2456d6`, `#fff` | `#8aadff`, `#0b1a3d` | Buttons and focus rings |
| `--irt-danger` | `#b3261e` | `#ff8a80` | Errors, one signal bar |
| `--irt-good`, `--irt-warn` | `#1e7a3c`, `#9a5b00` | `#6fd08c`, `#f2b84b` | Signal bars and indicators |
| `--irt-radius`, `--irt-gap` | `8px`, `12px` | | |
| `--irt-font` | `16px/1.4 system-ui, sans-serif` | | A `font` shorthand |

The defaults follow `prefers-color-scheme`. Each element sets
`color-scheme: light dark`, so its native controls and dialog backdrop
match the system; a project with its own dark theme on a light system
sets `color-scheme: dark` on the elements as well.

Past what the properties cover, style any part with `::part`:

```css
:root {
  --irt-bg: #14161c;
  --irt-fg: #f2f2f2;
  --irt-accent: #ffb000;
  --irt-accent-fg: #14161c;
}
irt-room-panel::part(player you) { font-weight: 600; }
```

Every element with a dialog also has the parts `frame`, `dialog` and
`close`.

## The irt.io link

Every element has a small "irt.io" link in its bottom-right corner, in
`--irt-muted`, opening `https://irt.io` in a new tab; the network
indicator has it in its popover. It has the part `link`, and can't be
turned off.

## Accessibility

Every field has a label, the order of focus follows the order on screen,
and everything works from the keyboard. Status changes are announced
through live regions and errors as alerts. The QR code is an image
labelled by `labels.qr`, and the share link beside it can be copied for
players who can't scan it. Buttons and fields are at least 44 pixels
tall, apart from the network indicator.

## Testing

The elements need a DOM. In Vitest, run their tests under jsdom with a
`// @vitest-environment jsdom` comment at the top of the file, and give
them a client from `@irt/testing`:

```ts
// web/panel.test.ts
// @vitest-environment jsdom
import "@irt/client/ui/room-panel";
import { defineRoom } from "@irt/room";
import { testRoom } from "@irt/testing";
import { expect, it } from "vitest";

it("lists the players in the room", async () => {
  const room = testRoom(defineRoom({ onJoin: (room, c) => room.presence.set(c.player, { name: c.player.toUpperCase() }) }));
  const alice = await room.connect({ player: "alice" });
  await room.connect({ player: "bob" });
  const panel = document.createElement("irt-room-panel");
  document.body.append(panel);
  panel.client = alice.client;
  await new Promise((r) => setTimeout(r, 0));
  const players = Array.from(panel.shadowRoot!.querySelectorAll("[part~=player]"), (li) => li.textContent);
  expect(players).toEqual(["ALICE (you)", "BOB"]);
});
```

jsdom has no `showModal`, so a test that opens a dialog stubs it.

---

# Webhooks

> Events IRT sends to your backend when rooms and players change, and how to verify them.

Set a project's `webhookUrl` and IRT sends it an HTTP `POST` for each
event in the project's rooms, and when the project nears a spending cap.
Set it in the dashboard, with `irt webhooks set <url>`, or with
`PATCH /projects/{p}` and `{"settings": {"webhookUrl": "https://..."}}`.
The URL must be https. A local or staging stack whose control server
sets `webhooks.allow_private_addresses` also accepts http and private
addresses, so a backend on the same machine can receive events.

## Events

| Type | Sent when |
|---|---|
| `room.created` | A room is created; `data` is `{public, joinCode, retention}`, where `retention` is the room's own retention from `POST /rooms`, or `null` when it follows the project's `rooms.retention` |
| `room.active` | A room has started or woken and is running; `data` is `{generation}` |
| `room.hibernated` | A room has hibernated; `data` is `{generation}` |
| `room.restored` | A room woke on a build older than its room state, after a rollback, and started from its room state from before the migration; `data` is `{generation, build, fromVersion, version}` |
| `room.deleted` | A room is deleted; `data` is `{reason}`: `"api"` when deleted through the API, the CLI or the dashboard, `"expired"` when its [retention](/docs/hibernation#retention) passed while hibernated, and `"retention"` when it emptied with retention `"none"` |
| `player.joined` | A player's connection joins a room; `data` is `{player, connection}` |
| `player.left` | A player's connection leaves a room; `data` is `{player, connection, code}`, with the close code |
| `build.rolled_back` | The live build crash-looped and the build it replaced went live again; `room` is `null` and `data` is `{build, to, reason, crashes}`. See [Automatic rollback](/docs/builds#automatic-rollback) |
| `usage.alert` | The project passed 80% of a spending cap, at most once per cap per UTC day; `room` is `null` and `data` is `{limit, used, max, day}`, with `limit` `maxRoomHoursPerDay` or `maxActiveRooms`. See [Stats and usage alerts](/docs/stats) |
| `billing.low_balance` | Your account's credit dropped below the low-balance threshold; sent to every project, once per drop, with `room` `null` and `data` `{balance, threshold, graceEndsAt}`. `graceEndsAt` is when projects stop waking rooms, if the balance is already at zero. See [limits](/docs/limits#credit) |

The body is JSON:

```json
{
  "type": "player.joined",
  "project": "my-game",
  "room": "forest-7",
  "at": "2026-11-04T10:00:00Z",
  "data": { "player": "u_42" }
}
```

## Delivery

Each event is sent once, best effort. There are no retries, so a webhook
that is down misses events. Treat webhooks as hints and read the
[HTTP API](/docs/http-api) when you need the current truth, for example
`GET /projects/{p}/rooms/{id}` for a room's status.

Events normally arrive well under a second after they happen. A burst
waits on your endpoint, which gets up to 32 deliveries at once, and
events held while IRT's services catch up after an outage arrive late,
up to minutes. Order isn't guaranteed. A room hibernates 30 seconds
after its last `player.left`, so a read of the room on that event finds
it running; a read that arrives late can wake it again.

Respond quickly with a `2xx`; do slow work after responding.

### Order

Events aren't delivered in order. Different parts of IRT send them: the
router sends `room.created`, `room.deleted` from the API and the player
events, and the host running the room sends `room.active`,
`room.hibernated` and `room.restored`. So a room created and started at
once often sends `room.active` before `room.created`. Order a room's
events by `at`, and by `generation` where they have one.

`generation` grows by one at each attempt to start the room, including
attempts that fail, so it can skip numbers. A room that failed to wake
four times and then woke reports `room.active` with a generation four
higher than its last.

## Verifying a webhook

Every request has an `IRT-Signature` header:

```
IRT-Signature: t=1793786400,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd
```

`v1` is the hex HMAC-SHA256 of `t`, a dot and the raw request body, keyed
with the project's webhook secret. To verify:

1. Compute the HMAC over the raw body exactly as received, before
   parsing it.
2. Compare it with `v1` in constant time.
3. Reject requests whose `t` is far from your clock, which stops a
   captured request being replayed later. Five minutes is a reasonable
   window.

```ts
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyWebhook(rawBody: string, header: string, secret: string): boolean {
  const parts = new Map(header.split(",").map((kv) => kv.split("=", 2) as [string, string]));
  const t = parts.get("t");
  const v1 = parts.get("v1");
  if (!t || !v1) return false;
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;

  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(v1, "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}
```

## The webhook secret

Rotate the secret in the dashboard, with `irt webhooks rotate-secret`
or with `POST /projects/{p}/webhook-secret`. The new secret is shown once and
signs every event from then on, so update your backend straight away.

---

# Dev tools

> The irt dev inspector for rooms, connections, state, entities, recent messages and calls; the per-room tick profiler; and simulated latency, jitter and loss in the client.

Three tools help while a game runs under `irt dev`: an inspector that
shows what each room holds, a tick profiler that says where a room's time
goes, and simulated network conditions in the client. All three are for
development. None of them changes what a deployed room or client does.

## The inspector

`irt dev` prints the inspector's address when it starts:

```sh
irt dev: http://127.0.0.1:7350 serves the site and room host; watching for changes
irt dev: inspect rooms at http://127.0.0.1:7350/v1/dev/
```

The page lists the running rooms and refreshes every second. For the room
you pick it shows:

- its generation, status, tick and tick rate
- the tick profile of the last second
- connections, with player ID and token meta
- `room.state`
- the private state of every player the room keeps it for, connected or not
- entities, with kind, owner and values, including the entities of
  [hidden kinds](/docs/guides/state-sync#hidden-entities), marked
  hidden. No client is sent those; the inspector shows them because it's
  for you
- the last 200 messages and calls from clients, newest first: kind, name,
  connection and player, tick, size in bytes, and the result or error

A message's name is its `type` when it's a JSON object with a string
`type`. A call's result is the size of its reply, or the error the client
got. `bytes` fields show as base64.

The same data is JSON, for scripts and agents:

| Endpoint | Returns |
|---|---|
| `GET /v1/dev/rooms` | `{ rooms: [{ project, id, generation, status, tick, connections }], stats }`, `stats` being the room host's last `stats` frame |
| `GET /v1/dev/rooms/{project}/{id}` | `{ project, id, generation, status, tick, tickRate, connections, state, private, entities, trace, profile }`, each entity being `{ id, kind, owner, hidden, values }`; 404 when the room isn't running |

```sh
curl -s http://127.0.0.1:7350/v1/dev/rooms/my-game/main | jq '.entities'
```

The inspector shows every player's private state and every hidden
entity, so it's only there under `irt dev` (or `irt-room-host` with
`IRT_INSPECTOR=1`). It sends no CORS headers and answers only requests
addressed to `localhost`, `127.0.0.1` or `[::1]`, so another web page
can't read it through your browser.

## The tick profiler

The room host times each room's code with `performance.now()`:

| Phase | What it times |
|---|---|
| `tick` | A whole tick |
| `writes` | Applying owner writes, `onWrite` included, in ticks that had any |
| `stepper` | The stepper's `step` |
| `onTick` | `onTick` |
| `flush` | Sending the state update, interest functions and compression included |
| `interest` | The part of `flush` that works out what each connection sees: interest keys, `sees` and `priority` |
| `onPlayerLeave` | Each run, at the start of a tick or before hibernation |
| `onJoin`, `onLeave`, `onMessage`, `call` | Each run of the hook or call handler, between ticks |

Each second it reports, per phase, the count, total, p50, p95 and max in
milliseconds. Percentiles come from the second's last 256 samples; count,
total and max cover all of them. Async hooks and calls count only up to
their first `await`. Phases that didn't run are left out.

Under `irt dev` the numbers are in the inspector. A `tick` p95 near the
tick interval (50 ms at 20 ticks a second) means the room can't keep up,
and every room in the process shares that event loop. The profile is
measured inside the room host, so it's a guide for your code, not what IRT
bills: room-hours are counted outside the VM.

Deployed room hosts measure the same phases. Each build's average and
longest tick per minute are in the dashboard's Stats tab, `irt stats`
and the HTTP API; see [Stats](/docs/stats). An active deployed room's
own profile of its last second is `irt rooms profile <id>` and `GET
/projects/{p}/rooms/{id}/profile`; it doesn't wake a hibernated room.

## Simulated network conditions

`simulateNetwork` from `@irt/client/dev` wraps the client's transport so
a local game feels like it's on a real network:

```ts
// web/main.ts
import { connect } from "@irt/client";

// Open the game with ?slow to try it at 150 ms with jitter and loss.
const dial = new URLSearchParams(location.search).has("slow")
  ? (await import("@irt/client/dev")).simulateNetwork({ rttMs: 150, jitterMs: 20, loss: 0.05 })
  : undefined;

const room = await connect({ router: location.origin, project: "my-game", room: "main", dial });
```

| Condition | Meaning |
|---|---|
| `rttMs` | Round-trip time to add, half of it each way |
| `jitterMs` | Each one-way delay is up to this much above or below `rttMs / 2`, never below 0 |
| `loss` | Fraction of unreliable messages dropped each way, 0 to 1 |

Reliable messages, calls, state updates and owner writes are never
dropped; they're delayed and arrive in order, as on a real stream.
Unreliable messages (`send` with `{ unreliable: true }`), inputs and
pings can be dropped and can overtake each other, as datagrams do.

It refuses a router that isn't `localhost`, `127.0.0.1` or `::1`, so
`connect` rejects with an `IrtError` saying so; pass
`{ allowRemote: true }` as the second argument to use it against another
router on purpose. Importing it dynamically, as above, keeps it out of the
game's main bundle; it isn't part of `@irt/client`'s core entry.

The second argument also takes `dial`, the transport to wrap, and `clock`
and `random`, which tests use to make delays and loss deterministic.

---

# Stats and usage alerts

> Per-build players, rooms, reconnects, errors and tick cost in the dashboard, and alerts before a project reaches its spending caps.

The dashboard's **Stats** tab shows each build's numbers a minute at a
time, as tables, for the last 14 days. Use it to see how a new build
behaves next to the one before it.

## What's counted

Measured by the router, outside your rooms:

| Column | Meaning |
|---|---|
| Peak players | The most connections at once in the minute or range. Each router counts its connections about every second, and each room counts the most it had since the count before, so a connection shorter than a second still counts. A player who moves between rooms within one count counts once in each room. Rooms on different routers are added up |
| Peak rooms | The most active rooms at once |
| Reconnects | Connections from a player who left the same room in the last minute, or who connected again before their last connection was seen to drop |

Reported by rooms, from inside their VM:

| Column | Meaning |
|---|---|
| Errors | Lines the room SDK logs at level `error`, such as a hook that threw |
| Ticks | Ticks run |
| Average tick, longest tick | Time spent in a tick, from the room host's own measurements |

Numbers reported by rooms come from your own code's process, so they're
your build's account of itself: good for debugging, and never used for
billing. Billing counts only what IRT measures outside your rooms; see
[Limits](/docs/limits).

A build's row in a range shows the highest per-minute peak and the totals
of the rest. Click a build to see its last hour minute by minute.

`irt stats` prints the same table in a terminal, and
`irt stats --build <id>` one build minute by minute; see
[CLI](/docs/cli#irt-stats). Tick cost is a build's average and longest
tick over all its rooms. For one room's cost per hook, such as how much
of a tick `onTick` or the state update takes, run the room under
`irt dev` and open its [inspector](/docs/dev-tools), which shows the
tick profile as p50, p95 and max.

## From your backend

The same numbers are in the [HTTP API](/docs/http-api), with an API key:

- `GET /projects/{p}/stats?from=...&to=...`: each build over a range, by
  default the last 24 hours, at most 14 days.
- `GET /projects/{p}/builds/{id}/stats?from=...&to=...`: one build per
  minute, by default the last hour, at most 24 hours.

`from` and `to` are RFC 3339 times, such as `2026-11-04T12:00:00Z`, or
dates, such as `2026-11-04`, which mean midnight UTC at their start.
Anything else answers `400` with the code `invalid`.

```json
{
  "minute": "2026-11-04T10:05:00Z",
  "peakPlayers": 42,
  "peakRooms": 7,
  "reconnects": 3,
  "reportedByRooms": { "errors": 0, "ticks": 8400, "tickMsAvg": 1.2, "tickMsMax": 9.5 }
}
```

`tickMsAvg` and `tickMsMax` are `null` for a minute with no ticks.

## Usage alerts

When a project passes 80% of `limits.maxRoomHoursPerDay` or
`limits.maxActiveRooms`, IRT sends a `usage.alert`
[webhook](/docs/webhooks) and the dashboard shows a banner on the
project's pages. Each limit alerts at most once per UTC day, so raise the
cap in the project's settings if the project is meant to grow past it.
Room-hours count from room periods that ended today, as the cap does, and
active rooms from the router's count in the last few minutes.

`GET /projects/{p}/alerts` lists today's alerts:

```json
{ "alerts": [{ "limit": "maxRoomHoursPerDay", "used": 164.2, "max": 200, "day": "2026-11-04", "at": "2026-11-04T15:20:00Z" }] }
```

---

# Self-hosting

> Running a build on your own machine with the open-source room host, in Docker or behind Caddy, and how it differs from hosted IRT.

The room host in `@irt/room` is open source and runs on its own. Given a
build, it serves the client protocol over WebSocket, the client HTTP API
and the site from one process, with room state on disk. The client SDKs
work against it as they do against the router, so a project can move
between IRT and its own machine by changing the router address.

Self-hosting is one process on one machine. The VM layer, placement
across hosts and hibernation to object storage are part of hosted IRT
and aren't open source.

## Running a build

`irt build` writes the build tarball to `.irt/build/build.tar.gz` and
leaves its unpacked files in `.irt/build/stage`: `irt-build.json`, each
room type's bundled module in `room/` and the site in `site/`. Pass either directory
to `irt-room-host`:

```sh
irt build
npx irt-room-host .irt/build/stage
```

Or unpack the tarball where it will run:

```sh
mkdir -p /srv/my-game
tar -xzf .irt/build/build.tar.gz -C /srv/my-game
npx irt-room-host /srv/my-game
```

Given a build directory, the room host serves each of its
[room types](/docs/concepts#rooms), native types included,
with each type's own size, `maxPlayers` and retention, its site with the
build's `site.crossOriginIsolated`, and the settings declared in
`irt.config.ts`. It also takes a single bundled room module in place of
a directory, as the one type `default`.

It logs one JSON line, `{"level":"info","msg":"listening",...}`, when it
is ready. On `SIGTERM` or `SIGINT` it drains: it stops taking
connections, closes the open ones with 1001 so clients reconnect with
backoff, and hibernates every room to disk, running `onHibernate`. Rooms
that haven't saved within 8 seconds are stopped, and wake from their
last change on disk, as after a crash.

## Configuration

The room host is configured by environment variables, and checks them
all at startup. A configuration it can't run with exits with code 2 and
one line per problem.

| Variable | Default | Meaning |
|---|---|---|
| `IRT_PORT` | `7350` | Port for the client protocol at `/v1/ws`, the client HTTP API, `/healthz` and the site |
| `IRT_HOSTNAME` | `127.0.0.1` | Address to listen on; `0.0.0.0` for every interface |
| `IRT_DATA` | `.irt` | Directory for room state and join codes; it must be writable |
| `IRT_SIGNING_KEYS` | the key in `$IRT_DATA/key` | Comma-separated HS256 secrets that verify [player tokens](/docs/player-tokens), each at least 32 characters |
| `IRT_GUEST_KEY` | the key in `$IRT_DATA/key` | HS256 secret that signs and verifies guest tokens, at least 32 characters and not one of the signing keys |
| `IRT_SETTINGS` | none | [Project settings](/docs/http-api#project-settings) as JSON, for those the build doesn't declare |
| `IRT_SITE` | none | A site directory to serve, with a room module only |
| `IRT_CROSS_ORIGIN_ISOLATED` | `0` | `1` serves `IRT_SITE` with COOP and COEP, with a room module only |
| `IRT_LIVEKIT_URL` | none | A LiveKit server for voice, such as `wss://voice.example.com` |
| `IRT_LIVEKIT_KEY`, `IRT_LIVEKIT_SECRET` | `devkey`, `secret` | That server's API key and secret |
| `IRT_INSPECTOR` | `0` | `1` serves the [inspector](/docs/dev-tools#the-inspector); it shows every player's private state, so leave it off on a server |

Generate keys with `openssl rand -base64 32`. Your backend signs player
tokens with a signing key exactly as it does for a hosted project.

### Keys and rotation

Tokens are checked as the router checks them. A player token must be
signed with one of `IRT_SIGNING_KEYS`, name the project the client
connects to in `prj`, and live at most 24 hours. A guest token must be
signed with `IRT_GUEST_KEY`; a signing key can't sign one, and the guest
key can't sign a player token.

To rotate a signing key, add the new key to `IRT_SIGNING_KEYS` and
restart, move your backend to the new key, then remove the old one and
restart again. Tokens signed with any listed key are accepted.

Guest tokens last 30 days and keep a guest's player ID across visits.
Set `IRT_GUEST_KEY` so they keep working when `IRT_DATA` is lost or the
room host moves to another machine. Changing it turns every returning
guest into a new one.

Without either variable, the room host generates a key in
`$IRT_DATA/key` and uses it for both, as `irt dev` does.

### Settings

`players.*`, `rooms.size`, `rooms.retention` and `voice.*` apply as they
do hosted. Settings declared in `irt.config.ts` belong to the build, as
they do for a hosted project; `IRT_SETTINGS` sets the rest, and setting
one the build declares is a startup error:

```sh
IRT_SETTINGS='{"players":{"quickJoin":true},"rooms":{"size":"large"}}' npx irt-room-host /srv/my-game
```

## Docker

The repository has a Dockerfile that builds the room host on Node 24 and
runs it as an unprivileged user, with room state in a volume at `/data`
and the build at `/build`:

```sh
docker build -f deploy/self-host/Dockerfile -t irt-room-host .
docker run -d --name my-game -p 7350:7350 \
  -v my-game-data:/data \
  -v /srv/my-game:/build:ro \
  -e IRT_SIGNING_KEYS -e IRT_GUEST_KEY \
  irt-room-host
```

The image listens on `0.0.0.0:7350`, and its health check calls
`/healthz`, which answers `200 ok`, or `503` while draining. `docker stop`
drains the room host within its 10-second grace period. A bind mount at
`/data` must be writable by uid 1000.

## TLS with Caddy

The room host speaks plain HTTP and WebSocket. Put a reverse proxy in
front of it for TLS. With [Caddy](https://caddyserver.com), which gets
certificates by itself and proxies WebSocket upgrades:

```text
game.example.com {
	reverse_proxy 127.0.0.1:7350
}
```

Clients then use `https://game.example.com` as their router address,
and the site is served from the same origin. Behind a proxy, keep
`IRT_HOSTNAME` at `127.0.0.1` so the room host is reachable only through
it.

Self-hosted connections use WebSocket only. WebTransport and its
datagrams need the router, so unreliable messages travel over the
WebSocket and arrive in order. On an `https://` address the client SDK
tries WebTransport once at `/v1/wt`, fails, and uses WebSocket from then
on.

## What's the same

- **The protocol and the client SDKs.** `connect`, `createRoom`,
  `joinByCode`, `listPublic` and `quickJoin` take the room host's address
  as `router`. A client switches between hosted and self-hosted by that
  URL alone.
- **The room SDK.** The same build runs in both, with the same hooks,
  hibernation and wake, room state versions and migrations.
- **Limits and close codes.** Message size and rate, connections per room
  by size and `maxPlayers`, room state size, token lifetime and the
  [close codes](/docs/limits#close-codes) are the hosted ones. Rooms
  hibernate 30 seconds after their last connection leaves.
- **Tokens and guests**, as above.
- **Player data, collections and leaderboards.** Room code's
  `room.playerData`, `room.collection` and `room.leaderboard` and the
  client SDK's `dataClient` work the same, with the same rights, errors
  and 5-second room cache, against `settings.data` from the build or
  `IRT_SETTINGS`. See [the guide](/docs/guides/player-data).

## What's different

- **One process.** All rooms share one Node event loop and one machine.
  There is no placement, no VM per tenant and no CPU or memory
  reservation per room.
- **Room state and player data on disk.** Rooms hibernate to
  `IRT_DATA` rather than to object storage, and every change is appended
  there as it happens. Player data, collections and leaderboards are in
  SQLite at `IRT_DATA/data.sqlite`, written before each call answers.
  Back up that directory; it is the only copy. `rooms.retention` other than
  `"none"` isn't enforced, so hibernated rooms are kept until you delete
  them.
- **The client HTTP API only.** The room host serves `/v1/ws`,
  `POST /v1/rooms`, `POST /v1/quick-join`, `GET /v1/codes/{project}/{code}`,
  `GET /v1/rooms/{project}`, `POST /v1/guest`, `POST /v1/data/{project}`
  and `/healthz`. Data calls have no rate limits and guest minting no
  per-address cap, so put a proxy's limits in front of a public room
  host. The [HTTP API](/docs/http-api)
  at `api.irt.io` isn't there: no server API calls into rooms, no room
  deletion, no bans, and no logs or stats endpoints. Webhooks aren't sent.
  Rooms are created only by clients, through `POST /v1/rooms`, join
  codes, quick join or connecting, so `players.createRooms` must be on;
  with it off, the only rooms are those already in `IRT_DATA`.
- **No hosted backend, no WebTransport, no metering, billing, spending
  limits or dashboard.** Close code 4009 never happens.
- **Voice** needs a LiveKit server of your own, set by `IRT_LIVEKIT_URL`.
- **Projects.** The room host serves whatever project slug a client
  names, with one set of settings and keys for all of them.

---

# HTTP API

> The control server API at api.irt.io/v1 for projects, keys, secrets, builds, rooms, logs and usage.

`https://api.irt.io/v1` takes and returns JSON. The dashboard, the CLI and
your backend all use it.

## Authentication

| Credential | Sent as | Used by | Acts for |
|---|---|---|---|
| Session | cookie `__Host-irt_session` | The dashboard at `app.irt.io` | Your tenant |
| Personal token | `Authorization: Bearer irt_pat_...` | The CLI, after `irt login` | Your tenant |
| API key | `Authorization: Bearer irt_key_...` | Backends and CI | One project |

```sh
curl https://api.irt.io/v1/projects/my-game/rooms \
  -H "Authorization: Bearer $IRT_API_KEY"
```

Keep API keys on your backend. Never ship one in a client.

### Signing in

- `GET /auth/github?invite=...` starts signing in with GitHub. The invite
  code is needed the first time only. The callback,
  `/auth/github/callback`, sets the session and returns to the dashboard.
- `POST /auth/logout` ends the session.
- `GET /me` returns the signed-in user, their tenant, its credit balance,
  and whether the user is an IRT admin.

### Device flow

This is how `irt login` gets a personal token:

1. `POST /auth/device` returns `{deviceCode, userCode, verificationUrl}`.
2. The user opens `https://app.irt.io/device`, signs in and enters
   `userCode`.
3. The CLI polls `POST /auth/device/token` with `{deviceCode}` until it
   returns `{token}`.

## Errors

Errors have an HTTP status and a body of this shape:

```json
{ "error": { "code": "not_found", "message": "No project named my-gmae." } }
```

`code` is a stable string to branch on, such as `not_found`, `invalid`,
`limit` or `unauthorized`. `message` is for people and may change.

## Projects

| Method | Path | Body | Does |
|---|---|---|---|
| GET | `/projects` | | Lists your projects |
| POST | `/projects` | `{slug, name}` | Creates a project |
| GET | `/projects/{p}` | | Gets a project and its settings |
| PATCH | `/projects/{p}` | `{name?, settings?}`, with only the settings to change | Updates a project |
| DELETE | `/projects/{p}` | | Deletes a project |

`{p}` is the project's slug.

### Project settings

| Setting | Default | Allowed | Meaning |
|---|---|---|---|
| `players.guests` | `true` | boolean | Clients may join with no player token |
| `players.createRooms` | `true` | boolean | Clients may create rooms and use join codes, and connecting to a room that doesn't exist creates it |
| `players.listPublic` | `true` | boolean | Clients may list active public rooms |
| `players.quickJoin` | `false` | boolean | Clients may join any public room with space, or a new one |
| `players.listPublicWithoutToken` | `false` | boolean | Anyone may list public rooms with no token, even with `players.guests` off |
| `voice.enabled` | `false` | boolean | Connections get a voice token |
| `voice.maxSpeakers` | `64` | integer 1 to 64 | A ceiling on each room's own `voice.maxSpeakers`, applied from a room's next wake; see [Proximity voice](/docs/guides/proximity-voice#turning-it-on) |
| `rooms.size` | `"standard"` | `"standard"`, `"large"`, `"extra-large"` | Room size for new rooms |
| `rooms.retention` | `"7d"` | `"none"`, `"<n>h"`, `"<n>d"` up to 365 days, `"forever"` | How long a room is kept after it hibernates; `"none"` deletes it when it empties |
| `rooms.buildUpdate` | `"hibernate"` | `"restart"`, `"hibernate"` | Running rooms move to a new build at once, or on their next hibernate |
| `rooms.rollbackOnCrashLoop` | `true` | boolean | When a newly live build crash-loops, make the build it replaced live again, once per build; see [Builds](/docs/builds#automatic-rollback) |
| `data` | none | see [Player data](/docs/guides/player-data#declaring-it) | Player data keys clients may write, and the project's collections and leaderboards; normally declared in `irt.config.ts` |
| `limits.maxActiveRooms` | `100` | integer | Spending cap: rooms active at once; never from code |
| `limits.maxRoomHoursPerDay` | `200` | integer | Spending cap: room-hours per day; never from code |
| `limits.maxSleepingConnections` | `10000` | integer, 0 to 1,000,000 | Connections the project's [sleeping rooms](/docs/hibernation#sleeping-rooms) hold in a region; never from code |
| `webhookUrl` | none | https URL | Where [webhook](/docs/webhooks) events go; never from code |

Settings go under `settings`, in the same nested shape as the table, and
`null` resets one to its default. Any other top-level field is a `400
invalid` that says so:

```sh
curl -X PATCH $IRT_API_URL/projects/my-game \
  -H "Authorization: Bearer $IRT_API_KEY" -H "Content-Type: application/json" \
  -d '{"settings": {"webhookUrl": "https://example.com/irt", "players": {"guests": false}}}'
```

A setting the live build declares in its
[`irt.config.ts`](/docs/cli#irtconfigts) can't be changed here: a
`PATCH` of it answers 409 naming that build.

A project's client config, which the client SDK needs to connect, is its
slug and its region's router: `{project, router: "wss://eu.irt.io"}`.

## Keys and secrets

| Method | Path | Body | Does |
|---|---|---|---|
| GET | `/projects/{p}/api-keys` | | Lists API keys |
| POST | `/projects/{p}/api-keys` | `{name}` | Creates an API key and returns it, once |
| DELETE | `/projects/{p}/api-keys/{id}` | | Deletes an API key |
| GET | `/projects/{p}/signing-keys` | | Lists signing keys: `{signingKeys: [{id, createdAt}]}` |
| POST | `/projects/{p}/signing-keys` | none | Creates a signing key and returns `{id, secret, createdAt}` with `201`; the secret is shown only this once |
| DELETE | `/projects/{p}/signing-keys/{id}` | | Deletes a signing key; `204` |
| POST | `/projects/{p}/webhook-secret` | | Rotates the webhook secret and returns it, once |
| GET | `/projects/{p}/secrets` | | Lists secret names |
| PUT | `/projects/{p}/secrets/{name}` | `{value}` | Sets a secret |
| DELETE | `/projects/{p}/secrets/{name}` | | Deletes a secret |

Signing keys sign [player tokens](/docs/player-tokens). Creating one
takes no request body; a body sent anyway, such as `{}`, is ignored. A
project has at most 5 signing keys, and creating a sixth answers `422`
with the code `limit`. Signing keys are managed with a login or personal
token, from the dashboard or `irt signing-keys`: an API key gets `403`.
Secrets reach room hosts as environment variables; their values are
never returned. `PATH`, `NODE_OPTIONS`, `HTTPS_PROXY`,
`NODE_USE_ENV_PROXY` and names starting with `IRT_` are reserved, and
setting one answers `400`.

## Builds

| Method | Path | Body | Does |
|---|---|---|---|
| POST | `/projects/{p}/builds` | the build tarball, `application/gzip` | Uploads a build; returns it, with `id`, `types` and `createdAt` |
| GET | `/projects/{p}/builds` | | Lists builds, newest first, with which is live |
| POST | `/projects/{p}/builds/{id}/live` | | Makes a build live |
| POST | `/projects/{p}/restart` | `{room?}` | Moves running rooms, or one, onto the live build now; returns `{rooms}` |

Making a build live switches the site at once and moves rooms to it
according to `buildUpdate`. The tarball's layout is in
[Builds and deploys](/docs/builds#whats-in-a-build).

A build's `types` are its [room types](/docs/concepts#rooms) by
name, as its manifest declares them: each with `schemaHash`, and
`schema`, `stateVersion` and `entry` for a standard type, or `native`,
`schema`, `stateVersion` and `tickRate` for a native one, and its own `size`, `maxPlayers` and `retention` when it
sets them. Making a build live returns it with `schemaChecks`, each type
in both builds by name with its
[schema check](/docs/builds#the-schema-check-at-deploy), and
`schemaCheck`, the `default` type's or `null`. A refusal, `409` with
code `schema_change` or `type_removed`, names the type in `error.type`.

## Rooms

| Method | Path | Body or query | Returns |
|---|---|---|---|
| POST | `/projects/{p}/rooms` | `{id?, type?, size?, retention?, public?, joinCode?, meta?, maxPlayers?}` | the room |
| GET | `/projects/{p}/rooms` | `?public&cursor` | active rooms |
| GET | `/projects/{p}/rooms` | `?status=all&cursor` | every room the project keeps, hibernated ones included |
| GET | `/projects/{p}/rooms/{id}` | | the room, with its status |
| DELETE | `/projects/{p}/rooms/{id}` | | |
| POST | `/projects/{p}/rooms/{id}/messages` | `{message}` | the room's reply |
| GET | `/projects/{p}/rooms/{id}/state` | `?meta=1` | the room's `room.state`; with `meta=1`, `{state, tick, tickRate, savedAt}`, where `savedAt` is when room state was last written (RFC 3339), for computing time-derived values; a room whose build uses an `@irt/room` older than `?meta=1` answers `422 room_error`, so rebuild and deploy to use it |
| GET | `/projects/{p}/rooms/{id}/profile` | | an active room's tick profile over its last second, `{window, profile}`, per phase `{count, total, p50, p95, max}` in milliseconds; `409 room_not_active` for a room that isn't active, which isn't woken for it; a build whose `@irt/room` predates it answers `422 room_error` |
| POST | `/projects/{p}/rooms/{id}/kick` | `{player}` | `204`; closes the player's connection with 4006 |
| POST | `/projects/{p}/rooms/{id}/voice/mute` | `{player, muted}` | `204`; mutes or unmutes the player's voice |
| POST | `/projects/{p}/rooms/{id}/voice/remove` | `{player}` | `204`; disconnects the player from the room's voice |

A room looks like this:

```json
{
  "id": "forest-7",
  "status": "active",
  "build": "b_01J9Z3",
  "size": "standard",
  "public": true,
  "joinCode": "K7QX2M",
  "meta": { "mode": "coop" },
  "maxPlayers": 4,
  "players": 3,
  "createdAt": "2026-11-04T10:00:00Z",
  "stateBytes": 18342
}
```

`status` is `active`, `waking` or `hibernated`. `stateBytes`, only on
`GET /projects/{p}/rooms/{id}`, is the size of the room's room state as
last saved to object storage, which trails a running room by up to 30
seconds; it's `null` before the room's first save. A room stops when its
room state passes 32 MB. Leaving out `id` on
create generates one. `type` is the room's [room type](/docs/concepts#rooms), one of
the live build's, else the type named `default`; a build without one
answers `400 invalid` naming its types. Without `size`, a room gets its
type's size, else the project's `rooms.size`, and the same for
`maxPlayers` and `retention`.

Creating a room doesn't start it. It's `hibernated`, with `build: null`,
until its first connection or API call, which starts it on the live
build like a wake: the client sees `waking` (the SDK's `onWaking` and
`waking` event), and the room runs `onCreate`, not `onWake`, since it
has no room state yet. `build` is set from then on. A room created by
connecting to an ID that doesn't exist starts the same way. `maxPlayers` caps the room's connections, from 1
to its size's connection limit; connecting past it closes with 4003. It's
`null` when the room is capped only by its size. `retention` gives the
room a retention of its own, with the same values as `rooms.retention`,
which wins over the project's: a game can keep its persistent rooms
`"forever"` and let throwaway ones go after a day. Rooms clients create
always follow the project's.

A list is `{rooms, cursor}`; pass `cursor` back for the next page until
it's `null`. With `?status=all` it lists every room the project keeps,
sorted by ID, 500 a page: active rooms as above, and hibernated ones as
`{id, status: "hibernated", players: 0}`. `public` can't be combined with
`status=all`. A room deleted through this API leaves the list at once.
A room created moments ago by a client, or deleted by its retention, may
be missing from it, or still in it, for a few seconds. Sending a message or reading state wakes a
hibernated room, so the call may take as long as a wake, and the room
then stays up for 30 seconds of room-hours before it hibernates again.
There's no read of a hibernated room's stored state yet. To show a
room's data publicly without waking it on every view, keep a copy in a
backend of your own: read the room while `GET /projects/{p}/rooms/{id}`
says it's `active`, and between reads compute what time changes from
`?meta=1`'s `tick` and `savedAt`. A site alone can't do it, since it
can't hold an API key and `/api` on its domain is reserved. Don't
refresh on `room.hibernated`: that read wakes the room, which hibernates
and sends `room.hibernated` again.

```sh
curl -X POST https://api.irt.io/v1/projects/my-game/rooms/forest-7/messages \
  -H "Authorization: Bearer $IRT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": {"type": "grant", "player": "u_42", "item": "lantern"}}'
```

When the room can't answer a message or a state read, the call answers
`422` with code `room_error`, and `message` says why:

```json
{ "error": { "code": "room_error", "message": "onRequest threw: unknown request" } }
```

- `onRequest threw: ...` carries the message of the error your
  `onRequest` threw or rejected with. The room logs it at level `error`.
- `onRequest rejected: ...` carries the message of a `CallRejected`
  your `onRequest` threw, for an expected refusal such as a move that
  breaks a rule. The room doesn't log it.
- `onRequest` may return a promise; the API waits for it.
- `unsupported call message` means the room's code has no `onRequest`.
- Other messages say the room hibernated or stopped before it answered,
  or didn't answer within 10 seconds. The call may or may not have run.

A room that can't be woken answers `503 unavailable`; when the cause is
in the build, such as room code that throws on load or a room SDK the
host doesn't support, `irt logs` has a line saying why. A project over its
spending limit or out of credit `429 limit`, and a router that got no
answer in time `504 timeout`.

Kick and the voice calls answer `404` when the player isn't connected,
and the voice calls `409` with code `voice_off` when the region has no
voice server. See [Moderation](/docs/moderation).

## Bans

| Method | Path | Body | Does |
|---|---|---|---|
| GET | `/projects/{p}/bans` | | Lists the bans that haven't expired |
| POST | `/projects/{p}/bans` | `{player, reason?, expiresAt?}` | Bans a player, or replaces their ban; returns the ban |
| DELETE | `/projects/{p}/bans/{player}` | | Unbans a player |

A ban is `{player, reason, expiresAt, createdAt}`; `expiresAt` is `null`
for a permanent ban, and must be in the future when given. A player ID is
1 to 134 bytes; URL-encode it in the path, so `guest:ab12` is
`guest%3Aab12`. A reason is at most 1000 bytes. A project can have 10,000
active bans; banning one more answers `422 limit`. The router closes a
banned player's connections with 4013 within a few seconds and refuses
new ones.

## Data

| Method | Path | Body | Does |
|---|---|---|---|
| POST | `/projects/{p}/data` | one operation, at most 128 KB | Runs a player data, collection or leaderboard operation as the server |

The body is an operation, such as `{"op": "player.get", "player":
"ada", "key": "save"}`; the operations are those of the
[room SDK](/docs/reference/room-sdk#player-data-collections-and-leaderboards),
named `player.get`, `player.set`, `player.increment`, `player.delete`,
`player.list`, `entry.get`, `entry.put`, `entry.list`, `entry.delete`,
`board.submit`, `board.top` and `board.around`, with their arguments as
fields and `null` meaning an optional one is left out. A backend may do
every operation, and also `player.purge`, which deletes a player's data
and every entry they own, leaderboard scores included, and answers
`{keys, entries}`, the numbers deleted: use it for a deletion request.

```sh
curl -X POST $IRT_API_URL/projects/my-game/data \
  -H "Authorization: Bearer $IRT_API_KEY" -H "Content-Type: application/json" \
  -d '{"op": "board.top", "collection": "highscores", "period": "week", "limit": 10}'
```

The answer is `{"ok": true, "result": ...}` or `{"ok": false, "error":
{"code": "E_...", "message"}}`, with `200` either way, and `503` with
code `E_UNAVAILABLE` when the data service can't be reached within 5
seconds; a write that timed out may or may not have happened, so retry
it with `version`. The codes are in [Errors](/docs/reference/errors#data-calls).

Clients reach the same operations, with a client's rights, through the
router: `POST /v1/data/{p}` on the region's router with a player or
guest token as `Authorization: Bearer`, and `POST /v1/guest` with
`{project}` for a guest token, `{token, player}`, at most 10 a minute
per address. The client SDK's `dataClient` makes these calls.

## Logs and usage

- `GET /projects/{p}/logs?since=...&follow=1` returns room host output.
  With `follow`, it's a stream of server-sent events.
- `GET /projects/{p}/usage?from=...&to=...` returns usage by day:
  room-hours by room size, traffic, voice-minutes and cost.
- `GET /projects/{p}/stats?from=...&to=...` returns each build's peak
  players and rooms, reconnects, and the errors and tick cost its rooms
  report, over a range of at most 14 days.
  `GET /projects/{p}/builds/{id}/stats` returns one build's per minute,
  over at most 24 hours. See [Stats and usage alerts](/docs/stats).
- `GET /projects/{p}/alerts` returns today's usage alerts.

---

# Room SDK

> Reference for @irt/room, the IRT SDK that room code is written with.

`@irt/room` is what room code imports. A room module's default export is
the result of `defineRoom`. Its main entry runs in Node and in browsers,
so a schema or stepper module can import from it and be shared with the
client.

```ts
import {
  defineRoom, defineSchema, defineCalls, defineStepper, defineHistory, entity, json, grid, combine, cellKey, EVERYWHERE, CloseCode, CallRejected, MAX_ENTITY_ID, MAX_HISTORY, MAX_REWIND_MS,
  type Room, type RoomDefinition, type Connection, type RoomEntity, type Entities, type History, type PastEntity,
  type Interest, type InterestPart, type GridOptions, type Json, type Migration, type RoomData, type Stepper, type World,
} from "@irt/room";
```

## defineRoom

```ts
function defineRoom<S extends Kind, P extends Kind, D extends object, C extends Calls>(def: RoomDefinition<S, P, D, C>): RoomDefinition<S, P, D, C>;

interface RoomDefinition<S, P, D, C> {
  schema?: Schema<S, P, C>;        // from defineSchema; without one, the room has no entities or calls
  tickRate?: number;               // ticks per second, an integer from 1 to 120; default 20
  stepper?: Stepper<any>;          // see the prediction guide
  interest?: Interest;             // without it, every connection sees every entity
  voice?: Voice;                   // see the proximity voice guide
  history?: readonly History[];    // fields to record each tick for room.rewind; see History
  data?: () => D;                  // makes room.data when the room starts or wakes; default {}
  version?: number;                // room state version, default 1
  migrations?: Record<number, Migration>;
  privateRetention?: number | "forever";  // ms a player's private state is kept after they leave; default PRIVATE_RETENTION, 24 hours
  sleep?: { after: number };       // sleep once quiet this many ms; see Sleeping rooms

  onCreate?(room: Room<S, P, D>): void | Promise<void>;
  onWake?(room: Room<S, P, D>, info: WakeInfo): void | Promise<void>;  // { elapsed, savedAt, reason, slept }
  onAlarm?(room: Room<S, P, D>, info: { scheduledAt: number; retry: number }): void | Promise<void>;
  onJoin?(room: Room<S, P, D>, connection: Connection): void | Promise<void>;
  seesPresence?(room: Room<S, P, D>, viewer: Connection, entry: PresenceEntry): boolean; // see Presence
  onMessage?(room: Room<S, P, D>, connection: Connection, message: unknown, info: { unreliable: boolean }): void | Promise<void>;
  onLeave?(room: Room<S, P, D>, connection: Connection): void | Promise<void>;
  onPlayerLeave?(room: Room<S, P, D>, player: string): void | Promise<void>;
  onTick?(room: Room<S, P, D>, dt: number): void | Promise<void>;
  onHibernate?(room: Room<S, P, D>): void | Promise<void>;
  onRequest?(room: Room<S, P, D>, message: unknown): unknown;
  onWrite?(room: Room<S, P, D>, connection: Connection, entity: RoomEntity, next: Record<string, unknown>): Record<string, unknown> | undefined;
  calls?: { [name: string]: (room: Room<S, P, D>, connection: Connection, args: Args) => Reply | Promise<Reply> };  // one per call the schema declares
}
```

`defineRoom` throws a `RangeError` for a `tickRate` outside 1 to 120, a
`privateRetention` that isn't a positive number of milliseconds or
`"forever"`, or a `sleep.after` that isn't a positive number of
milliseconds.

### Hooks

| Hook | Runs | If it throws |
|---|---|---|
| `onCreate` | once, when the room starts with no room state | the room stops |
| `onWake` | when the room starts from room state: after hibernating, or after its room host restarted. `savedAt` is the wall-clock time room state was last written (its last tick with changes, or its hibernation) and `elapsed` the milliseconds since, never negative; see [Offline progress](/docs/hibernation#offline-progress). `reason` is what woke it: `"connect"`, `"api"` (a server API call), `"alarm"` or `"message"` (a held connection of a sleeping room sent something or closed); `slept` is `true` for a room that went to sleep, whose connections are back in `room.connections` with their `data`; see [Sleeping rooms](#sleeping-rooms) | the room stops |
| `onAlarm` | when the room's alarm is due, active or hibernated; see [Alarms](#alarms) | it runs again after 2, 4, 8, 16, 32 and 64 seconds, then the alarm is dropped; logged; the room keeps running |
| `onJoin` | when a connection opens, including each reconnect. After a room host crash it runs again for every player who reconnects, with no `onLeave` before it, while their entities from before still exist | that connection closes with 4006; the room keeps running |
| `onMessage` | for each message from a connection | the error is logged with the room, player and tick, the message is dropped, the room keeps running |
| `onLeave` | when a connection closes, a dropped network included, and for each open connection before the room hibernates, except when it goes to sleep. Never after a crash | logged; the room keeps running |
| `onPlayerLeave` | once when a player's presence ends: `PRESENCE_GRACE`, 10 seconds, after its last connection closed with no new one, at the start of the tick that removes it. Before the room hibernates it runs for every player still in presence, after `onLeave` for each connection. Never after a crash. The place to delete a player's avatar | logged; the room keeps running |
| `onTick` | each tick, after the stepper, with `dt = 1 / tickRate` seconds | the room stops |
| `onHibernate` | before the room saves its room state and leaves its room host | the room stops |
| `onRequest` | for a server API message (`POST /projects/{p}/rooms/{id}/messages`); its return value or what its promise resolves to, as JSON, is the reply | the API call gets a `422 room_error` reply with the message; logged unless it's a `CallRejected` |
| `calls[name]` | for each client `call(name, args)`, as it arrives, after the call's `parse` if it has one; its return value or what its promise resolves to, JSON or bytes, is the reply. See [Calls](#calls) | the client's call rejects with the error's message; logged unless it's a `CallRejected`; the room keeps running |
| `onWrite` | for each owner write, at the start of the tick before the stepper; it returns the fields to apply, or undefined to reject. Synchronous. See [Ownership](/docs/guides/ownership) | logged; the write is rejected and the owner corrected |

A room that stops reports the error and closes its connections with
4007; other rooms in the room host keep running. Errors in the stepper,
in interest functions and in migrations also stop the room.

`onCreate`, `onWake` and `onHibernate` may be async: the room starts, or
hibernates, once they resolve. The other hooks may return a promise, but
the room doesn't wait for it; a rejection is handled as a throw.

### Alarms

A room can ask to run code at a time, whether it's active or hibernated
then, and without a player connected:

```ts
export default defineRoom({
  calls: {
    endTurn(room, connection) {
      room.state.turnEndsAt = room.now() + 24 * 3600_000;
      room.setAlarm(room.state.turnEndsAt);
    },
  },
  onAlarm(room, { scheduledAt, retry }) {
    if (room.state.turnEndsAt <= room.now()) skipTurn(room);
  },
});
```

- **One alarm per room.** `setAlarm(at)` replaces the alarm, `clearAlarm()`
  drops it and `room.alarm` reads it. A room with several deadlines keeps
  them in its own state and sets the alarm to the earliest.
- **The alarm is room state.** It survives hibernation and room host
  crashes, and is in `RoomData.alarm`; a migration can't drop it. A call
  that sets one replies once it's held, as for any change to room state.
- **When it fires.** `onAlarm` runs at the alarm's time by `room.now()`,
  never early, from the tick loop. A hibernated room wakes for it, with
  `onWake`'s `reason` set to `"alarm"`, and then runs `onAlarm` at once.
  When it can't wake in time, as when the project is out of credit, it
  runs at the next wake with `scheduledAt` in the past. `scheduledAt` is
  the time the alarm was set to.
- **At least once.** The alarm is cleared once `onAlarm` returns or its
  promise resolves, unless it set a new one. Setting it again to the
  same time once that time has come doesn't count as a new one. A room
  host that crashes inside it runs it again, so make it safe to repeat.
- **Retries.** An `onAlarm` that throws runs again after 2, 4, 8, 16, 32
  and 64 seconds (`ALARM_RETRIES`), with `retry` counting from 0, then
  the alarm is dropped and the error logged. One that set a new alarm
  before throwing keeps the new one and isn't retried, unless the new
  one is already due, which runs on the same schedule.
- **Limits.** `setAlarm` throws a `RangeError` for a time more than 365
  days ahead (`MAX_ALARM_AHEAD`) or one that isn't a finite number. A
  time in the past fires at once. Native rooms have no alarms.
- **What it costs.** A room that wakes for its alarm with no one
  connected hibernates again as soon as `onAlarm` is done, and is billed
  at least 10 seconds for the wake. A room with no connections stays
  active while its alarm is less than 2 minutes away. A pending alarm
  counts as activity for the room's retention.
- **Many alarms at once.** Alarm wakes are limited to 50 a second per
  project, so thousands of rooms with an alarm at the same time, such as
  a daily reset, run late. Add a few minutes of jitter to such times.

`irt dev`, `@irt/testing` and the self-hosted room host fire alarms in
process; in `@irt/testing` they follow the test clock, so
`room.host.advance` reaches them.

### Sleeping rooms

A room can hibernate while its players stay connected: it sleeps, the
router holds their connections, and the next thing a player does wakes
it. No one leaves, and time asleep costs no room-hours. It suits
turn-based and board games, chat, presence pages and lobbies, where
players stay connected but little happens.

```ts
export default defineRoom({
  sleep: { after: 60_000 },
  onWake(room, { reason, slept }) {
    // reason "message": a held connection sent something; slept: true
  },
});

room.sleep();   // sleep now, once no call is in flight
```

- **Opt in.** With `sleep.after`, the room sleeps once it has gone that
  long with no frame from any client but a ping, nothing sent,
  broadcast or stored, no call or server API request in flight, and no
  player's presence in its grace. Without it, a room sleeps only through
  `room.sleep()`. Opting in promises that the room keeps every deadline
  in its [alarm](#alarms), not in `setTimeout` or by counting ticks, and
  keeps in room state, or rebuilds in `onWake`, anything else it needs.
- **What's kept.** Presence, and each connection with its `data` as JSON
  of at most `MAX_SLEPT_DATA` (4 KB); a connection's `data` over that,
  or that doesn't serialize, wakes as `{}` and the room logs it.
  `onLeave` and `onPlayerLeave` don't run; `onHibernate` does.
- **What wakes it.** A message, call, owner write or presence status
  from a held connection, which the router holds and delivers after the
  wake, in order; a held connection closing, so the others see the
  player leave; a new connection; the alarm; a server API call.
  Unreliable messages and inputs are dropped while it sleeps, and the
  router answers pings. When the last held connection closes, the room
  stays asleep, and its next wake runs `onLeave` for everyone it saved.
- **At the wake.** Each connection comes back with a new ID and its
  `data`, without `onJoin`. `onWake` runs with `slept: true`, then
  `onLeave` for saved connections that didn't come back, whose players
  leave presence after the grace, then what they sent, then ticks
  resume and every client gets a full state update.
- **When it doesn't sleep.** The host refuses while the alarm is due
  within 2 minutes, and the room asks again after its next idle period.
- **Limits.** A project's sleeping rooms hold at most
  `limits.maxSleepingConnections` connections in a region, 10,000 by
  default; past it, a room that sleeps closes its connections with
  4011, as `requestHibernate` does. A held connection may send 64
  messages or 256 KB before its room wakes; past it, it closes with
  4006. Native rooms don't sleep.
- **What it costs.** Every wake is billed at least 10 seconds, so a room
  that calls `room.sleep()` after every message pays 10 seconds a
  message; `sleep.after` avoids that. Held connections are metered, at
  no charge for now; see [Credit](/docs/limits#credit).

Clients of `@irt/client` see `room.asleep` and the `sleep` and `wake`
events; calls made while the room sleeps are answered after it wakes.
`irt dev`, `@irt/testing` and the self-hosted room host hold sleeping
rooms' connections in process, as the router does.

Order within a tick: `room.tick` increments, then `onPlayerLeave` runs
for players whose presence ends, then owner writes are
applied through `onWrite`, then the stepper runs with
this tick's inputs, then `onTick`, then the state update goes to every
connection, then input acks. Messages are handled as they arrive,
between ticks, and their writes go out with the next tick's state
update.

A joining connection doesn't wait for a tick: it gets the full state as
soon as `onJoin` has run, or once the promise an async `onJoin` returns
settles. That update carries the tick that last ran, and it also sends
every other connection the changes made since that tick, so each
connection still gets one ordered stream. Join time is the round trip
plus `onJoin`, whatever the tick rate, so an idle game can run at
`tickRate: 1`.

Because `onLeave` and `onPlayerLeave` run before every hibernation and
`onJoin` runs again after a crash, where a game keeps a player's data
decides what survives; see
[Where player data lives](/docs/guides/state-sync#where-player-data-lives).
A room that creates a player's entity in `onJoin` should reuse the one
already there, and delete it in `onPlayerLeave` rather than `onLeave`,
so a dropped network and a reconnect within 10 seconds keep it:

```ts
// avatars.ts
import { defineRoom, defineSchema, entity } from "@irt/room";

const Avatar = entity("avatar", { owner: "string", x: "f32" });

export default defineRoom({
  schema: defineSchema({ entities: [Avatar] }),
  onJoin(room, conn) {
    const existing = [...room.entities.all(Avatar)].find((a) => a.owner === conn.player);
    conn.data.avatar = existing ?? room.entities.create(Avatar, { owner: conn.player });
  },
  onPlayerLeave(room, player) {
    for (const a of room.entities.all(Avatar)) if (a.owner === player) room.entities.delete(a);
  },
});
```

After a room host crash the room restarts from room state with presence
empty, so `onPlayerLeave` never runs for a player who doesn't come back.
A room that cares deletes, in `onTick`, avatars whose owner has had no
connection for a while.

A `defineRoom` module is one [room type](/docs/concepts#rooms): the
project's only one, named `default`, when `irt.config.ts` has `room`, or
the type it's named under in `rooms`. Each type has its own schema,
`version` and `migrations`, so a lobby type and a match type migrate
their room state independently. A room never changes type, so room code
doesn't check it.

## Room

```ts
interface Room<S, P, D> {
  readonly project: string;
  readonly id: string;
  readonly joinCode: string | null; // the code createRoom gave the room, or null
  readonly meta: unknown;           // the meta the room was created with, or null; fixed for its life
  readonly creator: string | null;  // the player whose client created the room, or null
  readonly from: Handoff | null;    // the handoff that created the room, or null; see below
  readonly tick: number;           // see Ticks; kept across hibernation
  readonly tickRate: number;
  now(): number;                   // wall-clock ms; follows @irt/testing's clock, unlike Date.now()
  readonly entities: Entities;
  readonly presence: Presence;     // who's in the room; see Presence
  readonly state: RoomEntity<S>;   // shared state every connection sees
  private(connection: Connection): RoomEntity<P>;
  private(player: string): RoomEntity<P> | undefined;            // by player ID, connected or not
  private(player: string, opts: { create: true }): RoomEntity<P>; // creates it with defaults if missing
  privatePlayers(): string[];      // the player IDs that have private state
  readonly connections: ReadonlyMap<number, Connection>;
  readonly data: D;                // yours, for this room; not synced, not saved in room state
  send(connection: Connection, message: unknown, opts?: { unreliable?: boolean }): void;
  broadcast(message: unknown, opts?: { unreliable?: boolean; except?: Connection }): void;
  kick(connection: Connection, reason?: string): void;  // 4006
  ban(player: string, opts?: { reason?: string; expiresAt?: number }): void; // 4014, kept in room state
  unban(player: string): boolean;
  bans(): RoomBan[];               // { player, reason, expiresAt: number | null }, unexpired
  muteVoice(player: string, opts?: { expiresAt?: number }): void;  // kept in room state; see Proximity voice
  unmuteVoice(player: string): boolean;
  voiceMutes(): RoomMute[];        // { player, expiresAt: number | null }, unexpired
  requestHibernate(): void;
  sleep(): void;                   // hibernate keeping connections; see Sleeping rooms
  setAlarm(at: number): void;      // wall-clock ms; replaces any alarm set; see Alarms
  clearAlarm(): void;
  readonly alarm: number | undefined;  // the time set, or undefined
  handoff(opts: HandoffOptions): Promise<{ room: string; type: string }>;  // move people to another room; see below
  rewind<K, F>(history: History<K, F>, tick: number): ReadonlyMap<number, PastEntity<K, F>>;  // see History
  record(opts?: { id?: string; private?: boolean; messages?: boolean }): string;  // starts a replay; see below
  stopRecording(): void;
  readonly recording: string | undefined;  // the replay being recorded
  clip(opts: { seconds: number; id?: string }): string;  // keeps the last 1 to 60 seconds
  playerData(player: string): PlayerData;   // a player's data across rooms; see Player data below
  collection(name: string): Collection;     // a collection declared in irt.config.ts
  leaderboard(name: string): Leaderboard;   // a collection with leaderboard settings
}

interface Connection {
  readonly id: number;             // from 1, unique per room generation
  readonly player: string;         // the token's sub, or "guest:<random>"
  readonly meta: unknown;          // the token's meta claim, or null
  data: Record<string, any>;       // yours; not saved in room state
  readonly viewTick: number;       // the tick the player saw when it sent this tick's input; see below
  readonly input: unknown;         // the input applied this tick, in the stepper and onTick; see below
  readonly rtt: number | undefined; // the client's lowest recent round trip in ms, as it reports it
  readonly protocol: number;       // the client protocol the connection speaks
}

interface HandoffOptions {
  players: Iterable<string | { player: string }>;  // people connected to this room, by ID or presence entry
  to: { type: string; quickJoin?: boolean; meta?: Record<string, unknown> };
  stay?: boolean;                  // keep them connected here too; default false
}

interface Handoff {
  lobby: string;                   // the room they came from
  players: { id: string; name: string; status: unknown }[];  // with the presence they had there
  bots: { id: string; name: string; status: unknown }[];     // a lobby's bots, already in room.bots
  behaviour?: string;              // the behaviour those bots run
}
```

- **`meta` and `creator`.** `meta` is what `createRoom`, the server
  API or a quick join gave the room. `creator` is the player whose
  client created it: through `createRoom` with a token, a quick join,
  or by connecting to a room that didn't exist, guests included. A room
  created through the server API, or by `createRoom` without a token,
  has none. Both are the same after every wake.
- **`handoff`** asks the router to move people connected to this
  room into another room: a new private room of `to.type` with
  `to.meta`, or with `quickJoin` a public room of it whose `meta`
  matches, with space for all of them. The router holds a seat there for
  each and tells their clients, which connect by themselves and leave
  this room unless `stay` is set. It resolves to the new room's ID and
  type once they've been told. It rejects with an `Error`, sending
  nothing, for a bot, a player who isn't connected, or one whose client
  is older than protocol 4, and with `HandoffFailed`, whose `reason` is `players` (none of them was
  still connected), `limit` (the project is at `limits.maxRooms`, or the
  room handed off 6 times in the last minute), `spending`,
  `unavailable` (the room couldn't be made, or the router didn't answer
  within 15 seconds) or `invalid`, and nobody moves. See
  [Lobbies and parties](/docs/guides/lobbies#from-your-own-room-code).
- **`from`** is set in a room a handoff created, from a lobby or another
  room's `handoff`, before `onCreate` and after every wake; it's `null`
  otherwise, and in a room a handoff's quick join picked or made. A lobby's bots are in `room.bots` with their IDs, names and
  statuses before `onCreate`, running `from.behaviour`.
- **`rtt`** is what the client reports in its pings, undefined until
  its first and for a client older than protocol 3. A client can lie
  about it, as about its view tick, so cap what a game gives for it,
  such as the latency a rhythm hit is judged with.

- **View tick.** Each input carries the tick of the room state the
  player was looking at when it sent it: behind the input's tick by the
  round trip and the client's interpolation delay. `viewTick` is that
  tick for the input applied this tick, or the last one applied, and
  never more than `MAX_REWIND_MS` (250 ms) behind the room. Rewind to it
  with [`room.rewind`](#history) to check a hit against what the shooter
  saw.
- **Input.** `input` is the input applied this tick, as the stepper's
  `parseInput` returned it, or `undefined` when the player sent none for
  this tick or the room has no stepper. It's set before the stepper runs
  and cleared after `onTick`, so `onTick` can act on a shot in the input
  with the `viewTick` it was aimed at. It's `undefined` between ticks.
- **Messages.** A `Uint8Array` is sent as a binary message; anything else
  as JSON. A message is at most 64 KB; `send` and `broadcast` throw a
  `RangeError` over that. `unreliable: true` sends a WebTransport
  datagram, or over WebSocket in order with stale ones dropped. Clients
  may send at most 120 messages per second; over that the router closes
  them with 4005.
- **Private state** is kept by player ID, so a player who reconnects or
  rejoins gets theirs back. It's created with defaults at the player's
  first join, and dropped once the player has been away for the room's
  `privateRetention` of wall-clock time, hibernated time included,
  checked on wake and every 30 seconds. `privateRetention` defaults to
  `PRIVATE_RETENTION`, 24 hours, so a room many players pass through
  doesn't keep everyone's forever; `"forever"` keeps it as long as the
  room.
- **`private(player)`** with a player ID works whether or not the
  player is connected: give an item to a teammate who's away, credit
  loot to a player who dropped, or grant one from `onRequest`. It
  returns `undefined` for a player with no private state, and creates
  nothing, so a mistyped or hostile ID from a message doesn't allocate
  room state. `private(player, { create: true })` creates it with
  defaults, as the player's first join would, so a backend can grant an
  item before the player ever joins; its retention then counts from that
  moment until the player connects. Only create for IDs you trust: with
  `privateRetention: "forever"`, state created for an ID that never
  joins is never dropped. A changed field reaches the player when
  they're connected, and is in room state either way. A player ID that's
  empty or over 256 characters throws a `TypeError`. With a connection,
  `private(conn)` always returns that connection's state.
  `privatePlayers()` lists the player IDs that have private state, the
  connected ones included.
- **`kick(connection, reason?)`** closes the connection with 4006. The
  client doesn't reconnect by itself, but the player can join again.
  `reason`, at most `MAX_CLOSE_REASON` (123) UTF-8 bytes or it throws,
  reaches the client as `IrtError.reason`. `onLeave` runs for the
  connection. A connection kicked before its first state update, as from
  `onJoin` before any `await`, never shows in any client's presence.
- **`ban(player, { reason, expiresAt })`** bans a player from this room
  only: their open connections close with 4014 and `reason`, and later
  ones are closed the same way before `onJoin` runs or presence shows
  them. `expiresAt` is wall-clock milliseconds, as `Date.now()` gives;
  without it the ban lasts until `unban`. Bans are kept in room state, so
  they survive hibernation, and they're in `RoomData.bans`; a migration
  can't drop them. A room holds `MAX_ROOM_BANS` (10,000). To keep a player out of
  every room of the project, ban them from your backend, the dashboard or
  the CLI; see [Moderation](/docs/moderation).
- **`requestHibernate`** hibernates the room now. Open connections run
  `onLeave` and are closed with 4011; their clients don't reconnect by
  themselves. Server API messages the room is still answering finish
  first, so an `onRequest` that calls it still sends its reply, and what
  it writes is in the room state. Messages that arrive meanwhile get an
  error.
- **`sleep`** asks to sleep: hibernate while the router holds the
  room's connections; see [Sleeping rooms](#sleeping-rooms).
- **Alarms.** `setAlarm(at)` asks for `onAlarm` at `at`; see
  [Alarms](#alarms).
- **Replays.** `record` starts recording what a connection that sees
  everything would see, without private state unless `private: true`,
  and returns the replay's ID; it stops at hibernation and must be
  started again in `onWake`. `clip` keeps the end of the recording past
  its retention. Both throw past their limits. See
  [Replays and clips](/docs/guides/replays).
- One connection per player: when a player connects again, the older
  connection closes with 4012 and `onLeave` runs for it before `onJoin`
  for the new one. The older client doesn't reconnect.

## Player data, collections and leaderboards

```ts
interface PlayerData {
  get<T>(key: string): Promise<{ value: T; version: number } | undefined>;
  set(key: string, value: unknown, opts?: WriteOptions): Promise<{ version: number }>;
  increment(key: string, by?: number, opts?: { once?: string }): Promise<number>;   // creates the key at 0
  delete(key: string, opts?: WriteOptions): Promise<boolean>;
  list(): Promise<{ key: string; value: unknown; version: number }[]>;
  refresh(): Promise<void>;                                  // drops what the room's cache holds
}

interface Collection {
  get<T>(id: string): Promise<Entry<T> | undefined>;
  put(entry: { id?: string; value: unknown; meta?: Meta; score?: number | null; owner?: string | null; version?: number; once?: string }): Promise<{ id: string; version: number }>;
  list(opts?: { where?: Meta; owner?: string; order?: EntryOrder; limit?: number; after?: string | null }): Promise<{ entries: EntrySummary[]; next: string | null }>;
  delete(id: string, opts?: WriteOptions): Promise<boolean>;
  refresh(): void;
}

interface Leaderboard {
  submit(player: string, score: number, opts?: { meta?: Meta; once?: string }): Promise<{ period: string; score: number }[]>;
  top(opts?: { period?: string; limit?: number; after?: string | null }): Promise<{ entries: RankedEntry[]; next: string | null }>;
  around(player: string, opts?: { period?: string; count?: number }): Promise<{ rank: number; entries: RankedEntry[] } | undefined>;
  refresh(): void;
}

type Meta = Record<string, string | number | boolean>;   // flat, at most 1 KB
// `version` must match, 0 meaning none. A write with a `once` key the project used in the last
// day resolves as the first did without writing again; see Player data.
interface WriteOptions { version?: number; once?: string }
type EntryOrder = "score" | "-score" | "created" | "-created" | "updated" | "-updated";
interface EntrySummary { id: string; meta: Meta; score: number | null; owner: string | null; version: number; created: number; updated: number }
interface Entry<T> extends EntrySummary { value: T }
interface RankedEntry { rank: number; player: string; score: number; meta: Meta; updated: number }
```

Player data is per player per project, so it outlives every room;
collections and leaderboards are per project, declared under
`settings.data` in `irt.config.ts`. The guide is
[Player data, collections and leaderboards](/docs/guides/player-data).

- **Values** are JSON or a `Uint8Array`, at most 64 KB. A player has at
  most 256 keys and 1 MB. Keys and entry IDs are 1 to 64 of
  `A-Z a-z 0-9 _ . : -`.
- **Versions** start at 1 and go up on every write. `version` on `set`,
  `put` and `delete` makes the write fail with `E_VERSION` unless the key
  or entry has it; `0` means it must not exist. `increment` takes none.
- **Lists** give at most 100 entries a page, 20 by default, without
  values; pass `next` as `after`. `where` matches `meta` keys by
  equality. Ties go by `id`; entries without a score come last in both
  `score` orders. `put` replaces the whole entry and keeps `created`.
- **Leaderboards.** `submit` applies the board's `keep` to every period
  it declares. `period` is `"all"` (the default), `"day"`, `"week"` or
  `"month"` for the current one in UTC, or a full name such as
  `"day:2026-11-06"`, `"week:2026-W45"` or `"month:2026-11"` for one of
  the three before it. Ranks go by score, then the earliest `updated`.
  `count` on `around` is 0 to 10, default 2.
- **The cache.** A `get` within 5 seconds of the room's last read or
  write of the same key or entry comes from memory, so the room sees its
  own writes at once and other writers' within 5 seconds. `refresh()`
  drops what the room holds of that player or collection. `list`, `top`
  and `around` are never cached.
- **Errors.** Calls reject with `DataError` from `@irt/room`, whose
  `code` is `E_INVALID`, `E_FORBIDDEN`, `E_UNKNOWN`, `E_VERSION`,
  `E_TYPE`, `E_QUOTA`, `E_LIMIT`, `E_SPENDING` or `E_UNAVAILABLE`; see
  [Errors](/docs/reference/errors#data-calls). After `E_UNAVAILABLE` a
  write may or may not have happened: retry it with `version`. A room
  host whose parent is too old for data calls gets `E_UNAVAILABLE` for
  every one.
- A room makes at most 200 data calls a second and 64 at once.

## Room data and module scope

A room host loads the room module once and runs many rooms of it, of
one build, in one process. So a variable at the top level of the
module, or of any module it imports:

- is shared by every room in that room host, which start, hibernate and
  stop independently of each other;
- outlives a room that hibernates, holding whatever it left there, and
  doesn't follow the room when it wakes in another room host;
- is lost when the room host restarts, crashes or drains.

Keep constants, schemas, steppers, `grid` objects and other code that
reads no room's data at module level. Keep a room's own derived data,
such as a lookup table built from its entities, in `room.data`: one
plain object per room, not synced and not saved in room state. It starts
as what `data()` returns, or `{}`, each time the room starts or wakes, so
build it in `onCreate` and again in `onWake`. `data()` also types it:

```ts
// spawns.ts
import { defineRoom, defineSchema, entity, type RoomEntity } from "@irt/room";

const Spawn = entity("spawn", { team: "string", x: "f32", y: "f32" });
type S = RoomEntity<typeof Spawn>;

function byTeam(spawns: Iterable<S>): Map<string, S[]> {
  const out = new Map<string, S[]>();
  for (const s of spawns) out.set(s.team, [...(out.get(s.team) ?? []), s]);
  return out;
}

export default defineRoom({
  schema: defineSchema({ entities: [Spawn] }),
  data: () => ({ byTeam: new Map<string, S[]>() }),
  onCreate(room) {
    room.entities.create(Spawn, { team: "red", x: 0, y: 0 });
    room.entities.create(Spawn, { team: "blue", x: 100, y: 0 });
    room.data.byTeam = byTeam(room.entities.all(Spawn));
  },
  onWake(room) {
    room.data.byTeam = byTeam(room.entities.all(Spawn));
  },
  onJoin(room, conn) {
    const team = (conn.meta as { team?: string } | null)?.team ?? "red";
    conn.data.spawn = room.data.byTeam.get(team)?.[0];
  },
});
```

`room.data` holds entity objects safely: entities are new objects after
a wake, and so is `room.data`. Steppers don't get `room`; for data a
stepper needs, see [Entity IDs and lookups](/docs/guides/state-sync#entity-ids-and-lookups).
A stepper's own caches key by the `world` that `step`, `save` and `load`
get, one object per room; see [Steppers](/docs/room-state#steppers).

## Calling your backend

Room code may call out over HTTPS with `fetch`, to the game's own
backend or any public API. Authenticate with a [secret](/docs/cli#irt-secrets),
which room code reads from `process.env`.

Deployed rooms run in VMs with no network interface, and `fetch` goes
through an egress proxy without room code doing anything. The proxy
allows:

- `https://` URLs on port 443, by host name. An IP address in the URL,
  another port, and a host name that resolves to a private, loopback or
  link-local address are refused, and `fetch` rejects.
- `fetch` only. `http://` URLs, `node:http` and `node:https`, libraries
  built on them such as axios, WebSocket clients and raw sockets have no
  network.
- 64 connections open at once and 10 MB a second in both directions
  together, per VM, which runs many of a project's rooms. A connection
  idle for 5 minutes is closed.

Outbound traffic isn't billed. It is counted for
[acceptable use](/docs/acceptable-use), which bans running a proxy.
There's no timeout of IRT's own on a call, so pass one, as below.

`irt dev`, `@irt/testing` and the staging stack run rooms as processes
on the machine, where `fetch` has the machine's network: `http://`,
other ports and `localhost` work there, and not when deployed.

IRT never retries a hook or a call, except `onAlarm` when it throws, and
only `onCreate`, `onWake` and `onHibernate` are awaited. So:

- Make every write safe to repeat, with an ID the backend recognises: a
  `fetch` can time out after the backend applied it.
- Send one room's calls one at a time when their order matters, such as
  a player's last save before the release that follows it.
- Wait for calls in flight in `onHibernate`, so a room doesn't sleep
  with them unsent. `onLeave` runs for every connection before it.

```ts
// backend.ts
import { defineRoom, defineSchema, entity } from "@irt/room";

const Score = entity("score", { total: "u32" });

async function save(player: string, total: number, id: string): Promise<void> {
  const res = await fetch("https://api.example.com/scores", {
    method: "POST",
    headers: { authorization: `Bearer ${process.env.BACKEND_KEY}`, "content-type": "application/json" },
    body: JSON.stringify({ id, player, total }),
    signal: AbortSignal.timeout(5000),
  });
  if (!res.ok) throw new Error(`saving the score failed with ${res.status}`);
}

export default defineRoom({
  schema: defineSchema({ state: Score }),
  data: () => ({ calls: Promise.resolve() }),
  onLeave(room, conn) {
    const total = room.state.total;
    const id = `${room.id}:${conn.player}:${room.tick}`;
    room.data.calls = room.data.calls.then(() => save(conn.player, total, id)).catch((e) => console.error(e));
  },
  async onHibernate(room) {
    await room.data.calls;
  },
});
```

## Entities

```ts
class Entities implements World {
  create<K extends Kind>(kind: K, values?: Partial<ValuesOf<K>>, opts?: { id?: number; owner?: string }): RoomEntity<K>;
  delete(entity: Entity): void;
  setOwner(entity: Entity, owner: string | undefined): void;   // a player ID, or undefined for the room
  ownerOf(entity: Entity): string | undefined;
  ownedBy<K extends Kind>(player: string, kind: K): IterableIterator<RoomEntity<K>>;
  get(id: number): RoomEntity | undefined;
  all<K extends Kind>(kind: K): IterableIterator<RoomEntity<K>>;
  readonly count: number;
}

type RoomEntity<K> = ValuesOf<K> & {
  readonly id: number;
  readonly kind: K;
  patch(field: BytesField<K>, offset: number, bytes: Uint8Array): void;
};
```

- Entity IDs are assigned from 2; 0 and 1 are the shared and private
  state. An automatic ID is above every ID the room has used, so it's
  never reused.
- `{ id }` sets the ID instead: an integer from 2 to `MAX_ENTITY_ID`
  (2^32 − 1) that no live entity has, such as one computed from a
  chunk's coordinates.
  Otherwise `create` throws, a `RangeError` for an ID out of range and an
  `Error` naming the live entity that has it. See
  [Entity IDs and lookups](/docs/guides/state-sync#entity-ids-and-lookups).
- `get(id)` is a map lookup. `all(kind)` visits every entity of the kind
  on each call. `get(0)` and `all` of the state kind give `room.state`,
  as a stepper's world does on both sides. `count` is the number of entities, hidden ones
  included; `room.state`, private state and presence aren't entities
  here, unlike on the client.
- Fields missing from `create` get defaults: `false`, `0`, `""`, empty
  bytes, `null`.
- `{ owner }` and `setOwner` give an entity to a player, who may then
  write its kind's writable fields from the client. They throw for a
  hidden kind, and for an owner that isn't a non-empty player
  ID of at most `MAX_PLAYER_ID` (256) characters. See
  [Ownership](/docs/guides/ownership).
- A write of the wrong type throws a `TypeError`; an integer out of range
  or a value over its size limit throws a `RangeError`, naming the field.
- See [State sync and interest](/docs/guides/state-sync) for field types,
  size limits and how writes are tracked.

## Presence

```ts
interface Presence {
  get(player: string): PresenceEntry | undefined;
  readonly size: number;
  [Symbol.iterator](): IterableIterator<PresenceEntry>;
  set(player: string, values: { name?: string; status?: unknown }): void;
}

interface PresenceEntry {
  readonly player: string;
  readonly name: string;        // MAX_PRESENCE_NAME (64) characters at most
  readonly status: unknown;     // JSON, MAX_PRESENCE_STATUS (1024) bytes at most; null until set
  readonly connected: boolean;
}
```

- The runtime adds a player's entry before `onJoin` and removes it
  `PRESENCE_GRACE` (10 seconds) after its last connection closes; from
  the tick after that close until then, `connected` is false. A player
  who reconnects in time keeps its entry and status.
- `name` starts as the `name` string of the token's `meta`, when it has
  one of at most 64 characters, else `""`. The player writes `status`
  from the client; `onWrite` isn't called for it.
- `set` throws for a player with no entry or a value over its limit. A
  status it sets differently from the player's write reaches the player
  as a correction.
- Every connection sees every entry, whatever `interest` says, unless
  the room defines `seesPresence(room, viewer, entry)`: then a viewer
  sees another player's entry only while it returns true, such as to
  hide players the viewer blocked. It runs each tick for every pair, so
  keep it cheap, and a player always sees its own entry. An entry
  counts toward the 16,384 entities a connection sees.
- A player banned with `room.ban`, or kicked before its first state
  update, never gets an entry anyone sees. A room
  holds at most `MAX_PRESENCE` (1,024) entries; past that, the entry of
  the player gone longest makes room.
- Presence isn't room state: it's empty after a wake until clients
  reconnect. `room.entities` doesn't hold it, and it doesn't change the
  IDs entities get. See [Presence](/docs/guides/presence).

## Schemas

```ts
function entity<F extends Record<string, FieldType>, W extends keyof F>(name: string, fields: F, opts?: { writable?: readonly W[]; ownerOnly?: readonly (keyof F)[]; hidden?: boolean }): Kind<F, W>;
function json<T = unknown>(): Json<T>;   // a json field typed T; "json" at runtime, same schema hash
function defineSchema<S extends Kind, P extends Kind, C extends Calls>(decl: { state?: S; private?: P; entities?: readonly Kind[]; calls?: C; input?: Kind }): Schema<S, P, C>;

class Schema<S, P, C> {
  readonly hash: number;           // sent by clients in hello; a mismatch is close code 4004
  readonly state: S;
  readonly private: P;
  readonly entities: readonly Kind[];
  readonly calls: C;               // not part of the hash
  readonly input: Kind | undefined;  // part of the hash when set
}
```

- `{ hidden: true }` declares a hidden kind. Its entities are room
  state like any other: saved, restored on wake, kept across a room host
  crash, and read and written through `room.entities` in hooks and
  calls. A stepper must not depend on them: the room's `world` is
  `room.entities` and holds them, but a client's prediction world never
  does, so a step that reads them predicts differently from the room.
  The room never sends them to a connection: they get no
  interest keys, whatever `interest` returns, voice doesn't see them,
  and their creation, changes and deletion send nothing. Only the
  inspector in `irt dev` shows them, marked hidden. See
  [Hidden entities](/docs/guides/state-sync#hidden-entities).
- `entity` throws for a hidden kind with `writable` or `ownerOnly`
  fields, since no player could see an entity it owned, and `{ owner }`
  and `setOwner` throw for its entities.
  `defineSchema` throws for a hidden `state` or `private` kind.
- `ownerOnly` fields are sent only to the connections of the entity's
  owner; see [Ownership](/docs/guides/ownership). `defineSchema` throws
  for them on the `state`, `private` or `input` kind.
- A hidden kind is in the schema and its hash like any kind, and its
  declaration is in the client's bundle with the schema module; its
  entities' values never are.

`input` declares the fields of the stepper's inputs as a kind, so
prediction inputs go as binary in that layout instead of as JSON; see
[Compact inputs](/docs/guides/prediction#compact-inputs). It's never an
entity, and it can't have writable fields. A schema without one has the
same hash as before schemas could declare it.

## Calls

```ts
function defineCalls<T extends { [name: string]: (args?: any) => unknown }>(parse?: { [name in keyof T]?: (raw: unknown) => Args }): Calls<T>;
```

A call is a request from one client that the room answers, apart from
state sync. The schema declares the calls with `defineCalls`, as a type
of signatures with at most one argument, and the room's `calls` has a
handler for each, checked against it: its `args` have the declared type
and it returns or resolves to the declared reply. The client's `call` is
checked against the same declaration; see the
[calls guide](/docs/guides/calls).

- Args and replies are JSON, or bytes as a `Uint8Array`, at most 64 KB.
  A reply of `undefined` arrives as `null`.
- Args come from the client and the types don't check them at runtime.
  Without a `parse` function the handler gets the decoded JSON as is, so
  it must not trust it. With one, the room runs it on the decoded JSON
  or bytes first and passes what it returns to the handler; if it
  throws, the call rejects with the error's message and the room
  doesn't log it.
- A handler rejects a call by throwing; the client's `call` rejects
  with the error's message. `throw new CallRejected(message)` is an
  expected rejection, such as a game rule, and isn't logged; any other
  error is logged at error level with its stack.
- A handler runs as the call arrives, between ticks, like `onMessage`.
  When it changed room state, its reply goes out after the next tick has
  saved the change and sent its state update, so a reply means the
  change is saved outside the VM; otherwise, and for errors, at once.
- A call in flight when the connection drops or the room restarts
  fails on the client and isn't retried. The handler may or may not
  have run.

## Interest

```ts
interface Interest {
  keysOf(room: Room, entity: RoomEntity): Iterable<string | number>;
  subscriptionsOf(room: Room, connection: Connection): Iterable<string | number>;
  sees?(room: Room, connection: Connection, entity: RoomEntity): boolean;   // narrows what shares a key, before limit
  limit?: { max: number; priority(room: Room, connection: Connection, entity: RoomEntity): number };
}

type GridOptions = {
  cellSize: number;
  dims: "xy" | "xz" | "xyz";
  position?: (room: Room, e: RoomEntity) => Position | undefined;
  around(room: Room, c: Connection): RoomEntity | Position | undefined;   // an entity is placed by `position` too
  prefix?: string;                 // starts every key the grid gives, EVERYWHERE included
  kinds?: Kind[];                  // the kinds it places; others get no key from it
} & ({ range: number } | { radius: number });   // one of the two
type InterestPart = Pick<Interest, "keysOf" | "subscriptionsOf" | "sees">;
function grid(opts: GridOptions): InterestPart;
function combine(...parts: InterestPart[]): Required<InterestPart>;
function cellKey(...cell: number[]): string;  // "3,-1" or "3,-1,0"
const EVERYWHERE = "*";
```

- `range` is a distance in world units. A connection sees exactly the
  entities within it of `around(connection)`: a circle on `"xy"` and
  `"xz"`, a sphere on `"xyz"`. The grid picks the cells that overlap it
  and its `sees` drops the rest.
- `radius` is a whole number of cells. A connection sees every entity in
  the square, or cube, of cells within `radius` cells of its own cell on
  each axis, so the distance it sees varies with where it stands in its
  cell. `sees` is undefined.
- `grid` throws a `TypeError` given both or neither.
- `combine` joins parts into one interest: a connection sees an entity
  when, in some part, they share a key and that part's `sees`, if any,
  passes it. Each grid keeps its own cells and range. Spread it to add a
  `limit`: `{ ...combine(a, b), limit }`. See
  [Combining grids and keys](/docs/guides/state-sync#combining-grids-and-keys).

Caps: 4,096 subscribed keys and 16,384 visible entities per connection.
See [State sync and interest](/docs/guides/state-sync#the-grid).

## Room state and migrations

Room state is the room's entities, `room.state`, every player's private
state, the tick, and what the stepper's `save(world)` returned for the room. The SDK saves it
by itself: after each tick with changes it streams the changes out of
the room host, and every 30 seconds it writes a full copy. Room state is
at most 32 MB; a room whose room state grows past that stops with the
reason `room state is N MB; the limit is 32 MB`.

A build that changes room state's shape increments `version` and adds an
up migration for each version step. A migration receives plain data and
returns it at the next version:

```ts
type Migration = (data: RoomData) => RoomData;

interface RoomData {
  version: number;
  tick: number;
  savedAt: number;                 // wall-clock ms when it was written
  nextId: number;
  state: Record<string, unknown>;
  private: Record<string, Record<string, unknown>>;  // by player ID
  privateSeen: Record<string, number>;               // when each player was last connected
  entities: { id: number; kind: string; values: Record<string, unknown> }[];
  stepper: unknown;
}
```

```ts
// migrations.ts
import { defineRoom, defineSchema, entity } from "@irt/room";

// Version 1 had { hp: "u8" }; version 2 renames it to health and adds a team.
const Player = entity("player", { owner: "string", health: "u16", team: "string" });

export default defineRoom({
  schema: defineSchema({ entities: [Player] }),
  version: 2,
  migrations: {
    2: (data) => ({
      ...data,
      entities: data.entities.map((e) =>
        e.kind !== "player"
          ? e
          : { ...e, values: { owner: e.values.owner, health: e.values.hp, team: "red" } },
      ),
    }),
  },
});
```

On wake, room state written at an older version runs through each
migration in turn. A missing migration, a kind or field the build doesn't
declare, or a value of the wrong type stops the room with a reason that
says which. Fields the build declares and the data lacks get defaults.

There are no down migrations. `irt build` records `version` in the
build, and when a rollback makes an older build live, a room whose
room state is at a newer version wakes from the room state kept from
before its migration instead; see
[New builds](/docs/hibernation#new-builds).

## Ticks

The room host runs every room's ticks with a fixed timestep. Rooms in one
room host tick at staggered phases. After a stall a room runs at most 4
ticks to catch up and drops the rest. Ticks stop while a room is
hibernated; on wake `onWake` gets the elapsed time instead of catch-up
ticks. Ticks still run for the 30 seconds before an empty room
hibernates; see [Timers across hibernation](/docs/hibernation#timers-across-hibernation).

`room.tick` counts the ticks the room has run:

- It's 0 in `onCreate`. A tick first increments it, then runs the
  stepper and `onTick`, so inside the stepper and `onTick` it's the
  number of the tick running, 1 for a new room's first.
- Between ticks, in `onJoin`, `onMessage`, `onLeave` and `onRequest`, it's
  the number of the last tick run. Writes made there go out with tick
  `room.tick + 1`.
- It's kept in room state, so it carries on across hibernation and
  crashes, and it doesn't count time spent hibernated.
- The client's `room.tick` is the tick of the last state update it
  applied.

So a round that starts in `onTick` and lasts 60 seconds at 20 ticks per
second can store `endsAt = room.tick + 1200` and end in the `onTick`
where `room.tick >= endsAt`, exactly 1200 ticks later. Tests can run it
to the tick with [`host.tick(n)`](/docs/reference/testing#testhost).

The room host times each tick's parts and each hook, and under `irt dev`
the inspector shows p50, p95 and max per second; see
[the tick profiler](/docs/dev-tools#the-tick-profiler).

## History

```ts
function defineHistory<K extends Kind, F extends RecordableField<K>>(kind: K, fields: readonly F[]): History<K, F>;

type PastEntity<K, F> = { readonly id: number } & Readonly<Pick<ValuesOf<K>, F>>;

const MAX_HISTORY = 8 * 1024 * 1024;   // bytes, all of a room's histories together
```

A history is the fields of one entity kind that a room records after
each tick's state update, for [lag compensation](/docs/guides/lag-compensation).
List it in the definition's `history`. `room.rewind(history, tick)`
returns the entities of the kind as tick `tick`'s state update sent
them, keyed by ID, each a frozen `{ id, ...fields }`:

- An entity that didn't exist at `tick` is absent.
- A tick older than the oldest kept is clamped to it. A tick not yet
  recorded, such as `room.tick` in `onTick`, or a later
  one, gives the entities as they are now. A fractional tick is rounded
  down.
- The room keeps `ceil(tickRate × MAX_REWIND_MS / 1000) + 2` ticks: 7 at
  20 ticks a second, 32 at 120.
- Each recorded entity costs 8 bytes per field per kept tick, plus 128
  bytes. Past `MAX_HISTORY`, new entities aren't recorded until deleted
  ones leave the kept ticks, and the room logs an error once.
- The history isn't room state: it's never saved and starts empty when
  the room starts or wakes.

`defineHistory` throws a `TypeError` for a field the kind doesn't have, a
`string`, `bytes` or `json` field, a field listed twice, or no fields.
`defineRoom` throws when `history` lists a kind that isn't one of the
schema's entity kinds. `room.rewind` throws for a history the
definition doesn't list, and a `TypeError` for a tick that isn't a
finite number.

Steppers don't get `rewind`: a stepper runs on the client too, which
keeps no history. Check hits in `onTick`.

## Running rooms yourself

The room host is the `irt-room-host` command in `@irt/room`. Given a
build directory from `irt build`, or a bundled room module as the type
`default`, it serves clients directly over WebSocket with room state on
disk, every room type of the build included, which is what `irt dev`
runs:

```sh
npx irt-room-host .irt/build/stage
```

[Self-hosting](/docs/self-hosting) covers its configuration: port,
address, data directory, signing keys, guest key, settings and site.
Two more variables run it under a host daemon instead:

| Variable | Default | Meaning |
|---|---|---|
| `IRT_ROOM_HOST_SOCKET` | none | When set, connect to this Unix socket as a room host instead |
| `IRT_BUILD` | empty | The build ID the room host reports on its socket |

Under a host daemon it runs the build's standard room types, loading
each type's module when its first room starts; native types run in
the host daemon's native room host instead.

A watchdog kills the process if its event loop is blocked for more than
5 seconds.

## Common mistakes

- **Doing slow work in `onTick`.** Rooms in a room host share one event
  loop; a long tick delays every room in it.
- **Keeping game state in module variables, `room.data` or `conn.data`.**
  None of them is room state; it's lost on hibernate and on a room host
  restart. Use entities, `room.state` and private state.
- **Keeping one room's data in a module variable.** Every room in the
  room host shares it. Use `room.data`; see
  [Room data and module scope](#room-data-and-module-scope).
- **Throwing from `onMessage` to reject a message.** It works, but it's
  logged as an error. Return early instead.
- **Expecting `onLeave` after a crash.** A room host that crashes runs no
  hooks; the room wakes from its room state and `onWake` runs, then
  `onJoin` for each player who reconnects. Find a player's entity from
  before rather than creating a second one.
- **Storing what should last on an entity deleted in `onLeave`.**
  `onLeave` runs before every hibernation, so it's gone then too. See
  [Where player data lives](/docs/guides/state-sync#where-player-data-lives).
- **Changing a kind without a migration.** A field the build doesn't
  declare in old room state stops the room on wake.
- **Holding entity objects across hibernation.** Entities are new objects
  after a wake; find them again in `onWake` or by ID.

---

# Client SDK

> Reference for @irt/client, the TypeScript client SDK that connects browsers and Node to rooms.

`@irt/client` runs in browsers and in Node 24 or later. It connects over
WebTransport when the platform has it and falls back to WebSocket; Node
has no WebTransport, so it uses WebSocket. See [Node clients and bots](/docs/guides/node-client)
for running it from scripts.

```ts
import {
  connect, RoomClient, type ReadyRoomClient, IrtError, CloseCode, defineSchema, defineCalls, defineStepper, entity, json,
  createRoom, joinByCode, listPublic, quickJoin, reloadForNewBuild,
  type ConnectOptions, type ConnectionStatus, type ClientEntity, type Prediction, type Interpolator, type WireStats,
} from "@irt/client";
```

## connect

```ts
function connect<S, P, C>(opts: ConnectOptions<S, P, C>): Promise<ReadyRoomClient<S, P, C>>;
// A RoomClient whose state and private are typed as set, since it has been ready.
type ReadyRoomClient<S, P, C> = RoomClient<S, P, C> & { readonly state: ClientEntity<S>; readonly private: OwnedEntity<P> };

interface ConnectOptions<S, P, C> {
  router: string;         // from the project's client config: "wss://eu.irt.io", or "http://127.0.0.1:7350" for irt dev
  project: string;        // the project's slug
  room: string;           // 1 to 64 characters of A-Z, a-z, 0-9, _ and -
  type?: string;          // the room type whose schema this is; default the build's type named default
  token?: string;         // a player token from your backend; without one, the client joins as a guest
  schema?: Schema<S, P, C>;  // the same defineSchema module the room uses
  onWaking?: () => void;  // the room isn't running and the connection waits for it to start: a wake, or a new room's first start
  timeout?: number;       // ms the first connection may take to become ready, waking included; default 15000
  targets?: Record<string, Schema>;  // schemas of the room types a handoff may take the player to, by type
  dial?: Dial;            // replaces the transport, as simulateNetwork and @irt/testing do
}
```

`connect` resolves once the client holds the room's full state, so
`room.state` and `room.private` are set. It rejects with an `IrtError`
when the router can't be reached (code 0, after trying WebTransport and
WebSocket), when the router closes with a code the client doesn't retry
(the close code), or when `timeout` passes first (code 0). After it
resolves, the client reconnects by itself.

`type` is the [room type](/docs/concepts#rooms) the client expects.
A room of another type, or a type the live build doesn't have, closes
the connection with 4015, which reloading doesn't fix. A connection that
creates its room creates it of this type.

```ts
// connect.ts
import { CloseCode, connect, defineSchema, entity, IrtError, reloadForNewBuild } from "@irt/client";

const Table = entity("table", { players: "u8" });
const schema = defineSchema({ state: Table });

try {
  const room = await connect({
    router: "wss://eu.irt.io",
    project: "my-game",
    room: "main",
    schema,
    onWaking: () => console.log("starting the room"),
  });
  console.log(room.player, room.state.players);
  room.on("closed", (error) => {
    if (error.code === CloseCode.RoomHibernated) console.log("offer a rejoin button");
  });
} catch (e) {
  if (e instanceof IrtError && e.code === CloseCode.SchemaMismatch) reloadForNewBuild();
  else throw e;
}
```

**Transports.** WebTransport at `https://<router>/v1/wt`, with one
bidirectional stream for reliable messages and datagrams for unreliable
ones; if it isn't available or doesn't connect within 3 seconds, the
client uses WebSocket at `wss://<router>/v1/ws` and stays on WebSocket
for later reconnects.

**Custom transports.** A `Dial` is `(router: string) => Promise<Transport>`,
called with `router` from the options on every connect and reconnect.
`dialWebSocket(router)` takes the same address and dials its
`/v1/ws`, so a dial can wrap it. A `Transport` may say what carries it
as `kind`, `"webtransport"` or `"websocket"`, which the client shows as
`transportKind`; keep the inner transport's when wrapping one. For
example, to count bytes sent:

```ts
// dial.ts
import { connect, dialWebSocket } from "@irt/client";

let sent = 0;
await connect({
  router: "http://127.0.0.1:7350",
  project: "my-game",
  room: "main",
  dial: async (router) => {
    const t = await dialWebSocket(router);
    const send = t.send;
    t.send = (data, unreliable) => {
      sent += data.length;
      send(data, unreliable);
    };
    return t;
  },
});
```

The client sets the transport's `onmessage` and `onclose` after the dial
resolves, so wrap incoming data by returning a transport of your own
whose handlers the client sets, as the inner one calls them.

It rejects with an `Error` naming the URL it dialled when the socket
closes before opening.

**Guests.** Without a `token`, the router mints a guest token with a
player ID of `guest:<random>`. The client keeps it in `localStorage`
under `irt.guest.<project>` (in memory where there's no `localStorage`
or it's blocked) and sends it on every connect, so a guest keeps its
player ID across reconnects, tabs and browser restarts. The token lasts
30 days and the router renews it on each connect. See
[Games without a backend](/docs/no-backend#guests).

## RoomClient

```ts
class RoomClient<S, P, C> {
  constructor(opts: ConnectOptions<S, P, C>);  // connects; await `ready` instead of connect()
  readonly ready: Promise<void>;
  readonly schema: Schema<S, P, C>;
  readonly entities: EntityStore;
  readonly presence: PresenceList;           // who's in the room; see Presence
  readonly state: ClientEntity<S> | undefined;     // undefined until ready
  readonly private: OwnedEntity<P> | undefined;    // undefined until ready; the player owns its private state
  status: ConnectionStatus;                  // "connecting" | "waking" | "open" | "reconnecting" | "closed"
  asleep: boolean;                           // the room sleeps and the router holds the connection
  connection: number;
  player: string;
  readonly project: string;                  // the project from ConnectOptions
  generation: number;                        // the room's generation; changes when it restarts or wakes
  tickRate: number;
  tick: number;                              // tick of the last state update applied
  rtt: number;                               // smallest recent round trip, in ms
  jitter: number;                            // mean deviation of the recent round trips, in ms
  transportKind: "webtransport" | "websocket" | undefined;  // what carries the connection
  joinTime: { ms: number; started: boolean } | undefined;   // how long joining took; see below
  protocol: number;                          // the client protocol the connection speaks, from welcome
  peers: { speakers: readonly string[]; listeners: readonly string[] };  // see Voice
  voice: { url: string; token: string } | undefined;                     // set when the project uses voice
  readonly stats: WireStats;                 // messages and bytes in and out; see Wire statistics
  serverTick(): number;                      // the room's current tick, estimated, with a fraction
  serverTime(): number | undefined;          // the room's wall clock, room.now(), estimated, in ms

  send(message: unknown, opts?: { unreliable?: boolean; to?: readonly string[] }): void;
  call<K extends keyof C>(name: K, args: Args<K>, opts?: { timeout?: number }): Promise<Reply<K>>;  // args optional when the call takes none
  lead(player: string): Promise<void>;      // native rooms: pass the leader role
  readonly lobby: LobbyState | undefined;   // a lobby's phase, who is ready and the countdown; see Lobbies
  setReady(ready: boolean): Promise<void>;  // lobbies: mark this player ready or not
  start(): Promise<void>;                   // lobbies: the leader starts the countdown, under any start rule
  cancel(): Promise<void>;                  // lobbies: the leader cancels it
  onHandoff(fn: (handoff: Handoff) => void): () => void;  // a lobby or room code moved the player; see Lobbies
  leave(): void;
  on(event: "waking" | "restored" | "sleep" | "wake", fn: () => void): () => void;
  on(event: "disconnected", fn: (code: number, reason: string) => void): () => void;
  on(event: "closed", fn: (error: IrtError) => void): () => void;
  on(event: "message", fn: (message: unknown, info: { unreliable: boolean; from?: string }) => void): () => void;
  on(event: "tick", fn: (tick: number) => void): () => void;
  on(event: "peers", fn: (peers: { speakers: readonly string[]; listeners: readonly string[] }) => void): () => void;
  on(event: "voice", fn: (access: { url: string; token: string }) => void): () => void;
  on(event: "lobby", fn: (state: LobbyState) => void): () => void;
  on(event: "handoff", fn: (handoff: Handoff) => void): () => void;
  onTick(fn: (tick: number) => void): () => void;
  predict<I, K>(stepper: Stepper<I>, opts: { find(room: RoomClient<S, P, C>): ClientEntity<K> | undefined; sample?(prediction: Prediction<I, K>): I; idle?(input: I): boolean }): Prediction<I, K>;
  interpolate<K extends Kind, F extends keyof ValuesOf<K> & string>(kind: K, fields: readonly F[]): Interpolator<K, F>;
  readonly playerData: PlayerData;           // this player's data; see Player data below
  collection(name: string): Collection;
  leaderboard(name: string): ClientLeaderboard;
}
```

- **`send`** sends a `Uint8Array` as a binary message and anything else
  as JSON, at most 64 KB. It throws if called before the client was
  first ready; while the client reconnects, messages are dropped. In a
  native room, `to`, 1 to 16 player IDs, sends it only to those of them
  who are connected; it throws a `RangeError` for an empty list or more
  than 16, and any other room closes the connection with 4006 for it.
- **`info.from`** of a `message` event is the sender's player ID in a
  native room, where messages come from other players, and `""` for
  one sent through the server API. It's undefined in a room with room
  code, whose messages come from the room. Held messages keep it.
- **`lead`** passes the leader role of a native room to another
  connected player, with the native room's call `lead`, and resolves once
  the room took it. It rejects with an `IrtError` when this player
  isn't the leader or the other player isn't connected. See Presence.
- **`leave`** closes the connection; the client doesn't reconnect and
  emits `closed` with code 1000.
- **`state` and `private`** are undefined until `ready` resolves, and
  set from then on, through reconnects. `connect` resolves to a
  `ReadyRoomClient`, the same object typed with both set. With
  `new RoomClient`, read them as `room.private?.coins`, or after
  `await room.ready`.
- Every `on` returns a function that removes the listener.
- **`serverTick()` and `rtt`** come from pings. The client pings three
  times 100 ms apart after each `welcome`, then every 2 seconds. The
  room answers with its current tick, and the client takes the answer
  to be from the middle of that tick and half a round trip old.
  `serverTick()` and `rtt` use the sample with the smallest round trip
  of the last 8. Across a reconnect to the same generation the client
  keeps its estimate until a new pong arrives; after a restart or a
  wake it uses the first state update's tick until then.
- **`jitter`** is the mean deviation of the last 8 round trips from
  their mean. **`transportKind`** comes from the dial; a custom `dial`
  can leave its `kind` out, and then it's undefined.
- **`joinTime`** is set when `ready` resolves: the milliseconds from
  `new RoomClient` to the first full state update, leaving out any
  `createRoom` or `quickJoin` before it, and `started`, whether the
  router sent `waking` on the way, which it does for a room that starts
  as well as one that wakes. After a reconnect it's the time from the
  drop to the resync. The [join loader](/docs/ui-kit#irt-join-loader)
  shows it.
- **How accurate `serverTick()` is.** The room only reports whole ticks,
  so on a symmetric link expect it to be off by up to half a tick: about
  25 ms at 20 Hz. Two clients in the same room can differ by up to a
  tick. It's good enough for what the SDK uses it for, sending inputs
  for the right tick and the render time of `interpolate`, and for
  timing game events in ticks. It isn't a wall clock: a stalled room
  skips the ticks it couldn't run and ticks don't count time the room
  was hibernated or restarting.
- **`serverTime()`** is the room's wall clock, `room.now()`, in
  milliseconds, for timing in real time, such as music or judging a key
  press. Each pong carries the room's clock when it answered; the
  client takes the pong with the smallest round trip of the last 8,
  adds half its round trip and carries it on with its own clock. On a
  symmetric link it's off by about a millisecond. It's undefined before
  the first pong, and from a router or room older than client protocol
  3. It follows the test clock in `@irt/testing`, as `room.now()` does.
  The client also reports its `rtt` in each ping, which the room shows
  as `conn.rtt`.
- **Asymmetric links.** Any clock estimated from round trips,
  `serverTick()`, `serverTime()` and one you build yourself, assumes half the round
  trip each way. When a link is slower one way, the clock is off by
  half the difference, and nothing in the round trip shows it: with
  150 ms up and 0 ms down, the client's clock is 75 ms behind the
  room's. To correct for it, and for audio output latency, let each
  player calibrate an offset, such as by tapping along to a beat.

**Messages before a listener.** A room's messages can reach the client
before `connect` resolves, such as those it sends in `onJoin`. The
client holds reliable messages that arrive before the first `message`
listener is added, up to 100, and gives them to the listeners once the
code that added the first one has run, so listeners added together all
get them. So `await connect(...)` then `room.on("message", ...)` gets
every message the room sent on join. Messages keep the order the room
sent them in, held ones first; a held message is delivered after the
state updates that arrived with it are applied. Unreliable messages are
not held: before the first listener, they are dropped. After the first
`message` listener has been added, nothing is held, so a listener added
later gets only messages from then on.

| Event | When |
|---|---|
| `waking` | The room isn't running and the connection is held while it starts. That's a wake of a hibernated room, but also the first start of a room this connection creates, and a restart after a crash: the router says it before it has looked up whether the room has room state. Show something neutral, such as "starting the room" |
| `disconnected` | The connection dropped; the client is reconnecting |
| `restored` | A reconnect succeeded and the client holds the full state again, resumed or sent whole |
| `sleep` | The room went to sleep and the router holds the connection; `room.asleep` is true. The connection stays open: messages, calls and writes sent meanwhile wake the room and reach it after, and unreliable messages and inputs are dropped. The client pings every 15 seconds instead of every 2 until the room wakes |
| `wake` | The room woke from sleep and the client holds its full state again. Calls made while it slept are answered, not failed; prediction starts over |
| `closed` | The connection ended for good, with an `IrtError` whose `code` is the close code |
| `message` | A message from the room arrived |
| `tick` | A whole state update was applied. The room sends one only for a tick that changed something this client sees, so a room where nothing changes fires none; for the room's current tick, use `room.serverTick()` |
| `peers` | `room.peers` changed: who this player hears or is heard by |
| `voice` | The router granted voice for this connection; `room.voice` is set |
| `lobby` | A lobby's state changed; `room.lobby` is set |
| `handoff` | A handoff connected the player to another room, or failed to; the same as `onHandoff` |

### Lobbies

```ts
interface LobbyState {
  phase: "waiting" | "countdown" | "handing-off";
  ready: string[];          // ready people in join order, then every bot
  startsAt: number | null;  // when the countdown ends, in the room's wall-clock ms; compare with serverTime()
  min: number;              // the lobby's minPlayers and maxPlayers
  max: number;
  failed: "players" | "limit" | "spending" | "unavailable" | null;  // why the last handoff failed, until the next countdown
}

type Handoff =
  | { room: string; type: string; client: RoomClient }  // connected to the new room
  | { room: string; type: string; error: IrtError };   // couldn't connect; this client stays where it was
```

- **`lobby`** is set from the lobby's state message, which a lobby sends
  after the first state update and whenever it changes. It's undefined
  in every room that isn't a lobby.
- **`setReady`, `start` and `cancel`** are the lobby's calls `ready`,
  `start` and `cancel`. They reject with an `IrtError` with the
  lobby's reason: `start` and `cancel` from anyone but the leader,
  `start` outside waiting or with fewer than `minPlayers` people and
  bots, `cancel` outside the countdown, and `setReady` while the
  lobby hands off. In a room that isn't a lobby they reject as calls the
  room doesn't answer.
- **Handoffs.** When the router moves the player, the client connects
  to the new room with `targets[type]` as its schema, the empty schema
  for a type it doesn't name, and the same token or guest. Once the new
  client holds the room's state, this one leaves its room, unless the
  handoff keeps it, as a party's does, then `onHandoff` gets the new
  client. If the new client fails for good, `onHandoff` gets its error
  and this client stays connected. See
  [Lobbies and parties](/docs/guides/lobbies).

### Wire statistics

```ts
class WireStats {
  messagesIn: number;
  bytesIn: number;
  messagesOut: number;
  bytesOut: number;
  readonly received: Record<string, { messages: number; bytes: number }>;  // by server message type
  readonly sent: Record<string, { messages: number; bytes: number }>;      // by client message type
  lastUpdate: { tick: number; parts: number; bytes: number; full: boolean } | undefined;
}
```

`room.stats` counts the client's traffic since it was created, across
reconnects. Sizes are of protocol messages as encoded, without the
transport's own framing, such as a WebSocket frame header. `received`
is keyed by type: `state` (state updates), `ack` (input acks), `pong`,
`message`, `unreliable`, `reply` and the rest; `sent` by `input` (or
`typedInput` with a schema's [input kind](/docs/guides/prediction#compact-inputs)),
`ping`, `write`, `message`, `unreliable`, `call` and `hello`. So
`stats.received.state.bytes` is what state sync cost and
`stats.sent.input.bytes` what prediction inputs cost. `lastUpdate` is
the last whole state update applied: its tick, the messages it was
split into, their size together on the wire, compressed or not, and
whether it was a full update, as on joining or on a reconnect that
couldn't resume. A tick that sent the client nothing leaves it as it
was. Sample the counters once a second to get rates:

```ts
// wire-rates.ts
import type { RoomClient } from "@irt/client";

export function logRates(room: RoomClient): void {
  let last = { in: room.stats.bytesIn, out: room.stats.bytesOut };
  setInterval(() => {
    const now = { in: room.stats.bytesIn, out: room.stats.bytesOut };
    console.log(`in ${now.in - last.in} B/s, out ${now.out - last.out} B/s, last update ${room.stats.lastUpdate?.bytes ?? 0} B`);
    last = now;
  }, 1000);
}
```

### Calls

`call(name, args)` runs the room's `calls[name]` handler and resolves to
what it returns, JSON or bytes. Its name, args and reply are typed from
the `calls` of the schema passed to `connect`, declared with
`defineCalls`; see the [calls guide](/docs/guides/calls). It rejects
with an `IrtError` when the handler throws, with the handler's message;
when the call's `parse` rejects the args; when the room has no such
call; after `timeout` milliseconds, 10,000 by default; and when the
connection drops or the room restarts first. A call made while the room
sleeps waits for it to wake and is answered then. A call that fails that way
may or may not have run, and the SDK never retries it, so make calls
that change state safe to repeat, or check with another call. Before the
client is first ready, `call` throws.

### Reloading for a new build

`reloadForNewBuild()` reloads the page after a 4004 so the browser loads
the live build's site, and returns `true`. It reloads at most once until
a connection succeeds, and returns `false` instead of reloading again: a
room still running an older build refuses the new site's clients with
4004 until it hibernates, so reloading on every 4004 would loop. It also
returns `false` outside a browser or when storage is blocked.

## Close codes

| Code | Meaning | Client SDK |
|---|---|---|
| 4000 | Protocol version not supported | Fails; update `@irt/client` |
| 4001 | Token invalid or expired | Fails |
| 4002 | Room not found | Fails |
| 4003 | Room full | Fails |
| 4004 | The client's schema differs from the room build's | Fails; the message gives both hashes. Rebuild and redeploy the client and room together |
| 4005 | Rate or size limit exceeded | Reconnects after backoff |
| 4006 | Kicked by the room, or its `onJoin` threw | Fails |
| 4007 | Room stopped | Fails |
| 4008 | Room moved or restarted | Reconnects at once |
| 4009 | Project over its spending limit | Fails |
| 4010 | Wake timed out | Reconnects after backoff |
| 4011 | The room hibernated by its own request | Fails; connect again to rejoin, which wakes it |
| 4012 | The same player connected to the room again elsewhere | Fails; the player is playing in another tab or device |
| 4013 | The player is [banned](/docs/moderation) from the project | Fails |
| 4014 | The room banned the player | Fails |
| 4015 | The room isn't of the client's `type`, or the live build has no such type | Fails; don't reload for it, since the new site has the same mistake |

Any other close, and a failure to connect at all, reconnects with
backoff: 250 ms doubling up to 10 s, with jitter. [Errors and close
codes](/docs/reference/errors) has each code's causes and the messages
`connect` and `call` reject with.

## Entities on the client

```ts
type ClientEntity<K> = Readonly<ValuesOf<K> & { id: number; kind: K }> & {
  toJSON(): ValuesOf<K> & { id: number; kind: string };   // a plain copy; kind is the kind's name
};
// An entity the local player owns: its writable fields can be set.
type OwnedEntity<K> = ClientEntity<K> & { -readonly [N in WritableOf<K>]: ValuesOf<K>[N] };

class EntityStore {
  get(id: number): ClientEntity | undefined;
  all<K extends Kind>(kind: K): IterableIterator<Entity<K> & { toJSON(): ValuesOf<K> & { id: number; kind: string } }>;
  mine<K extends Kind>(kind: K): IterableIterator<OwnedEntity<K>>;
  ownerOf(e: ClientEntity): string | undefined;   // a player ID, or undefined for the room
  readonly count: number;
  onEnter<K extends Kind>(kind: K, fn: (e: ClientEntity<K>) => void): () => void;
  onChange<K extends Kind>(kind: K, fn: (e: ClientEntity<K>, changed: (keyof ValuesOf<K>)[]) => void): () => void;
  onCorrect<K extends Kind>(kind: K, fn: (e: OwnedEntity<K>, corrected: WritableOf<K>[]) => void): () => void;
  onOwner<K extends Kind>(kind: K, fn: (e: ClientEntity<K>) => void): () => void;
  onLeave<K extends Kind>(kind: K, fn: (e: ClientEntity<K>) => void): () => void;
}
```

- Entities are read-only, except the writable fields of entities the
  local player owns, including its private state; any other write throws
  a `TypeError`. See [Ownership](/docs/guides/ownership).
- Owner writes are sent at most once per room tick. The room's
  corrections overwrite them, and `onCorrect` runs after `onChange` for
  the corrected fields.
- A state update is applied a whole tick at a time, then the callbacks
  run in order: leaves, enters and changes as they happened, then
  `tick`.
- To copy an entity, call `toJSON()`: `{ id, kind, ...fields }` with
  `kind` as the kind's name, which `JSON.stringify` also uses. Its fields
  are accessors on a shared prototype, so `{ ...entity }` copies only
  `id` and `kind`. The copy is a snapshot of the values at that moment,
  and the entity object itself keeps changing with each state update.
- The shared state is entity 0 and the private state entity 1, of the
  schema's state and private kinds; `onChange(schema.state, ...)` works.
- `count` is every entity the client holds: the shared state, its
  private state, a presence entry for each player in the room, and the
  room's entities in its view. A seated player in a room of four, with
  one entity of its own in view, has a `count` of 7. Count one kind
  with `all(kind)`. The room's `entities.count` counts only the room's
  entities.
- Entities of a [hidden kind](/docs/guides/state-sync#hidden-entities)
  never arrive, so `all(kind)` of one is always empty.
- On a reconnect or a change of generation, every entity leaves and the
  full state enters again.

## Presence

```ts
interface PresenceEntry {
  readonly player: string;
  readonly name: string;        // set by the room
  readonly status: unknown;     // JSON, at most 1 KB; null until set
  readonly connected: boolean;  // false for 10 s after the player's last connection closed
}

class PresenceList {
  get(player: string): PresenceEntry | undefined;
  readonly me: PresenceEntry | undefined;   // the local player's entry
  readonly size: number;
  [Symbol.iterator](): IterableIterator<PresenceEntry>;
  setStatus(status: unknown): void;
  onJoin(fn: (p: PresenceEntry) => void): () => void;
  onChange(fn: (p: PresenceEntry, changed: ("name" | "status" | "connected")[]) => void): () => void;
  onLeave(fn: (p: PresenceEntry) => void): () => void;
  readonly leader: string | undefined;      // native rooms: the player who leads, or undefined for none
  onLeader(fn: (player: string | undefined) => void): () => void;
}
```

- `room.presence` lists every player in the room, whatever the room's
  interest, and is set once `ready` resolves. Its callbacks run after
  the entity callbacks of the same state update, before `tick`.
- A resync doesn't fire `onLeave` and `onJoin` for players who stayed;
  `onChange` runs for whatever changed while the client was away.
- `setStatus` is an owner write: it changes `me.status` at once, without
  `onChange`, and throws a `RangeError` over 1 KB. A correction from the
  room fires `onChange`. See [Presence](/docs/guides/presence).
- **The leader.** A native room has a leader, set after the client's
  first state update and whenever it changes, when `onLeader` runs. The
  leader keeps the role while their presence lasts, so through a
  disconnect of up to 10 seconds, or until they pass it with
  `room.lead(player)`; then the earliest connected player leads, and
  the role doesn't go back to the old leader. A room with room code has
  no leader, and `leader` stays undefined.
- **In a native room** each player's status is at most 64 bytes of JSON;
  a longer one closes the connection with 4006, as does a
  `to` list of more than 16 players or a malformed message.

## Interpolation

```ts
class Interpolator<K, F extends string> {
  get(entity: ClientEntity<K>): Record<F, number>;
}
```

`room.interpolate(kind, fields)` records the listed numeric fields of
every entity of the kind as state updates arrive. `get(entity)` returns
them at the client's render time: the room's estimated tick minus two
ticks or 100 ms, whichever is longer, linearly between the two states
around it. Call it each frame. Use it for remote entities; use
[prediction](/docs/guides/prediction) for the local player.

## Prediction

```ts
class Prediction<I, K> {          // K is the kind `find` returns
  readonly entity: Entity<K> | undefined;   // has toJSON(), as client entities do
  render<F extends keyof ValuesOf<K>>(fields: readonly F[], opts?: { snapDistance?: number }): Record<F, number>;
  snap(): void;                   // drops the mispredictions render is smoothing
  readonly pending: number;       // ticks ahead of the room's state: about 2 plus half the round trip while sampling
  readonly settled: boolean;      // entity agrees with the room's last state
  mispredictions: number;         // replays that found a field the stepper writes different
  onMispredict(fn: (m: { tick: number; fields: string[]; delta: Record<string, number> }) => void): () => void;
  push(input: I): void;
  stop(): void;
}
```

`sample(prediction)` runs once per room tick, first at the next tick
after `predict` returns, and receives the `Prediction`. Its `entity` is
set before each call whenever `find` finds the entity, so it's
undefined only while `find` finds nothing: before the entity is in the
client's view, while the room has deleted it, and after a reconnect
until the full state arrives.

`render(fields, { snapDistance })` drops the correction of those fields
instead of smoothing it when it's longer than `snapDistance`, measured
as a Euclidean distance over the fields, as after a teleport; `snap()`
drops every correction at once. See the
[prediction guide](/docs/guides/prediction) for how inputs, acks and
replay work.

## HTTP helpers for games without a backend

```ts
function createRoom(opts: { router: string; project: string; token?: string; id?: string; type?: string; public?: boolean; joinCode?: boolean; meta?: unknown; maxPlayers?: number }): Promise<{ id: string; joinCode: string | null }>;
function joinByCode(opts: { router: string; project: string; token?: string; code: string }): Promise<string>;
function listPublic(opts: { router: string; project: string; token?: string; type?: string }): Promise<{ id: string; players: number; type: string; meta: unknown }[]>;
function quickJoin(opts: { router: string; project: string; token?: string; type?: string; meta?: Record<string, unknown>; maxPlayers?: number }): Promise<{ id: string; joinCode: string | null }>;
```

Each is allowed or not by a project setting (`players.createRooms`,
`players.listPublic`, `players.quickJoin`). They reject with an `IrtError` whose `code` is the HTTP
status, such as 404 for an unknown join code. Join codes are 6
characters of `A-H`, `J-N`, `P-Z` and `2-9`. `joinByCode` is case-insensitive
and ignores spaces around the code, so `"k7qx2m "` finds `K7QX2M`.

`maxPlayers` caps a room's connections below its room size's connection
limit (64 for `standard`), from 1 to that limit; a connection past it
closes with 4003, and a value out of range rejects with 400. With
`players.createRooms` on, connecting to a room that doesn't exist also
creates it, as a private room with no join code.

`type` is the [room type](/docs/concepts#rooms): `createRoom`
creates a room of it, `quickJoin` picks or creates one, and `listPublic`
lists only rooms of it. Without one, `createRoom` and `quickJoin` use the
type named `default` and reject with 400 naming the build's types when
it has none, and `listPublic` lists every type, each room with its
`type`. A type's own `maxPlayers` and size apply to its new rooms.

`quickJoin` returns a public room to connect to, for games that fill rooms
with whoever comes. It picks the active public room with the most players
that's under its connection limit and its own `maxPlayers`, among those
whose `meta` has every top-level key of `opts.meta` with an equal value.
Without one it picks such a hibernated room, and without that it creates
a public room with `opts.meta` as its `meta` and `opts.maxPlayers` as its
`maxPlayers`. It holds the room's slot for 10 seconds or until the client
connects, so players who quick join at once don't overfill a room or create
one each. `joinCode` is the room's join code, or `null`. The setting is off by
default; matchmaking by skill, parties or queues belongs in your backend.

```ts
// rooms.ts
import { connect, createRoom, joinByCode, listPublic, quickJoin } from "@irt/client";

const router = "wss://eu.irt.io";
const project = "my-game";

export async function host() {
  const { id, joinCode } = await createRoom({ router, project, public: true, joinCode: true, meta: { mode: "duel" } });
  console.log("share", joinCode);
  return connect({ router, project, room: id });
}

export async function join(code: string) {
  return connect({ router, project, room: await joinByCode({ router, project, code }) });
}

export async function browse() {
  for (const r of await listPublic({ router, project })) console.log(r.id, r.players, r.meta);
}

export async function play(mode: string) {
  const { id } = await quickJoin({ router, project, meta: { mode } });
  return connect({ router, project, room: id });
}
```

## Player data, collections and leaderboards

```ts
function dataClient(opts: { router: string; project: string; token?: string }): DataClient;

class DataClient {
  readonly playerData: PlayerData;             // get, set, increment, delete, list, as in the room SDK, for this player
  collection(name: string): Collection;        // get, put, list, delete
  leaderboard(name: string): ClientLeaderboard;
  player(): Promise<string>;                   // the player ID calls are made as; mints a guest without a token
}

class ClientLeaderboard {
  submit(score: number, opts?: { meta?: Record<string, string | number | boolean> }): Promise<{ period: string; score: number }[]>;
  top(opts?: { period?: string; limit?: number; after?: string | null }): Promise<{ entries: RankedEntry[]; next: string | null }>;
  around(opts?: { player?: string; period?: string; count?: number }): Promise<{ rank: number; entries: RankedEntry[] } | undefined>;  // this player by default
}
```

The same calls as [in the room](/docs/reference/room-sdk#player-data-collections-and-leaderboards),
for the player the client is, over the router's `POST /v1/data/{project}`,
with no room connection needed. `RoomClient` has them too, as
`room.playerData`, `room.collection(name)` and `room.leaderboard(name)`,
made with the connection's token or guest.

- **Guests.** Without a `token`, the first call takes the guest token
  `connect` keeps in `localStorage`, or gets one from `POST /v1/guest`
  and keeps it there, so a guest is one player in rooms and data calls.
  An expired guest token gets a new guest, as connecting does. With
  storage blocked, the token lives as long as the page.
- **Rights.** A client reads its own player data and writes only the
  keys in `data.player.clientWrite`; reads entries and boards with
  `clientRead`; and with `clientWrite: "own"` creates entries, changes
  and deletes its own, and submits its own score. `owner` is always the
  client's player. A score a client submits can be faked.
- **Nothing is cached** on the client; every call goes to the router.
- **Errors.** Calls reject with `DataError` (also exported here) and a
  contract code: `E_UNAVAILABLE` when the router or data service can't be
  reached or answers 503, `E_LIMIT` over the router's 10 calls a second
  per address and per player or 10 guests a minute per address,
  `E_FORBIDDEN` for a rejected token. See the
  [guide](/docs/guides/player-data).

```ts
// data.ts
import { DataError, dataClient } from "@irt/client";

const data = dataClient({ router: "wss://eu.irt.io", project: "my-game" });

export async function saveSettings(volume: number) {
  try {
    await data.playerData.set("settings", { volume });
  } catch (e) {
    if (e instanceof DataError && e.code === "E_UNAVAILABLE") return false;
    throw e;
  }
  return true;
}

export async function weeklyTop() {
  const { entries } = await data.leaderboard("highscores").top({ period: "week", limit: 10 });
  return entries.map((e) => `${e.rank}. ${e.meta.name ?? e.player} ${e.score}`);
}
```

## Simulated network

```ts
import { simulateNetwork, type NetworkConditions, type SimulateOptions } from "@irt/client/dev";

function simulateNetwork(conditions: NetworkConditions, opts?: SimulateOptions): Dial;

interface NetworkConditions {
  rttMs: number;      // added round trip, half each way
  jitterMs?: number;  // each one-way delay varies by up to this much either side of rttMs / 2
  loss?: number;      // fraction of unreliable messages dropped each way, 0 to 1
}

interface SimulateOptions {
  dial?: Dial;            // the transport to wrap; default WebTransport, then WebSocket
  clock?: Clock;          // timers, for tests
  random?: () => number;  // uniform in [0, 1), for tests
  allowRemote?: boolean;  // allow a router other than localhost, 127.0.0.1 or ::1
}
```

Pass the result as `dial` to `connect`. Reliable messages are delayed and
stay in order; unreliable messages, inputs and pings can also be dropped
and reordered. Against a router that isn't local, without `allowRemote`,
`connect` rejects with an `IrtError` of code 0 saying so. It's a separate
entry, so it adds nothing to a bundle that doesn't import it. See
[Dev tools](/docs/dev-tools#simulated-network-conditions).

## Voice

`room.peers` is `{ speakers, listeners }`, the player IDs this player
hears and is heard by, as the room last decided; the `peers` event fires
when it changes. `room.voice` is the router's `{ url, token }` when the
project uses voice, and the `voice` event fires when it's granted. On
each reconnect `room.voice` is undefined and `room.peers` empty until the
router and the room send them again. `joinVoice(room, { position?, spatial?, range? })` from
`@irt/client/voice` joins the voice server. The `Voice` it returns
has `participants`, the other players on the voice server, with a
`participants` event when one joins or leaves it, next to `speaking`,
`mutedPlayers` and the player's own controls; see
[Proximity voice](/docs/guides/proximity-voice#client).

## Replays

`loadReplay(bytes, { schema? })` from `@irt/client/replay` plays a
replay or clip file into `replay.entities`, an `EntityStore` with the
usual events, with `replay.state` and `replay.presence`. `play()`,
`pause()`, `speed`, `seek(tick)` and `step()` move it between
`firstTick` and `lastTick`; the `tick`, `message` and `end` events
follow. `kind(name)` returns a recorded kind that differs from the
schema's, and `privateOf(player)` a player's private state when it was
recorded. It's a separate entry, so it adds nothing to a bundle that
doesn't import it. See [Replays and clips](/docs/guides/replays).

## Common mistakes

- **Not awaiting `connect`.** `room.state` and `room.private` are set only
  once it resolves, and `send` throws before then.
- **Reloading on every close.** Reload only on 4004. The client already
  reconnects on the codes that allow it.
- **Reconnecting by hand after 4011.** That's the room asking to
  hibernate; offer the player a rejoin instead of looping.
- **Writing a client entity.** Send a message, or predict the local
  player.
- **Keeping references across a resync.** After `restored`, entities
  the room sent again are new objects, every entity after a full update
  and those that changed after a resume; look them up again or rebuild
  from `onEnter`.
- **Opening two clients as the same player.** The router closes the
  older one with 4012, and it doesn't reconnect. Two tabs of one browser
  are the same guest.

---

# @irt/testing

> Reference for the testing library that runs rooms in process with test clients and a controlled clock.

`@irt/testing` runs your room definition in process with no network: a
room host, the router and storage it talks to, and test clients that use
the real `@irt/client` over an in-memory transport. Time moves only when
the test moves it. It works with Vitest and `node:test`; `irt test` runs
Vitest. [Testing rooms](/docs/guides/testing) shows patterns for
hibernation, crashes, calls, ownership and migrations.

```ts
import { createTestHost, testRoom, RoomStoppedError, TestClock, type TestHost, type TestRoom, type TestClient, type TestRoomOf, type TestClientOf } from "@irt/testing";
```

## Starting rooms

```ts
function testRoom<S, P, D, C>(def: RoomDefinition<S, P, D, C>, opts?: TestHostOptions): TestRoom<S, P, D, C>;
function createTestHost<S, P, D, C>(def: RoomDefinition<S, P, D, C>, opts?: TestHostOptions): TestHost<S, P, D, C>;

interface TestHostOptions {
  project?: string;           // defaults to "test"
  settings?: ProjectSettings; // as irt.config.ts declares them; rooms.retention applies
  startAt?: number;           // the clock's wall time at the start, ms since the epoch; defaults to the real time
  types?: Record<string, RoomDefinition>;  // the build's other room types, beside def as default, such as a lobby's target
}
```

A test that checks absolute times, such as `onWake`'s `savedAt`,
`room.now()` or a schedule on the UTC clock, should pass `startAt`, since
the default changes from run to run.

```ts
// For typing helpers that take a test room or client of a room definition:
type TestRoomOf<typeof room> = TestRoom<S, P, D, C>;
type TestClientOf<typeof room> = TestClient<S, P, C>;
```

`settings.rooms.retention` applies: a room that stays hibernated for its
retention is deleted, and its `status` becomes `"not created"`. The test
host deletes it the moment the retention passes; deployed, the sweeper
does it up to an hour later.

`testRoom(def)` is a host with one room called `"room"` in project
`"test"`. Use `createTestHost` for several rooms of the same build in one
room host, such as to check that one room's crash leaves the others
running.

`S` and `P` are the schema's state and private kinds, `D` the type of
`room.data`, and `C` the schema's calls. To type a helper that takes a
test room or client, use `TestRoomOf<typeof room>` and
`TestClientOf<typeof room>` rather than writing the parameters out:
`TestClient<S, P>` leaves out `C`, which then defaults to no calls, so
`client.call` takes `never`.

```ts
// helpers.test.ts
import { CallRejected, defineCalls, defineRoom, defineSchema, entity } from "@irt/room";
import { type TestClientOf, type TestRoomOf, testRoom } from "@irt/testing";
import { expect, test } from "vitest";

const Table = entity("table", { seated: "u8" });
const room = defineRoom({
  schema: defineSchema({ state: Table, calls: defineCalls<{ sit(args: { seat: number }): { seat: number } }>() }),
  calls: {
    sit(room, _conn, { seat }) {
      if (seat > 4) throw new CallRejected("the table has 4 seats");
      room.state.seated += 1;
      return { seat };
    },
  },
});

async function sit(t: TestRoomOf<typeof room>, client: TestClientOf<typeof room>, seat: number): Promise<number> {
  // The reply to a call that changed room state waits for the tick that saves it.
  const [{ seat: taken }] = await Promise.all([client.client.call("sit", { seat }), t.host.tick()]);
  return taken;
}

test("two players sit", async () => {
  const t = testRoom(room);
  expect(await sit(t, await t.connect({ player: "alice" }), 1)).toBe(1);
  expect(await sit(t, await t.connect({ player: "bob" }), 2)).toBe(2);
  expect(t.live.state.seated).toBe(2);
});

test("a fifth seat is refused", async () => {
  const t = testRoom(room);
  await expect(sit(t, await t.connect({ player: "carol" }), 5)).rejects.toThrow("the table has 4 seats");
});
```

The room runs a call's handler as the call arrives, so `sit` awaits the
call before it ticks. A helper that starts a call, ticks, and only then
awaits it leaves a rejected call without a handler during the tick, and
Vitest reports an unhandled rejection. To tick while a call is in
flight, attach the assertion first, as in
`const refused = expect(call).rejects.toThrow(...)`, then tick and
`await refused`.

## TestHost

```ts
class TestHost<S, P, D, C> {
  readonly clock: TestClock;
  readonly tickRate: number;
  room(id: string): TestRoom<S, P, D, C>;     // a handle; the room starts on connect or wake()
  tick(n?: number): Promise<void>;      // runs n ticks (default 1) of the room's tick rate
  advance(ms: number): Promise<void>;   // moves the clock, running every timer that falls due
  crash(): Promise<void>;               // crashes the room host; its rooms restart from room state
  // What a game without a backend calls from its client, against this host:
  createRoom(opts?: { id?: string; public?: boolean; joinCode?: boolean; meta?: unknown; maxPlayers?: number }): Promise<{ id: string; joinCode: string | null }>;
  joinByCode(code: string): Promise<string>;
  listPublic(): Promise<{ id: string; players: number; meta: unknown }[]>;
  quickJoin(opts?: { meta?: Record<string, unknown>; maxPlayers?: number }): Promise<{ id: string; joinCode: string | null }>;
  // Player data, collections and leaderboards, kept in memory for the host:
  playerData(player: string): PlayerData;   // as the server API, to seed and assert; nothing cached
  collection(name: string): Collection;
  leaderboard(name: string): Leaderboard;
  query(op: { op: string; [arg: string]: unknown }, caller?: DataCaller): Promise<DataReply>;  // one raw operation, as the server API by default
  dataClient(opts?: { player?: string }): DataClient;  // @irt/client's dataClient, as a player or a new guest, with no room
}

class TestClock {
  now(): number;                        // ms since the host was created
  wall(): number;                       // the host's startAt plus now(); room.now() reads it
  jump(ms: number): void;               // moves time without running timers, like a blocked event loop
}
```

**Ticks.** `tick(n)` moves the clock by `n / tickRate` seconds, and every
running room runs exactly `n` ticks in it, so `room.live.tick` grows by
exactly `n`. Inside `onTick`, `room.tick` is the number of the tick
running: 1 for a new room's first tick (see
[Ticks](/docs/reference/room-sdk#ticks)). `connect` moves the clock too,
until the client holds its first state update, so it may run a tick of
a running room. To time something the room started, read when it
started from the room rather than counting ticks since `connect`:

```ts
// round.test.ts
import { defineRoom, defineSchema, entity } from "@irt/room";
import { testRoom } from "@irt/testing";
import { expect, test } from "vitest";

const Round = entity("round", { phase: "string", endsAt: "u32" });
const room = defineRoom({
  schema: defineSchema({ state: Round }),
  tickRate: 20,
  onTick(room) {
    if (room.state.phase === "" && room.connections.size >= 2) {
      room.state.phase = "playing";
      room.state.endsAt = room.tick + 60 * 20;
    } else if (room.state.phase === "playing" && room.tick >= room.state.endsAt) {
      room.state.phase = "ended";
    }
  },
});

test("a round lasts exactly 60 seconds", async () => {
  const t = testRoom(room);
  await t.connect({ player: "alice" });
  await t.connect({ player: "bob" });
  await t.host.tick();
  expect(t.live.state.phase).toBe("playing");
  await t.host.tick(t.live.state.endsAt - t.live.tick - 1);
  expect(t.live.state.phase).toBe("playing");
  await t.host.tick();
  expect(t.live.state.phase).toBe("ended");
});
```

**Local-mode API.** `createRoom`, `joinByCode`, `listPublic` and `quickJoin` behave as
the [client SDK's](/docs/reference/client-sdk#http-helpers-for-games-without-a-backend)
do against `irt dev`, with the host's `settings` applied: they reject
with an `IrtError` whose `code` is the HTTP status, such as 403 when
`players.createRooms` is off or 404 for an unknown join code, and
`joinByCode` takes a code in any case. `quickJoin` holds each slot it hands
out until a client connects to the room or the host's clock passes 10
seconds. Connect to a created room with `host.room(id).connect()`.
`host.room(id).connect()` creates a room that doesn't exist only when
`players.createRooms` is on, as the router does; with it off the connect
fails with 4002 until the room is created or `wake()` starts it. A
room's `maxPlayers` closes connections past it with 4003.

**Player data.** Each host keeps player data, collections and
leaderboards in memory, with the `data` settings of its `settings` and
the host's clock for entries' times and leaderboard periods. Seed and
read it with `host.playerData(player)`, `host.collection(name)` and
`host.leaderboard(name)`, which call as the server API would and cache
nothing. Room code's calls go through the same store, with the room's
5-second cache, so after a test writes a key a room read in the last 5
seconds, move the clock with `host.advance(5000)` or have the room call
`refresh()`. A test client's `client.client.playerData`, `collection`
and `leaderboard` make client calls, with the client's rights, as
`host.dataClient()` does without a room. Pass `startAt` to pin the week
a leaderboard test runs in.

```ts
// highscore.test.ts
import { defineRoom } from "@irt/room";
import { createTestHost } from "@irt/testing";
import { expect, test } from "vitest";

const room = defineRoom({
  async onJoin(room, conn) {
    const visits = await room.playerData(conn.player).increment("visits", 1);
    await room.leaderboard("visits").submit(conn.player, visits);
  },
});

test("each join counts a visit and ranks the player", async () => {
  const host = createTestHost(room, { settings: { data: { collections: { visits: { clientRead: true, leaderboard: {} } } } } });
  await host.playerData("bob").set("visits", 4);
  await host.room("lobby").connect({ player: "ada" });
  const bob = await host.room("lobby").connect({ player: "bob" });
  expect(await host.playerData("bob").get("visits")).toEqual({ value: 5, version: 2 });
  expect(await bob.client.leaderboard("visits").around()).toMatchObject({ rank: 1, entries: [{ player: "bob" }, { player: "ada" }] });
});
```

`tick` and `advance` throw a `RoomStoppedError` when a room stopped
meanwhile, from an error in `onCreate`, `onWake`, `onTick`,
`onHibernate`, the stepper, interest or a migration, or from room state
over 32 MB:

```text
Room test/duel stopped at tick 12:
Error: score overflow
    at onTick (src/room.ts:20:11)
Other rooms in the room host keep running. If the test expects this, catch it, for example `await expect(host.tick()).rejects.toThrow(RoomStoppedError)`.
```

Errors in `onMessage`, `onLeave` and `onRequest` don't stop the room;
they're logged to stderr and the message is dropped.

`crash()` drops the room host without running any hooks, as a crash
would. Its rooms restart in a new room host from the room state the
parent holds, which includes every tick's changes, and their clients
reconnect on the next `tick` or `advance`.

## TestRoom

```ts
class TestRoom<S, P, D, C> {
  readonly id: string;
  readonly host: TestHost<S, P, D, C>;
  readonly clients: TestClient<S, P, C>[];
  readonly status: "starting" | "waking" | "active" | "hibernating" | "hibernated" | "stopped" | "not created";
  readonly live: Room<S, P, D>;            // the running room; read and write its entities from the test
  stored(): RoomData;                   // the room state a wake would start from, decoded
  connect(opts?: { player?: string; meta?: unknown; type?: string }): Promise<TestClient<S, P, C>>;  // type: one of the host's types
  wake(): Promise<void>;                // starts or wakes the room with no connection
  hibernate(): Promise<void>;           // hibernates now; connected clients close with 4011
  request(message: unknown): Promise<unknown>;  // calls onRequest, as the server API does, and resolves with its reply
  replays(): string[];                  // the room's replay IDs, oldest first
  clips(): string[];
  replay(id: string): Replay;           // loads a replay, as recorded so far, with @irt/client/replay
  clip(id: string): Replay;
}
```

- `connect` without `player` joins as a guest. `meta` becomes the token's
  `meta` claim, which `onJoin` reads as `connection.meta`. It moves the
  clock until the client holds its first full state update, which a
  running room sends once `onJoin` has run. When the room refuses the connection it rejects
  with an `IrtError` whose `code` is the close code, as `connect` from
  `@irt/client` does: `await expect(t.connect({ player: "c" })).rejects.toMatchObject({ code: 4003 })`.
- `live` throws if the room isn't active, saying its status.
- `hibernate` waits for an async `onHibernate` in real time, up to 10
  seconds, so one that waits on real I/O, such as a `fetch` to a backend
  the test runs, finishes first. The test clock doesn't move meanwhile.
  If it hasn't finished by then, `hibernate` rejects, saying the room
  is still hibernating.
- `request` wakes the room first if it isn't active, as a server API
  message does. It rejects with the error when `onRequest` throws, when
  the room has no `onRequest`, and when the room stops or its room host
  crashes before `onRequest` returns. An `onRequest` that calls
  `room.requestHibernate()` resolves with its reply, and the room
  hibernates after it.
- A room with no connections hibernates by itself 30 seconds after the
  last one closes, as it does in production.
- `replay` and `clip` load with the room definition's schema and the
  host's clock, so `play()` moves as the test moves time. They throw,
  listing the IDs the room has, for an ID it doesn't.

## TestClient

```ts
class TestClient<S, P, C> {
  readonly client: ReadyRoomClient<S, P, C>;  // the real client, ready; everything in the client SDK works
  readonly private: ClientEntity<P>;   // this player's private state as the client holds it
  readonly messages: { message: unknown; unreliable: boolean; tick: number }[];
  readonly events: string[];           // "waking", "disconnected 1006", "restored", "closed 4011", "handoff <room>", ...
  readonly handoffs: Handoff[];        // each handoff that moved the player: the new room and its client, or the error
  restored: number;                    // reconnects that completed
  closedWith: number | undefined;      // the close code once the connection ended for good
  readonly lastUpdate: { tick: number; parts: number; bytes: number; full: boolean } | undefined;  // see below
  readonly speakers: readonly string[];   // player IDs this client hears, as the room's voice rule last said
  readonly listeners: readonly string[];  // player IDs that hear this client
  view<K extends Kind>(kind: K): Record<string, unknown>[];  // entities it sees, as plain objects sorted by ID
  sees(id: number): boolean;
  expectSees(id: number): void;
  expectNotSees(id: number): void;
  expectMessage(expected: unknown): void;   // objects match when every key of `expected` matches
  send(message: unknown, opts?: { unreliable?: boolean }): void;
  predict<I, K>(stepper: Stepper<I>, opts: { find(room: RoomClient<S, P, C>): ClientEntity<K> | undefined; sample(prediction: Prediction<I, K>): I }): Prediction<I, K>;
  drop(): void;                        // drops the network; the client reconnects with backoff
  reconnected(): Promise<void>;        // moves the clock until resynced since the last drop or crash; at once if it already is
  leave(): Promise<void>;
}
```

- `speakers` and `listeners` are the client's `room.peers`, empty until
  the room's [voice](/docs/guides/proximity-voice) rule first tells it.
- `lastUpdate` is `client.stats.lastUpdate`, the last whole state
  update the client applied; `client.stats` has the client's other
  traffic too, by message type (see
  [Wire statistics](/docs/reference/client-sdk#wire-statistics)).
  In it, `tick` is its tick, `parts` how many messages it was split into, each
  at most about 60 KB, `bytes` their total size as sent, and `full`
  whether it was a full update, as on joining or reconnecting, rather
  than a delta. A tick that sends the client nothing leaves it as it was,
  so compare its `tick` with the room's. It's undefined until the first.

Use `lastUpdate` to check what a game costs on the wire, such as that a
join splits into parts and an edit sends a few bytes:

```ts
// sync-size.test.ts
import { defineRoom, defineSchema, entity, type RoomEntity } from "@irt/room";
import { testRoom } from "@irt/testing";
import { expect, test } from "vitest";

const Chunk = entity("chunk", { blocks: "bytes" });
const room = defineRoom({
  schema: defineSchema({ entities: [Chunk] }),
  onCreate(room) {
    for (let i = 0; i < 8; i++) room.entities.create(Chunk, { blocks: new Uint8Array(32 * 32 * 32).fill(1) });
  },
  onMessage(room) {
    const chunk = room.entities.get(2) as RoomEntity<typeof Chunk>;
    chunk.patch("blocks", 0, new Uint8Array([0]));
  },
});

test("a join is split into parts and an edit is a few bytes", async () => {
  const t = testRoom(room);
  const alice = await t.connect({ player: "alice" });
  // Two 32 KB chunks don't fit in one part, so each gets its own.
  expect(alice.lastUpdate).toMatchObject({ full: true, parts: 8 });

  alice.send("dig");
  await t.host.tick();
  expect(alice.lastUpdate).toMatchObject({ tick: t.live.tick, full: false, parts: 1 });
  expect(alice.lastUpdate!.bytes).toBeLessThan(32);
});
```

Failure messages name the client, its connection, the room and the tick,
and say what it has instead:

```text
Expected client "alice" (connection 1) in room test/room to see entity 99 at tick 4, but it doesn't. It sees 3 entities: score 0, private 1, player 2.
```

## A complete test file

```ts
// room.test.ts
import { defineRoom, defineSchema, entity, grid, type RoomEntity } from "@irt/room";
import { createTestHost, RoomStoppedError, testRoom } from "@irt/testing";
import { describe, expect, it } from "vitest";

const Player = entity("player", { owner: "string", x: "f32", y: "f32" });
const Score = entity("score", { points: "u32" });

const room = defineRoom({
  schema: defineSchema({ state: Score, entities: [Player] }),
  interest: grid({ cellSize: 10, radius: 1, dims: "xy", around: (_room, c) => c.data.player }),
  onJoin(room, conn) {
    const at = (conn.meta as { x: number } | null)?.x ?? 0;
    conn.data.player = room.entities.create(Player, { owner: conn.player, x: at });
    room.send(conn, { welcome: conn.player });
  },
  onMessage(room, conn, message) {
    const p = conn.data.player as RoomEntity<typeof Player>;
    if (message === "right") p.x += 15;
    if (message === "score") room.state.points += 1;
  },
  onTick(room) {
    if (room.state.points > 2) throw new Error("score overflow");
  },
  onLeave(room, conn) {
    room.entities.delete(conn.data.player);
  },
});

describe("the room", () => {
  it("shows players to each other only when they are near", async () => {
    const t = testRoom(room);
    const alice = await t.connect({ player: "alice", meta: { x: 0 } });
    const bob = await t.connect({ player: "bob", meta: { x: 25 } });
    const bobId = bob.view(Player)[0]!.id as number;
    alice.expectNotSees(bobId);
    alice.send("right");
    await t.host.tick();
    alice.expectSees(bobId);
    alice.expectMessage({ welcome: "alice" });
  });

  it("keeps the score across hibernation, reconnects and crashes", async () => {
    const t = testRoom(room);
    const alice = await t.connect({ player: "alice" });
    alice.send("score");
    await t.host.tick();

    alice.drop();
    await alice.reconnected();
    expect(alice.client.state.points).toBe(1);

    await t.host.crash();
    await alice.reconnected();
    expect(alice.client.state.points).toBe(1);

    await t.hibernate();
    expect(alice.closedWith).toBe(4011);
    await t.host.advance(60_000);
    const back = await t.connect({ player: "alice" });
    expect(back.client.state.points).toBe(1);
    expect(t.stored().state.points).toBe(1);
  });

  it("stops only the room whose tick threw", async () => {
    const host = createTestHost(room);
    const a = await host.room("a").connect({ player: "alice" });
    const b = await host.room("b").connect({ player: "bob" });
    for (let i = 0; i < 3; i++) a.send("score");
    await expect(host.tick()).rejects.toThrow(RoomStoppedError);
    expect(a.closedWith).toBe(4007);
    await host.tick();
    expect(host.room("b").status).toBe("active");
    expect(b.client.status).toBe("open");
  });
});
```

## With node:test

Nothing in `@irt/testing` depends on Vitest:

```ts
// counts.node-test.ts
import assert from "node:assert/strict";
import { test } from "node:test";
import { defineRoom, defineSchema, entity } from "@irt/room";
import { testRoom } from "@irt/testing";

const Counter = entity("counter", { n: "u32" });
const room = defineRoom({
  schema: defineSchema({ state: Counter }),
  onMessage(room) {
    room.state.n += 1;
  },
});

test("counts messages", async () => {
  const t = testRoom(room);
  const c = await t.connect({ player: "p" });
  c.send("+1");
  await t.host.tick();
  assert.equal(c.client.state.n, 1);
});
```

## Common mistakes

- **Asserting before a tick.** State updates go out at the end of a
  tick; `await t.host.tick()` before reading a client's view.
- **Counting ticks from `connect`.** `connect` may run a tick of a
  running room. Read `t.live.tick` and the tick the room stored, as the
  round test above does.
- **Using real timers.** `setTimeout` in a test doesn't move the room's
  clock. Use `tick` and `advance`.
- **Forgetting `await`.** `tick`, `advance`, `connect`, `hibernate`,
  `wake`, `crash` and `reconnected` are async; without `await` nothing
  has happened yet.
- **Expecting clients to come back after `hibernate()`.** They are closed
  with 4011 and don't reconnect; connect a new client to wake the room.
- **Catching `RoomStoppedError` too broadly.** It means room code threw
  where that stops the room; assert on its message.

---

# Errors and close codes

> Every close code a connection can end with, whether the client SDK reconnects, and the IrtError messages connect, call and the HTTP helpers reject with.

A connection to a room ends with a WebSocket-style close code. Codes from
4000 to 4099 are IRT's own; the client SDK decides from the code whether
to reconnect by itself or to give up and tell the game. Everything a game
sees as an error is an `IrtError`:

```ts
class IrtError extends Error {
  readonly code: number;   // a close code, an HTTP status, 422 for a call the room failed, 1000 after leave(), or 0
  readonly message: string;
  readonly reason: string; // the router's or the room's close reason, such as room.kick's; "" for none
}
```

| `code` | Comes from |
|---|---|
| 4000 to 4099 | The router or the room closed the connection; see [Close codes](#close-codes) |
| 1000 | `room.leave()` |
| 400 to 599 | `createRoom`, `joinByCode` and `listPublic`, with the HTTP status |
| 422 | A call the room answered with an error, such as a handler that threw `CallRejected`; see [call](#call) |
| 0 | No close code: the router couldn't be reached, a timeout passed, or a call got no answer from the room |

## Close codes

The `CloseCode` export of `@irt/client` and `@irt/room` names them:

```ts
// reload-on-4004.ts
import { CloseCode, connect, defineSchema, IrtError, reloadForNewBuild } from "@irt/client";

try {
  await connect({ router: "wss://eu.irt.io", project: "my-game", room: "main", schema: defineSchema({}) });
} catch (e) {
  if (e instanceof IrtError && e.code === CloseCode.SchemaMismatch) reloadForNewBuild();
  else throw e;
}
```

| Code | `CloseCode` | Reconnects | Cause | What to do |
|---|---|---|---|---|
| 4000 | `VersionUnsupported` | no | The client's protocol version isn't one the router accepts, its first message wasn't `hello`, or a message couldn't be decoded | Update `@irt/client`, rebuild and deploy. The router accepts the current protocol version and the one before it |
| 4001 | `TokenInvalid` | no | The player token's signature, `prj`, `room`, `exp` or lifetime is wrong, its `meta` is over 1 KB, or there's no token and `players.guests` is off | Get a fresh token from your backend and connect again. Tokens last at most 24 hours, so a client that reconnects after its token expired ends here |
| 4002 | `RoomNotFound` | no | The project or room ID is invalid, the project doesn't exist, or the room was never created or was deleted and `players.createRooms` is off, so connecting doesn't create it | Create the room first, with `createRoom`, `irt rooms create` or the [HTTP API](/docs/http-api#rooms), turn `players.createRooms` on, or send the player back to a room list |
| 4003 | `RoomFull` | no | The room has as many connections as its room size or its `maxPlayers` allows; a player already connected doesn't count again | Pick or create another room |
| 4004 | `SchemaMismatch` | no | The client's schema hash isn't that of its room's build: the live build's, or an older build's for a room still running one. Under `irt dev`, and from a room on an older build, the reason gives both hashes | A site client: reload, which loads the live build's site. Anything else, such as a bot or a native client, rebuild against the live build's schema. See [Builds and deploys](/docs/builds#the-schema-hash) |
| 4005 | `LimitExceeded` | after backoff | Over 120 messages a second, a message over 64 KB, a message before `welcome`, the router's send queue for this client full, or too many connections to rooms that don't exist from one address | Send less: batch inputs, use state sync instead of messages for continuous data |
| 4006 | `Kicked` | no | Room code called `room.kick(connection, reason?)`, `onJoin` threw, the client sent something malformed, or it sent more than 64 messages or 256 KB while its room slept | Show `reason` if the room gave one; the player may join again. Otherwise read the room's logs (`irt logs`) for an `onJoin` error |
| 4007 | `RoomStopped` | no | Room code threw where that stops the room, room state grew past 32 MB, or the project has no live build | Read `irt logs`; fix and deploy. Connecting again wakes the room from its last room state |
| 4008 | `RoomMoved` | at once | The room restarted: its room host crashed or drained, the router lost its link to the room host, the room moved to a new live build with `rooms.buildUpdate` `"restart"` or `irt restart`, or the room hibernated just as the connection opened | Nothing; the client reconnects and emits `restored` |
| 4009 | `SpendingLimit` | no | The project is suspended, over `limits.maxActiveRooms` or `limits.maxRoomHoursPerDay`, or its account is out of credit | The account owner raises the limit or tops up in the dashboard |
| 4010 | `WakeTimeout` | after backoff | The room didn't wake within 10 seconds, or its room state couldn't be read | Nothing; the wake isn't cancelled and the client retries |
| 4011 | `RoomHibernated` | no | Room code called `room.requestHibernate()` with players connected, or the room went to sleep with the project's sleeping rooms holding `limits.maxSleepingConnections` connections | Offer a rejoin button; connecting again wakes the room |
| 4012 | `Superseded` | no | The same player ID connected to the room again, from another tab, device or process | Tell the player they're playing elsewhere. Don't reconnect automatically, or two tabs close each other in turn |
| 4013 | `Banned` | no | The player is banned from the project, at hello or when the ban arrives; see [Moderation](/docs/moderation) | Tell the player; a ban with an expiry lifts by itself |
| 4014 | `RoomBanned` | no | Room code banned the player from this room with `room.ban`, now or before they connected; `reason` is the ban's | Tell the player they can't rejoin this room, with `reason`; other rooms still take them |
| 4015 | `RoomTypeMismatch` | no | The room is of another [room type](/docs/concepts#rooms) than the client's `type`, or the live build has no such type, or the client named no type and the build has no `default` type; `reason` says which | Connect with the room's type. Don't reload: the site has the same code |

Any other close, such as a dropped network (1006) or a router that isn't
ready yet (1013), and a failure to open a connection after the first
one, reconnects with backoff: 250 ms doubling up to 10 seconds, with
jitter. `reconnectAfter(code)` from `@irt/protocol` returns `"now"`,
`"backoff"` or `"never"` for a code, as the SDK decides.

While it reconnects the client emits `disconnected` with the code and
reason, and `restored` once it holds the full state again. A code it
doesn't reconnect after emits `closed` with an `IrtError`, and, before the
first connection was ready, rejects `connect`.

```ts
// status.ts
import { CloseCode, reloadForNewBuild, type RoomClient } from "@irt/client";

export function showStatus(room: RoomClient, show: (text: string) => void) {
  room.on("disconnected", (code) => show(`reconnecting (${code})`));
  room.on("restored", () => show("connected"));
  room.on("closed", (e) => {
    if (e.code === CloseCode.Superseded) show("You're playing in another tab.");
    else if (e.code === CloseCode.RoomHibernated) show("The room went to sleep. Rejoin?");
    else if (e.code === CloseCode.SchemaMismatch) reloadForNewBuild();
    else show(e.message);
  });
}
```

## connect

`connect` resolves once the client holds the room's full state. It
rejects with an `IrtError`:

| `code` | `message` |
|---|---|
| 0 | `can't reach the router at <router>: <reason>`: neither WebTransport nor WebSocket connected the first time |
| 0 | `connecting to room <id> took longer than <timeout> ms; the client was <status>`: `timeout`, 15,000 ms by default, passed first. Waking counts toward it |
| 4000 to 4099 | the close code's message, below, with the router's reason in parentheses |

The message of each close code:

| Code | `message` |
|---|---|
| 4000 | `the router doesn't support this client SDK's protocol version; update @irt/client` |
| 4001 | `the player token is invalid or expired` |
| 4002 | `the room doesn't exist` |
| 4003 | `the room is full` |
| 4004 | `the client's schema differs from the room build's: rebuild and redeploy the client and room together`, with the reason in parentheses before the colon |
| 4006 | `the room kicked this connection` |
| 4013 | `the player is banned from this project` |
| 4014 | `the player is banned from this room` |
| 4015 | `the room is of another room type, or the build has no such type`, with the reason in parentheses |
| 4007 | `the room stopped` |
| 4009 | `the project is over its spending limit` |
| 4011 | `the room hibernated by its own request; connect again to rejoin it` |
| others | `connection closed with <code>` |

Under `irt dev` and in tests the reason is more specific, such as `(the
project doesn't allow guests; join with a player token)` after 4001.

`send` and `call` throw a plain `Error` when called before the client was
first ready: `send() was called before the client was ready; await
connect(...) or client.ready first`.

## call

`room.call(name, args)` rejects with an `IrtError`. When the room answered
with an error, its `code` is 422:

| `message` | When | Did it run? |
|---|---|---|
| `call <name> failed in the room: <message>` | The handler threw or rejected, such as with `CallRejected` for a game rule; `<message>` is its error's message | It ran and threw |
| `call <name> failed in the room: the room has no call "<name>"` | The room defines no such handler | No |
| `call <name> failed in the room: the reply to <name> is <n> bytes; the limit is 65536` | The handler returned more than 64 KB | Yes |
| `call <name> failed in the room: the room stopped` | The room had stopped | No |

When it got no answer from the room, its `code` is 0:

| `message` | When | Did it run? |
|---|---|---|
| `call <name> got no reply within <timeout> ms` | `timeout`, 10,000 ms by default, passed | Maybe |
| `call <name> failed: the connection dropped; it may or may not have run` | The connection dropped first | Maybe |
| `call <name> failed: the room restarted; it may or may not have run` | The room restarted, so the old room's reply won't come | Maybe |
| `call <name> failed: the client left the room; it may or may not have run` | `leave()` or a close the client doesn't reconnect after | Maybe |
| `call <name> failed: the client is <status>` | Called while the client was reconnecting or closed | No |

The SDK never retries a call. Make calls that change state safe to
repeat, such as by sending an ID the room checks, or ask the room what
happened with another call. Errors a handler throws, other than
`CallRejected`, are also logged in the room with the player and tick.

## The HTTP helpers

`createRoom`, `joinByCode` and `listPublic` reject with an `IrtError`
whose `code` is the HTTP status and whose message is `<method> <path>
failed with <status>: <the router's message>`:

| Status | Cause |
|---|---|
| 400 | An invalid room ID, or `meta` over 1 KB |
| 401 | A token was given and is invalid, or none was given and `players.guests` is off |
| 403 | `players.createRooms` is off (`createRoom`, `joinByCode`) or `players.listPublic` is off (`listPublic`) |
| 404 | No room has the join code, or its room was deleted; or the project doesn't exist |
| 409 | `createRoom` with an `id` that a room already has |
| 429 | Too many requests from this address, with a `Retry-After` header; or the project has `limits.maxRooms` rooms |
| 503 | Room storage is unavailable, or no join code was free; try again |

See [Games without a backend](/docs/no-backend) for how they fit
together.

## Data calls

Player data, collection and leaderboard calls, from room code and from
the client SDK alike, reject with a `DataError` whose `code` is one of
these, and whose message says what to change:

| Code | Cause | What to do |
|---|---|---|
| `E_INVALID` | A malformed call: a bad key or ID, both or neither of a value, a value over 64 KB, `meta` over 1 KB or not flat, a bad `limit`, `count`, cursor or period, a request over 128 KB | Fix the call |
| `E_FORBIDDEN` | The caller may not do it: a client reading another player's data, writing a key not in `data.player.clientWrite`, reading without `clientRead`, writing without `clientWrite: "own"` or another player's entry, or an invalid token | Do it from room code, or change the settings |
| `E_UNKNOWN` | The collection isn't declared in the live build, a `top`, `around` or `submit` on a collection without leaderboard settings, or `get`, `list` or `put` on one with them | Declare it in `irt.config.ts`, or use the right calls |
| `E_VERSION` | The `version` given isn't the key's or entry's; `0` means it must not exist | Read it again and decide |
| `E_TYPE` | `increment` on a value that isn't a number | |
| `E_QUOTA` | Over a player's 256 keys or 1 MB, a collection's 1,000,000 entries, or the collection's `maxOwn` for a client | Delete something first |
| `E_LIMIT` | Over 200 calls a second or 64 at once for a room, 10 a second for a client address or a player, or 10 guests a minute per address | Call less often; use the room's cache for gets |
| `E_SPENDING` | The project is over its spending limit, or the account is out of credit | Top up or raise the limit |
| `E_UNAVAILABLE` | The data service can't be reached in 5 seconds; also from a room host too old for data calls | Retry; a write may or may not have happened, so retry it with `version` |

The router answers a client's data call with HTTP 200 and the reply
whatever its outcome, 401 for a missing or invalid token, 429 past its
limits and 503 when the data service is down; the client SDK turns the
last three into `E_FORBIDDEN`, `E_LIMIT` and `E_UNAVAILABLE`.

## In the room

Room code reports errors in the room's log, which `irt logs` and the
dashboard show. What an error in each hook does is in the
[Room SDK reference](/docs/reference/room-sdk#hooks): errors in
`onMessage`, `onLeave`, `onRequest`, `onWrite` and call handlers cost only
the message, write or call; errors in `onJoin` close that connection with
4006; errors anywhere else stop the room with 4007. In tests, a stopped
room makes `tick` and `advance` throw a `RoomStoppedError` with the
reason.

A room that stops on wake gives a reason that says what to change:

| Reason | Fix |
|---|---|
| `room state is at version 1 and this build has no migration to version 2` | Add `migrations[2]` |
| `room state is at version 2, newer than this build's version 1` | A build older than the room state is live; see [Rolling back](/docs/builds#rolling-back) |
| `room state has entities of kind <kind>, which this build doesn't declare; add a migration` | Keep the kind, or remove its entities in a migration |
| `room state for <what> doesn't fit this build's declarations; add a migration: ...` | A field changed type or range; convert it in a migration |
| `room state is <n> MB; the limit is 32 MB` | Store less; see [Room state](/docs/room-state#limits) |

## Common mistakes

- **Reconnecting by hand.** The SDK already reconnects after the codes
  that allow it. A loop that calls `connect` again on every `closed` turns
  4012 into two tabs fighting and 4011 into a room that can't hibernate.
- **Reloading on every close.** Reload only on 4004, which a new build
  causes; other codes don't go away on reload.
- **Retrying a failed call blindly.** It may have run. Make it safe to
  repeat first.
- **Treating 4001 as permanent.** It's usually an expired token: fetch a
  new one and connect again.

---

# MCP server

> Give a coding agent the IRT docs and read access to your project's builds, rooms, logs and usage with irt mcp, an MCP server for Claude Code and other MCP clients.

`irt mcp` runs an [MCP](https://modelcontextprotocol.io) server on stdio
for coding agents. It gives an agent two things:

- **The IRT docs**, searchable and readable a section at a time, so it
  looks up the API instead of guessing at it. The docs are bundled with
  the CLI, so they match the SDK version you installed and need no
  network.
- **Your project**: its status, builds, rooms, room state, recent logs,
  usage and bans, read with your CLI login. Tools that change anything
  are off unless you start the server with `--allow-writes`.

It's part of `@irt/cli`, so there's nothing else to install. For the
integration rules as a Claude Code skill, see
[`irt skill install`](/docs/cli#irt-skill-install---dir-path---force);
the two work together.

## Setup

Log in once, so the server can read your projects:

```sh
npx @irt/cli login
```

### Claude Code

From the project directory, the one with `irt.config.ts`:

```sh
claude mcp add irt -- npx -y @irt/cli mcp
```

Add `--scope project` to write the server to the project's `.mcp.json`
and share it with everyone who works on the project. Claude Code starts
the server in the project directory, so the project tools act on the
project named in `irt.config.ts`.

### Other MCP clients

Clients that take a JSON config, such as Cursor or Claude Desktop, need
an entry like this one:

```json
{
  "mcpServers": {
    "irt": {
      "command": "npx",
      "args": ["-y", "@irt/cli", "mcp", "--project", "space-race"]
    }
  }
}
```

`--project` names the project the tools act on by default. Without it
the server uses `irt.config.ts` in the directory the client starts it in,
which isn't always your project. An agent can also name a project in each
call.

### Credentials

The server uses the CLI's saved login from `irt login`, read on every
call, so logging in again takes effect without a restart. To use a token
instead, such as a project API key, set `IRT_TOKEN` in the server's
environment:

```sh
claude mcp add irt -e IRT_TOKEN=irt_key_... -- npx -y @irt/cli mcp
```

An API key acts on its one project, so `list_projects` and `whoami` need
a personal login. The docs tools need no login at all.

## Tools

Every result is at most 32,000 characters, about 8,000 tokens. A docs
page longer than that ends with the section to read next, and a large
room state or log is cut with a note saying how to narrow it.

### Docs

| Tool | What it does |
|---|---|
| `list_docs` | Every docs page by section, with its id and description |
| `search_docs` | The sections that best match some keywords, each with a snippet and the `read_doc` arguments to read it |
| `read_doc` | A page as Markdown, or one section by its heading. Takes a page id such as `guides/agents`, a `/docs/...` link or a docs URL |

### Project, read-only

Each takes an optional `project` slug, which defaults to the server's
project.

| Tool | What it does |
|---|---|
| `whoami` | The user, tenant and credit balance the login acts as |
| `list_projects` | The tenant's projects |
| `project_status` | The project's region, settings, client config, live build, and active rooms and players |
| `list_builds` | Builds, newest first, with which is live and each one's `stateVersion` |
| `list_rooms` | Active rooms, or with `status: "all"` hibernated ones too, a page at a time |
| `get_room` | One room's status, build, size, join code and players. Doesn't wake it |
| `get_room_state` | A room's `room.state`. Wakes a hibernated room, which bills room-hours until it hibernates again |
| `tail_logs` | The newest room host output, optionally for one room and since a time such as `15m` |
| `usage` | Room-hours, traffic and cost by day |
| `list_bans` | The bans in force |

### Writes, with `--allow-writes`

| Tool | What it does |
|---|---|
| `create_room` | Creates a room, optionally public, with a join code, size, retention or meta |
| `delete_room` | Deletes a room and its room state for good |
| `send_room_message` | Sends a server message to a room and returns its reply; wakes it |
| `make_build_live` | Makes a build live, which rolls back when the build is older |
| `ban_player` | Bans a player from every room, for a while or for good |
| `unban_player` | Lifts a ban |

## Allowing writes

Without `--allow-writes` the server doesn't list the write tools at all,
and tells the agent to ask you for them. With it, an agent with your
login can delete rooms, roll back the live build and ban players, so
allow writes only when you want the agent to do that, and prefer a
project you use for testing:

```sh
claude mcp add irt-staging -- npx -y @irt/cli mcp --project space-race-staging --allow-writes
```

The server tells the agent to confirm with you before deleting rooms,
making a build live or banning a player. `delete_room`,
`send_room_message`, `make_build_live` and `ban_player` are marked
destructive, so clients that ask before such calls ask you. Deploying
isn't a tool: the agent runs `irt deploy` like any other command, with
your client's usual approval.

---

# Physics

> Reference for @irt/physics, Rapier 2D and 3D as a stepper shared by rooms and client prediction.

`@irt/physics` has one entry per engine, each needing its Rapier package
installed beside it:

| Entry | Needs |
|---|---|
| `@irt/physics/rapier2d` | `@dimforge/rapier2d-compat` 0.21.0 |
| `@irt/physics/rapier3d` | `@dimforge/rapier3d-compat` 0.21.0 |

Both export the same names. Rapier is loaded by the time the import
resolves. The [physics guide](/docs/guides/physics) explains how a tick
runs, prediction and saving.

```ts
import { physics, body, castRay, RAPIER, type BodyOptions, type BodySpec, type BodyType, type Control, type PhysicsOptions, type PhysicsStepper, type Pose } from "@irt/physics/rapier2d";
```

## physics

```ts
function physics<I>(options: {
  gravity: { x: number; y: number };            // 3D: { x, y, z }
  bodies: readonly BodySpec<I>[];
  parseInput?(raw: unknown): I;                 // as a stepper's parseInput, on the room only
}): PhysicsStepper<I>;

interface PhysicsStepper<I> extends Stepper<I> {
  rapierWorld(world: World): RAPIER.World | undefined;
  bodyOf(world: World, entity: Entity | number): RAPIER.RigidBody | undefined;
  entityOf(world: World, of: RAPIER.RigidBody | RAPIER.Collider): Entity | undefined;
}
```

The result is a [stepper](/docs/guides/prediction#the-stepper): pass it
as the room's `stepper` and to `room.predict`. It keeps one Rapier world
per room or prediction, keyed by the `world` it's stepped with, so one
stepper object serves every room in a room host.

- `rapierWorld(world)` is the Rapier world for `room.entities`, for ray
  casts and other queries. It's undefined until the room's first tick or
  wake, and after the room has left the room host. Forces and impulses
  can be applied to its bodies, but set poses through the entities'
  fields.
- `bodyOf(world, entity)` is an entity's body, by entity or ID, and
  `entityOf(world, bodyOrCollider)` the entity a body belongs to, or the
  entity of the body a collider is attached to, such as a ray cast's
  hit. Both are undefined for what has no body, including an entity in
  the tick it's created, before the stepper has run. A body can be made
  again, so look it up rather than keep it across ticks.
- `save` returns bytes when the world has a dynamic body: the Rapier
  world and which entity each body belongs to. `load` restores them and
  reconciles with the entities. Without dynamic bodies, `save` returns
  undefined and `load` makes every body from its entity.
- `release` frees a room's Rapier world; the room host calls it when the
  room leaves, and a prediction when it stops.

`physics` throws when a kind is listed twice, when a kind lacks a
position field or has only part of a group (`vx` without `vy`), when a
pose field isn't `f32` or `f64`, and when a pose field is writable.

## body

```ts
function body<K extends Kind, I>(kind: K, options: BodyOptions<K, I>): BodySpec<I>;

type BodyType = "dynamic" | "fixed" | "kinematic" | "character";

interface BodyOptions<K, I> {
  type: BodyType;
  colliders(entity: Entity<K>): RAPIER.ColliderDesc | RAPIER.ColliderDesc[];
  shapeKey?(entity: Entity<K>): unknown;
  reshape?(colliders: RAPIER.Collider[], entity: Entity<K>, before: Entity<K>): void;
  body?(desc: RAPIER.RigidBodyDesc, entity: Entity<K>): void;
  player?(entity: Entity<K>): string | undefined;
  control?(control: Control<K>, input: I | undefined, dt: number): void;
  character?(controller: RAPIER.KinematicCharacterController): void;
}
```

| Option | Meaning |
|---|---|
| `type` | `dynamic` is simulated; `fixed` never moves; `kinematic` moves where `control` sets it with `body.setNextKinematicTranslation`; `character` is kinematic and moves with `control.move` |
| `colliders` | The shapes of an entity's body, made with the body and again when `shapeKey` changes. A fixed body's colliders are made with density 0, since its mass is never used; the description itself is left as it was |
| `shapeKey` | A value compared with `!==` each tick, on the room and in prediction, that changes whenever `colliders` would return different shapes, such as an edit count. When it changes, the colliders are updated by `reshape`, or made again. Bodies in contact with them are woken |
| `reshape` | Updates the colliders in place after `shapeKey` changed, such as with `collider.setVoxel`, given the entity and `before`, a copy of the entity's values when the colliders were last made or reshaped. It mustn't add or remove colliders. Colliders restored from a saved world are made again instead |
| `body` | Adjusts the body description before the body is made: damping, CCD, gravity scale, initial velocity |
| `player` | The player whose input `control` gets for this entity |
| `control` | Runs each tick before the world steps: on the room for every body of the kind, on a client only for the predicted entity's. `input` is undefined when the player sent none for the tick, or there's no `player` |
| `character` | Configures the kind's character controller once per world: slopes, steps, snapping to the ground, pushing dynamic bodies |

Pose fields, by name:

| | 2D | 3D |
|---|---|---|
| Position, required | `x`, `y` | `x`, `y`, `z` |
| Rotation; without it the body doesn't rotate | `angle` | `qx`, `qy`, `qz`, `qw` |
| Velocity, `dynamic` only | `vx`, `vy` | `vx`, `vy`, `vz` |
| Angular velocity, `dynamic` only | `spin` | `wx`, `wy`, `wz` |

## Control

```ts
interface Control<K> {
  readonly tick: number;          // the room tick being stepped, the same on the room and in a replay
  readonly entity: Entity<K>;     // write the kind's other fields as game state
  readonly body: RAPIER.RigidBody;
  readonly world: RAPIER.World;
  move(dx: number, dy: number): boolean;   // 3D: move(dx, dy, dz)
}
```

`move` asks the character controller to move a `character` body by up
to the given distance this tick, sliding along what it hits, and
returns whether the body ends on the ground. Call it once per tick; a
second call replaces the first. It throws for other body types. A
movement no longer than twice the controller's normal nudge factor,
1e-4 by default, is dropped: the nudge and snapping to the ground
otherwise move a character standing across an edge up and down every
tick.

## castRay

```ts
function castRay<T extends Pose>(ray: RAPIER.Ray, maxToi: number, targets: Iterable<T>, shape: (target: T) => RAPIER.Shape): { target: T; toi: number } | undefined;

interface Pose { readonly x: number; readonly y: number; readonly angle?: number }   // 3D: x, y, z and optional qx, qy, qz, qw
```

The nearest of `targets` that the ray hits within `maxToi`, each placed
at its pose with the shape `shape` returns for it, such as
`new RAPIER.Capsule(0.5, 0.3)`, and the time of impact in units of
`ray.dir`; `undefined` when it hits none. A target without rotation
fields isn't rotated. A ray that starts inside a shape hits it at 0.

It needs no Rapier world, so it checks a shot against poses from
[`room.rewind`](/docs/reference/room-sdk#history), which are where the
shooter saw the targets; see [Lag compensation](/docs/guides/lag-compensation#with-physics).
It visits every target, so pass only the ones in range when there are
many.

## RAPIER

The Rapier module the entry loaded, for `ColliderDesc`, `RigidBodyDesc`,
ray casts and the rest of Rapier's API. Importing
`@dimforge/rapier2d-compat` directly gives the same module.

---

# Acceptable use

> What IRT may be used for, what it may not, and how to report abuse. Draft for legal review.

> **Draft for legal review.** This policy is not in force. Its wording
> will change before launch.

IRT is for games and interactive apps. This policy applies to everything
a tenant runs or serves on IRT: room code, sites, and the traffic they
send and receive.

## Allowed

Multiplayer games, and interactive apps that fit rooms: shared
whiteboards, collaborative tools, live events, and the tests, tools and
bots that support them.

## Not allowed

- **Cryptocurrency mining**, or any use of rooms for computation unrelated
  to the game or app.
- **Proxies, VPNs and tunnels**, or relaying traffic for third parties.
- **Phishing**: sites that imitate another service or collect credentials
  or payment details under false pretences.
- **Malware**: serving or controlling malicious software.
- **Attacks**: scanning, flooding or breaking into other systems, from
  rooms or sites.
- **Spam**: unsolicited bulk messages through any part of IRT.
- **Illegal content**, and content that sexually exploits minors, without
  exception.
- **Harassment**: using IRT to threaten, stalk or abuse people.
- **Evading limits**: working around spending caps, rate limits, room size
  reservations or the isolation between tenants.

Outbound network limits on rooms are high enough for games and low enough
to catch proxies. Reaching them repeatedly is a reason to look at a
project.

## Content on the user content domain

Tenant sites are served only from `irt-serve.com`, never from `irt.io`.
Each tenant is responsible for what its sites and rooms serve, including
content its players create.

## Enforcement

We may hibernate or delete rooms, take down sites, suspend projects or
suspend tenants that break this policy. Where we can, we tell the tenant
first and give them a chance to fix the problem. For phishing, malware,
attacks and content that exploits minors, we act first.

## Reporting abuse

Email [abuse@irt.io](mailto:abuse@irt.io) with the address of the site or
the project involved, what you saw and when. We read every report.