Concepts

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 and webhooks, and signs 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.

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.