Create a Server

A Colyseus game has a server and one or more clients. The server runs your game rooms and owns their state. Clients connect to it. This page creates the server, and the client SDK pages connect to it.

Prerequisites

• Node.js LTS version (or Bun)
• Git
• A code editor (VS Code recommended)

Setting up your server

# Create a new Colyseus project
npm create colyseus-app@latest ./my-server
 
# Enter the project directory
cd my-server
 
# Run the server
npm start

# Create a new Colyseus project
pnpm create colyseus-app@latest ./my-server
 
# Enter the project directory
cd my-server
 
# Run the server
pnpm start

# Create a new Colyseus project
yarn create colyseus-app ./my-server
 
# Enter the project directory
cd my-server
 
# Run the server
yarn start

# Create a new Colyseus project
bun create colyseus-app@latest ./my-server
 
# Enter the project directory
cd my-server
 
# Install Bun transport & Run the server
bun add @colyseus/bun-websockets
bun run src/index.ts

import { schema, t, type SchemaType } from "@colyseus/schema";
 
export const Player = schema({
  x: t.number().default(0),
  y: t.number().default(0),
});
export type Player = SchemaType<typeof Player>;
 
export const MyRoomState = schema({
  players: t.map(Player),
});
export type MyRoomState = SchemaType<typeof MyRoomState>;

import { Room, Client, CloseCode } from "colyseus";
import { MyRoomState, Player } from "./schema/MyRoomState.js";
 
export class MyRoom extends Room<{ state: MyRoomState }> {
  maxClients = 4;
  state = new MyRoomState();
 
  messages = {
    move: (client: Client, message: { x: number, y: number }) => {
      const player = this.state.players.get(client.sessionId);
      if (!player) { return; }
 
      player.x = message.x;
      player.y = message.y;
    },
  };
 
  onJoin(client: Client, options: any) {
    this.state.players.set(client.sessionId, new Player());
    this.broadcast("chat", `${client.sessionId} joined.`);
  }
 
  onLeave(client: Client, code: CloseCode) {
    this.state.players.delete(client.sessionId);
    this.broadcast("chat", `${client.sessionId} left.`);
  }
}

Build your game logic

The room is where your game runs. Continue with:

Scaffolding options

create-colyseus-app asks a few questions and creates the project from your answers. Each option adds working, wired-in code, and the room comes with a headless test.

Presets

The first question is what you’re building. Pick a preset, or Custom to choose each feature individually.

Using command-line options

Every question has a flag. Options you pass are not asked, and they override the preset. --yes fills the rest with defaults, so a single command works in a terminal, a script, or CI.

npm create colyseus-app@latest my-server -- --preset realtime-action --yes
 
npm create colyseus-app@latest my-server -- --ts --layout vite --netcode fixed \
    --matchmaking lobby,reconnection --auth module --database colyseus --yes

Pass . as the directory to scaffold into the current folder. Omit the directory to be asked for a project name.

The realtime-action preset, the vite and monorepo layouts, fixed netcode, oauth and the database require TypeScript. Haxe projects take none of these options: the generator copies the Haxe template as is.

Other flags: --name <pkg-name>, --git (initialize a repository with a first commit), --no-install, --overwrite. Run npx create-colyseus-app@latest --help for the full reference.

Getting Started TypeScript