Skip to main content

Get started with games

Build real-time games, quizzes and votes that several people join from browsers or phones. Clients only send input; a host inside the server (server.host) decides scores and winners. If you are new, read core concepts in five minutes first.

1. Install​

Games run on your own IOSignal server. A host runs inside the server process, so it cannot be put on the public server (io.iosignal.net). With Node.js 22.16.0 or later, one package gives you both the server and the browser client.

npm install iosignal

Server code uses import { Server } from 'iosignal'; browser screens use import IO from 'iosignal/io'.

2. First connection: Host Quiz​

The Host Quiz example is a real-time quiz whose questions and scoring are run by a host inside the server.

git clone https://github.com/remocons/iosignal-examples.git
cd iosignal-examples/iosignal_host-quiz
npm ci
npm start

Open http://localhost:5181 in two or more windows and play. When both scoreboards change together, it works. Use the example's cheating panel (its screens are in Korean) to forge the scoreboard and see the server drop it.

3. What differs for games​

  • Judge on the server: with plain channels anyone can send to any channel, and messages carry no sender. A host receives the sender the server checked (from.cid) with every input, and only the host may send tags such as the scoreboard. Game logic inside the server
  • Keep input within the quota: each connection has a messages-per-second and bytes-per-second limit, and input above it is dropped silently. Send when something changes or at a fixed rate, not on every frame. Quota and limits
  • State broadcasts: send what everyone sees with host.publish('game#$state', …). With $ the server keeps the last value, so a screen that joins late gets it at once. Send a result for one player with host.to(cid, …).
  • Reconnections and leaving: an anonymous connection gets a new CID when it reconnects and joins as a new player. To keep the same person, use authentication. When a connection that sent input closes, the host gets leave.
  • Message size: the server sets the largest message; clients read io.quota.maxMessageBytes after ready. Keep the state short.
  • Several servers: a host sees only the connections on its own server, so the players of one room must connect to the same server.
  • Boards can play: Arduino can send input with the same tags and receive results in onMessage.

4. Build guides​

What you want to doPages
Register a host, take input, broadcast stateGame logic inside the server
Watch tick intervals, inputs and blocked forgeries liveServer dashboard
Connections and subscriptions of browser screensGet started in the browser, JS subscriptions and lifecycle
Server options, quotas and host methodsServer API
Open the server to other devices and the internetGet started with a server

5. Examples​

  • Host Quiz: a quiz the server scores, blocked forgeries, dashboard

6. When you are stuck​

  • A screen does not reach the server: connection diagnosis
  • Input does not reach the host: check that the tag is in the host's inbound and that the quota is not exceeded. The server's server.stats() and the dashboard show how many inputs were dropped.