node-host reference

Accept phones on your own Node 22+ HTTP(S) server. Import ControllerHost and serveControllerAssets from @controller-plus/sdk/node-host. No Controller+ service is required on this route.

Constructor

new ControllerHost({ server, origin, game = { id: 'custom-game', name: 'Your game', controls: {} }, path = '/ws', allowedOrigins = [], maxPlayers = 16, now = Date.now } = {})

One instance owns one room. Properties include room, origin, path, game, maxPlayers, expires (epoch milliseconds, six hours after creation), players (Map), defaultView, publicState, and server. Treat tokens, socket collections and mutable player records as host-only data.

Credentials and presentation

Names are stripped of control/format characters and truncated to 24 characters after protocol validation. Seats have stable IDs such as p1. A reconnect rotates the resume ticket, resets input/sequence numbers and keeps the same seat. Offline reservations last five minutes.

Events

ControllerHost extends Node EventEmitter. on(event, callback) returns the host. Use off(event, callback) or once(event, callback) as normal.

connected fires before the new seat's socket and app are assigned. setView there stores a view for delivery with welcome, but initial fallback selection sees no app. Defer app-specific view selection with setImmediate, or send a safe common view first. To observe resume, read roster state from a host Session or check the known seat on subsequent input. There is no reconnected event.

Feedback and phone output

Feedback validation throws before sending. Feedback is transient and is not replayed after reconnect.

Browser assets

await serveControllerAssets(req, res): Promise<boolean> serves /join and /sdk/ for GET/HEAD. Returns true if it handled the request (including a 400/404/405 response), false for other paths. Mount before your game router. It serves only SDK web/, src/, assets/, vendor/, and examples/games/ paths; it rejects hidden/traversal paths. It does not serve your game or sound catalog assets.

Low-level adapter hooks

These public methods support the adapter's implementation. Most games never call them. They use ws WebSocket instances and internal player records, not browser Session objects.

Limits and failures

Client messages: 16,384 bytes and 180 messages/second per socket. Authenticate within five seconds. A send buffer over 262,144 bytes closes as 4008. Held input releases after one second without input, sampled every 250 ms. Player application-message silence beyond five seconds terminates the connection; socket traffic silence beyond eight seconds also terminates it. Session pings keep quiet controllers alive.

JSON errors include the protocol error codes. Adapter errors include room_full, room_expired, unauthorized, invalid_resume, forbidden, rate_limited, invalid_binary and handler_error. A game callback exception during message handling becomes a generic handler_error on the phone. Do not throw from normal event handling; validate and ignore disallowed actions.

Complete server

import http from 'node:http';
import { ControllerHost, serveControllerAssets } from '@controller-plus/sdk/node-host';

const port = 47411;
export const server = http.createServer(async (req, res) => {
  if (await serveControllerAssets(req, res)) return;
  if (req.url === '/qr.svg') {
    res.writeHead(200, { 'Content-Type': 'image/svg+xml' });
    return res.end(await host.qrSVG());
  }
  res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
  res.end('<h1>Join the game</h1><img src="/qr.svg" alt="Scan to join">');
});
export const host = new ControllerHost({
  server, origin: process.env.PUBLIC_ORIGIN || `http://127.0.0.1:${port}`,
  game: { id: 'direct-example', name: 'Direct game', controls: {} }, maxPlayers: 8,
});
host.on('connected', ({ playerId }) => {
  setImmediate(() => host.setView(playerId, { kind: 'waiting', title: 'Lobby', text: 'You joined' }));
});
host.on('event', ({ playerId, event }) => {
  if (event === 'ready') host.playFeedback(playerId, 'ui.confirm');
});
await new Promise(resolve => server.listen(port, '0.0.0.0', resolve));
export async function stop() { await host.close(); await new Promise(r => server.close(r)); }
process.once('SIGINT', stop);

For another device, set PUBLIC_ORIGIN to this computer's reachable LAN address with port 47411 before starting. Use HTTPS/WSS on the internet. See Quickstart for game state, player names, reconnects and QR refresh after removal.