relay-host reference

Create a game room from a browser or Node 22+. The helper handles roster changes, compact input, peer links and relay fallback. Import from @controller-plus/sdk/relay-host or https://controller.plus/sdk/src/relay-host.mjs.

createRoom

await createRoom(options = {}): Promise<RelayRoom> creates and connects the host. DEFAULT_RELAY is https://controller.plus. A resolved promise means the host received welcome; it does not mean a phone has joined.

Missing game strings throw TypeError. Invalid requirements throw ProtocolError with code: 'invalid_requires'. Network, URL and WebSocket errors propagate. HTTP refusal throws Error with the service's code, such as invalid_game, invalid_game_origins, rate_limited, room_limit or service_unavailable. Handle the initial rejection separately from later error events. Initial connection has an eight-second timeout and is not automatically retried before the first successful welcome.

Room properties

A phone Player is { id, name, connected, link, source: 'phone', app: { platform, version } \| null, network, route, roundTripMs }. network is wifi, cellular, ethernet, other or unknown. route starts as relay; roundTripMs starts as null. Local pad entries are { id: 'pad' + (index + 1), name, connected: true, source: 'gamepad', route: 'local', roundTripMs: null }.

Room methods

All player IDs below are strings from the roster. Do not identify players by display name.

new RelayRoom(created, WebSocketImpl, { peer = true, RTCPeerConnectionImpl = globalThis.RTCPeerConnection, localControllers = true } = {}) is also exported. created must contain the creation response's room, endpoint, hostToken, joinURL, qrSVG, expires. The constructor starts local watchers but does not connect: await room.session.connect() is still required. Prefer createRoom unless your backend already created the room.

Events

State and welcome frames are available on room.session, not as room events. There is no room-level state, view, disconnected or close event. Subscribe to room.session.on('disconnected', ...) when needed. Event handlers added after connection do not replay earlier notifications; seed from room.players when attaching late.

Limits and reconnects

Private views and public relay state each have a 14,000-byte JSON budget. Client messages have a 16,384-byte total budget and a 180-message/second ceiling per connection. Budget the command envelope too. Do not send views every render frame. See surface limits for controller-tree limits.

Phone seats are reserved for five minutes after disconnect. A valid rotating resume ticket keeps the playerId. The SDK releases stale held binary input after 1.2 seconds, checked every 250 ms. Clear your stored input on leave and host disconnect too. Initial input is event-driven, not a continuous 60 Hz stream. Host reconnection restores the roster; your game owns its simulation state and should resend current private views when needed.

Room example

import { createRoom, movement, NEUTRAL } from '@controller-plus/sdk/relay-host';

export const room = await createRoom({
  game: { id: 'docs-room', name: 'Controller room' }, maxPlayers: 8,
  localControllers: false,
});
export const players = new Map();
room.on('join', ({ playerId, name }) => {
  const player = players.get(playerId) || { input: NEUTRAL(), score: 0 };
  Object.assign(player, { name, connected: true });
  players.set(playerId, player);
  room.view(playerId, { kind: 'gamepad', title: 'Controller room' });
  room.state({ players: [...players].map(([id, p]) => ({ id, name: p.name })) });
});
room.on('input', ({ playerId, input }) => {
  const p = players.get(playerId);
  if (p) { p.input = input; p.move = movement(input); }
});
room.on('leave', ({ playerId }) => {
  const p = players.get(playerId);
  if (p) { p.connected = false; p.input = NEUTRAL(); }
});
room.session.on('disconnected', () => {
  for (const p of players.values()) p.input = NEUTRAL();
});
room.on('error', ({ code, message }) => console.error(code || 'connection', message));
const unsubscribe = room.on('route', ({ playerId, route }) => console.log(playerId, route));
export function reward(playerId) {
  room.feedback(playerId, 'game.win');
  room.rumble(playerId, { low: 0.4, high: 0.2, durationMs: 120 });
}
export function kick(playerId) { room.remove(playerId); }
export function stop() { unsubscribe(); room.close(); }
// Render room.qrSVG, room.joinURL and room.code in your game's lobby.

movement, BUTTONS and NEUTRAL are re-exported from controls. Their signatures and behavior are unchanged.