Multiplayer
A multiplayer game template adds a Colyseus 0.18 game server to the game. The server is in charge. Players send it requests, such as "move me here". The server checks them, updates the game state, and Colyseus sends the changes to every player.
Answer Yes to "Multiplayer?" when you create a game, or add -multiplayer to its id. Pick a game and a platform lists every id.
- npm
- yarn
- pnpm
- bun
npm create pixi.js@latest my-game -- --template starter-web-multiplayer
yarn create pixi.js my-game --template starter-web-multiplayer
pnpm create pixi.js my-game --template starter-web-multiplayer
bun create pixi.js my-game --template starter-web-multiplayer
Add -js to the id for JavaScript. This page uses the starter game on the web: everyone who opens the game gets a bunny on a shared floor. Click or tap the floor to walk there, and press Jump to make your bunny jump on every player's screen. Open the game in two browser windows to see both bunnies.
The first install needs Git and takes longer than the other templates. Colyseus lists a uWebSockets.js transport as a peer dependency, so npm also downloads uWebSockets.js, about 125 MB, from GitHub. The template doesn't use it. See npm install fails with spawn git.
Project structure
my-game/
├── public/
│ ├── assets/
│ │ ├── sounds/
│ │ │ └── sfx-press.wav
│ │ ├── bunny.png
│ │ └── button.png
│ ├── favicon.png
│ └── style.css
├── server/
│ ├── GameRoom.ts
│ ├── GameState.ts
│ ├── index.ts
│ ├── platform.ts
│ └── world.ts
├── src/
│ ├── assets.ts
│ ├── connect.ts
│ ├── cube.ts
│ ├── main.ts
│ ├── platform.ts
│ ├── scene.ts
│ └── vite-env.d.ts
├── index.html
├── package.json
├── tsconfig.json
└── vite.config.ts
The code in server/ runs on Node.js. Most of it belongs to the game:
index.tsdefines the server and its rooms. A room is one game session that players join.GameRoom.tshandles players joining, sending messages and leaving.GameState.tsdescribes the state that Colyseus keeps in sync on every player's screen.world.tsholds the size of the floor, which the server and the game both import.
Two files come from the platform: server/platform.ts decides who can join and which room they join, and src/connect.ts joins the room from the game. src/scene.ts replaces the single-player scene and draws a bunny for each player, with the spinning cube in the middle of the floor. src/main.ts, src/assets.ts, src/cube.ts and src/platform.ts are the same as in the single-player template.
Scripts
| Script | Runs | What it does |
|---|---|---|
dev | vite | Starts the dev server with the game server inside it, on port 8080 |
build | oxlint && tsc && vite build | Lints, type-checks, then builds the game into dist/client/ and the server into dist/server/ |
preview | node dist/server/server.mjs | Runs the production server, which serves the game and the rooms on port 8080 |
start runs dev. In JavaScript projects, build skips tsc.
The game and the server in one process
vite.config.ts adds the Colyseus Vite plugin:
import { colyseus } from "colyseus/vite";
import { defineConfig } from "vite";
// The dev server and the built game server both listen on this port
const port = 8080;
// https://vite.dev/config/
export default defineConfig({
plugins: [
// Runs the game server inside the dev server. The build writes it to
// dist/server/server.mjs, which also serves the game from dist/client.
colyseus({ serverEntry: "/server/index.ts", port, serveClient: true }),
],
server: {
port,
open: true,
// Lets other people reach the dev server through a cloudflared tunnel
allowedHosts: [".trycloudflare.com"],
},
build: {
// PixiJS, PixiJS 3D and the game libraries together are larger than
// Vite's 500 kB default
chunkSizeWarningLimit: 1000,
},
environments: {
// The game server serves public/ from dist/client, so skip a second copy
colyseus: { build: { copyPublicDir: false } },
},
});
allowedHosts lets the dev server answer requests that come through a cloudflared quick tunnel, which gives it a public HTTPS address. You can use one to play with friends on your dev server, and the Discord platform runs the game inside Discord this way.
In development, npm run dev starts one process. Vite serves the game, and the plugin runs the server from server/index.ts on the same port, so there's no second terminal and no proxy. When you save a file in src/, the page reloads. When you save a file in server/, the plugin reloads the server code without restarting the process. Rooms keep their state, and open pages reconnect on their own, so bunnies stay where they were. A file that both the game and the server import, such as server/world.ts, reloads the pages too. Their old bunnies stay for about 15 seconds, until the room gives up on the old connections. If a page shows "Can't reach the game server", refresh it.
vite build builds two things: the game into dist/client/, and a standalone server into dist/server/server.mjs. With serveClient: true, that server also serves the files in dist/client/, so one Node.js process runs the whole game.
How state sync works
The state
server/GameState.ts describes the state with schema() from @colyseus/schema:
import { schema, t } from "@colyseus/schema";
import type { SchemaType } from "@colyseus/schema";
/**
* A player's bunny. The server sets its position, and its name when players
* sign in.
*/
export const Player = schema(
{ x: t.number(), y: t.number(), name: t.string() },
"Player",
);
/** The room state. Every change is sent to every player in the room. */
export const GameState = schema({ players: t.map(Player) }, "GameState");
export type GameState = SchemaType<typeof GameState>;
players is a map from each player's session id to their Player. Only fields declared here are synced. Colyseus sends just the fields that changed, 20 times a second by default, in a compact binary format.
The room
server/GameRoom.ts is the only code that changes the state:
import { Room } from "colyseus";
import type { Client } from "colyseus";
import { GameState, Player } from "./GameState.ts";
import { onAuth } from "./platform.ts";
import type { JoinOptions } from "./platform.ts";
import { WORLD_HEIGHT, WORLD_WIDTH } from "./world.ts";
/** Every player who joins gets a bunny they can move and make jump */
export class GameRoom extends Room<{ state: GameState }> {
/** Signs players in on platforms that need it, before they join */
static onAuth = onAuth;
state = new GameState();
messages = {
move: (client: Client, message: { x: number; y: number }) => {
const player = this.state.players.get(client.sessionId);
// Clients can send anything, so check the message before using it
if (
!player ||
!Number.isFinite(message?.x) ||
!Number.isFinite(message?.y)
) {
return;
}
player.x = clamp(message.x, 0, WORLD_WIDTH);
player.y = clamp(message.y, 0, WORLD_HEIGHT);
},
jump: (client: Client) => {
this.broadcast("jump", client.sessionId);
},
};
/** The options src/connect.ts joins with, already checked by onAuth */
onJoin(client: Client<{ auth?: { name: string } }>, _options?: JoinOptions) {
// Reloading the dev server rejoins every player into the restored room
if (this.state.players.has(client.sessionId)) return;
this.state.players.set(
client.sessionId,
new Player({
x: Math.random() * WORLD_WIDTH,
y: Math.random() * WORLD_HEIGHT,
// Templates that sign players in, like Discord, set client.auth
name: client.auth?.name ?? "",
}),
);
}
onLeave(client: Client) {
this.state.players.delete(client.sessionId);
}
/** Without this, an error in the room stops the whole server */
onUncaughtException(error: Error) {
console.error(error);
}
}
function clamp(value: number, min: number, max: number) {
return Math.min(Math.max(value, min), max);
}
onJoinadds aPlayerat a random spot when someone joins, andonLeaveremoves it when they leave. After a dev server reload, players join the restored room again, soonJoinkeeps a bunny that's already there. The player'snamecomes fromclient.auth, which the platform'sonAuthsets. On the web it doesn't, sonamestays empty.messageshandles what players send.moveignores anything that isn't a pair of numbers and keeps the bunny on the floor, so a modified client can't send its bunny off the floor. Useclient.sessionIdto know who sent a message, never an id from the message itself.jumpisn't state. Nothing needs to remember that a bunny jumped, so the room passes it on to every player withbroadcastinstead.onUncaughtExceptionlogs errors thrown in the room's code, so one bug doesn't take the server down for everyone.
server/index.ts registers the room under the name game:
import { defineRoom, defineServer } from "colyseus";
import { GameRoom } from "./GameRoom.ts";
import { filterBy, routes } from "./platform.ts";
export const server = defineServer({
rooms: {
// The platform can split players into separate rooms, as Discord does
// with one room per Activity session
game: defineRoom(GameRoom).filterBy(filterBy),
},
routes,
});
How platforms change the server
onAuth, JoinOptions, filterBy and routes come from server/platform.ts, which belongs to the platform. They're how the same room works on every platform:
| Export | What it does | Web | Discord |
|---|---|---|---|
onAuth | Runs before a player joins. What it returns becomes client.auth. | Lets everyone in | Lets in only players signed in with Discord, with their name |
JoinOptions | The options src/connect.ts joins with, so TypeScript checks them | None | The Activity session's instanceId |
filterBy | Join options that split players into separate rooms | None, so everyone joins one room | instanceId, so each Activity session gets its own room |
routes | HTTP routes the server adds | None | /api/token, which trades a sign-in code for a token |
See the web and Discord platforms for their versions of the file.
The game
src/connect.ts exports joinGame(), which joins the game room. On the web it's one call to joinOrCreate("game"); on Discord it also sends the token of the player initPlatform signed in, and the Activity session's id. Either way, the scene doesn't change. See the web's src/connect.ts.
src/scene.ts calls joinGame() and reacts to state changes with Callbacks from @colyseus/sdk:
const room = await joinGame();
const callbacks = Callbacks.get(room);
const players = new Map<string, Container>();
status.text = "";
callbacks.onAdd("players", (player, sessionId) => {
const view = createPlayer(sessionId === room.sessionId, player.name);
view.position.set(player.x, player.y);
players.set(sessionId, view);
world.addChild(view);
const stopWalking = callbacks.onChange(player, () =>
walk(view, player.x, player.y),
);
// Without this, a dev server reload can try to move a removed bunny
view.once("destroyed", stopWalking);
});
const removePlayer = (sessionId: string) => {
const view = players.get(sessionId)!;
players.delete(sessionId);
gsap.killTweensOf([view, ...view.children]);
view.destroy({ children: true });
};
callbacks.onRemove("players", (_player, sessionId) => removePlayer(sessionId));
- The local
playersmap holds the bunny drawn for each session id, so later callbacks can find it. onAddruns for every player already in the room and for each one who joins later, including you. Your own bunny gets the glow.createPlayeralso draws the player'snameabove the bunny. On the webnameis empty, so no label shows.onChangeruns when the server changes a player'sxory. It returns a function that stops listening, which the scene calls when it destroys the bunny.onRemoveruns when a player leaves.
If the connection drops, the SDK tries to reconnect on its own, and the scene shows "Reconnecting..." until it succeeds or "Disconnected" if it can't. The room removes a player as soon as they disconnect, so apart from server reloads in development, a player who drops has to reload the page to play again. When the game leaves the room, the scene removes every bunny.
Clicking the floor sends a move message with the spot you clicked. The bunny doesn't move until the server answers with a new position. walk then tweens it there with GSAP at a steady speed, which also smooths over the gaps between updates:
function walk(view: Container, x: number, y: number) {
gsap.to(view, {
x,
y,
duration: Math.hypot(x - view.x, y - view.y) / SPEED,
ease: "none",
overwrite: true,
});
}
Client<typeof server> in connect.ts imports the server's type, so TypeScript checks room names, and player in the scene's callbacks has the fields from the schema. The import is type-only, so no server code ends up in the game bundle. The game does import server/world.ts, which holds plain numbers.
The floor's size is set in world units in server/world.ts. The scene scales the floor to fit the screen, so a position means the same spot for every player, whatever their screen size.
Run the production build
npm run build
npm run preview
Then open http://localhost:8080. preview runs dist/server/server.mjs with Node.js. It's the same server you deploy.
Deploy
A multiplayer game needs a host that runs Node.js and accepts WebSocket connections. A static host can serve dist/client/, but the game can't connect without the server.
dist/server/server.mjs loads colyseus, express and the other dependencies from node_modules instead of bundling them. On the server:
- Copy
dist/,package.jsonand your lockfile. - Install the dependencies without the dev tools, for example with
npm ci --omit=dev. This still comes to about 380 MB, mostlyuWebSockets.js. - Run
node dist/server/server.mjs, ornpm run preview.
The server listens on port from vite.config.ts, 8080 by default. The build writes the port into dist/server/server.mjs, so to use another one, change it and build again. The server doesn't read the PORT environment variable. A host that picks the port when the server starts and passes it in PORT needs PORT set to your port; if the host doesn't let you choose it, the built server can't run there as it is.
The server answers any path it has no file for with index.html, so a missing asset in production loads as HTML and fails to decode instead of returning a 404.
The Colyseus deployment guide covers process managers, scaling to more than one process, and Colyseus Cloud. A Discord Activity also needs HTTPS and its Discord settings; see deploy a Discord Activity.
Change the game
- Sync more data: add a field to
PlayerorGameState, such asscore: t.number(), and set it in the room. The game sees it inonChange. See schema types. - Show player names: on the web, pass a name in
joinOrCreate("game", { name })insrc/connect.ts, changeJoinOptionsinserver/platform.tsto{ name: string }, and useoptions.namefor the newPlayer'snamein the room'sonJoin. The scene draws it above the bunny. Check that it's a short string first, asmovechecks its message. The Discord platform takes the name from the player's Discord account instead. - Send another action: add a handler to
messagesin the room and callroom.send()from the game. - Limit message spam: set
maxMessagesPerSecondon the room to disconnect a client that sends more messages than that. - Limit players: set
maxClientson the room. When a room is full,joinOrCreateopens a new one. - Keep a player's seat after a dropped connection: the template removes a player as soon as they disconnect. Colyseus can hold the seat while the game reconnects. See reconnection.
Learn more
- Colyseus documentation, including state sync callbacks, rooms and the client SDK.
- Client prediction, to move your own bunny before the server answers.
- Game templates for the libraries the game uses.