# 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.