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 withhost.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.maxMessageBytesafterready. 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 do | Pages |
|---|---|
| Register a host, take input, broadcast state | Game logic inside the server |
| Watch tick intervals, inputs and blocked forgeries live | Server dashboard |
| Connections and subscriptions of browser screens | Get started in the browser, JS subscriptions and lifecycle |
| Server options, quotas and host methods | Server API |
| Open the server to other devices and the internet | Get 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
inboundand that the quota is not exceeded. The server'sserver.stats()and the dashboard show how many inputs were dropped.