Getting Started

Prerequisites

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

Frontend

Colyseus is unopinionated on the game engine or framework you use in the frontend. See how to get started with one of the official SDKs available for different platforms:

Backend

Run one command and follow the prompts to create your local development server.

Create your Colyseus server

Terminal: npm

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

Terminal: pnpm

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

Terminal: yarn

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

Terminal: Bun

# 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

The generator asks which language to use and what you’re building. Minimal server is enough to follow along. See Scaffolding options for every preset and flag.

Edit your room code

Go to src/rooms/MyRoom.ts and start building your game logic! See more:

Room API State Synchronization Netcode: Prediction & Lag Comp

🤖 Using an AI coding agent

Most models learned Colyseus from material older than 0.18. Without guidance, they write colyseus.js imports, Room<MyState> generics and client.id. The Colyseus skill keeps the agent on the current APIs and has it check your installed version before writing any Room or Schema code. Install it for Claude Code, Codex, Cursor, Gemini CLI, Copilot or any other agent that supports skills:

Terminal

npx skills add colyseus/skill            # this project
npx skills add colyseus/skill --global   # every project

The skill activates on its own when a task involves Colyseus. Bundled docs cover the areas agents get wrong most (state, rooms, the client SDK, netcode), with links to the rest.

Without the skill, point the agent at llms.txt. Every page is also served as raw markdown: append .md to its URL, e.g. /room.md.

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.

Preset	`--preset`	What you get
Minimal server	`minimal`	A single room, nothing else.
Realtime action	`realtime-action`	Vite project (client, server and shared code) with an authoritative fixed tick, server-validated input and client-side prediction, plus lobby and reconnection. TypeScript only.
Turn-based	`turn-based`	Server-owned turn order with a per-turn deadline, plus reconnection.
Custom	`custom`	Asks every question: layout, netcode, matchmaking, authentication and database.

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.

Terminal

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

npm create needs the -- separator to forward options to the generator. pnpm, yarn, bun create and npx create-colyseus-app@latest don’t.

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

Option	Choices (first is the default)
`--language`	`typescript` · `esm` · `cjs` · `haxe`. Also as shorthand flags: `--ts`, `--esm`, `--cjs`, `--haxe`
`--preset`	`minimal` · `realtime-action` · `turn-based` · `custom`
`--layout`	`server` · `vite` (client + server + shared code in one Vite project) · `monorepo` (`apps/backend` + `apps/frontend`)
`--netcode`	`none` · `fixed` (fixed tick + client prediction) · `tick` (simple server tick) · `turn-based` · `relay` (client-authoritative)
`--matchmaking`	none by default. Comma-separated: `lobby` · `filterby` · `reconnection` · `idle-kick`
`--auth`	`none` · `onauth` (validate a token in `onAuth()`, no dependencies) · `module` (`@colyseus/auth`: anonymous + email/password) · `oauth` (`@colyseus/auth` + OAuth provider)
`--oauth-provider`	`discord` · `google` · `github` · `twitch`
`--database`	`none` · `colyseus` (`@colyseus/database`: SQLite in development, Postgres in production)

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.

Introduction

TypeScript