@irtio/client

Connect a browser game or Node script to an irtio room. Read shared state, update records you own, call typed RPCs, and handle connection changes.

npm install @irtio/client @irtio/schema

Join a room

This browser excerpt assumes the schema and room from the quickstart, with the room server running locally. Bundle it as main.ts in your game page:

import { joinRoom } from '@irtio/client';
import { schema } from './irtio/schema.js';

const room = await joinRoom(schema, { name: 'Player' });

window.addEventListener('pointermove', (event) => {
  const player = room.state.players.get(room.me);
  if (!player) return;
  player.x = event.clientX;
  player.y = event.clientY;
});

console.log('Share this room:', room.link);
room.on('status', (status) => console.log(status));

The join resolves after the initial snapshot arrives. In a browser, the client reads ?room= from the page URL or creates a room and puts its code in the URL. Open that link in another tab to join the same room. Call room.leave() when your application is finished with it.

Read, write, and react

| API | Use | | --- | --- | | room.state | Current state and writes to owned records | | room.render | Interpolated remote state for drawing | | room.call.<name>(params) | A typed server RPC; rejects on refusal or failure | | room.onAdd, room.onRemove, room.onChange | Subscribe to entity collection changes | | room.messages.<name> | Send and receive schema-declared messages | | room.on('status', callback) | Update connection UI | | room.on('error', callback) | Handle reported errors |

An RPC reply can arrive before its state update. Return a value from the RPC when the caller needs it immediately, or react to state updates independently.

In Node.js 22, pass url and a room code explicitly to connect scripts to the same room. Omitting room creates a new room on each call. See Node usage.

Optional features

Use matchRoom for hosted matchmaking, joinRelay for relay messages, and joinVoice for voice chat after a user gesture. Identity and matchmaking use the hosted control API.

For physics prediction, install the matching engine peer dependency and import its entry point:

| Engine | Install | Import | | --- | --- | --- | | Rapier 3D | @dimforge/rapier3d-compat | @irtio/client/rapier3d | | Rapier 2D | @dimforge/rapier2d-compat | @irtio/client/rapier2d | | Matter 2D | matter-js | @irtio/client/matter |

Pass the imported engine as module in the appropriate physics option. Follow the physics setup to share world definitions with the server. See the client reference for signatures, defaults, and errors.