Skip to content

Getting started

Colyseus requires Node.js v8.0 or higher.

From examples project

See some examples in action by cloning the examples project and running it locally.

git clone https://github.com/colyseus/colyseus-examples.git
cd colyseus-examples
npm install
npm run bundle-colyseus-client

To run the http + websocket server, run npm start.

Creating a barebones Colyseus server

Create a directory for your server.

mkdir server
cd server

1. Create a package.json file:

npm init

2. Install the colyseus module:

npm install colyseus --save

3. Install the typescript, and ts-node modules as development dependencies.

npm install typescript ts-node --save-dev

4. Create the tsconfig.json file:

npx tsc --init

5. Create a index.ts file for the server:

// index.ts
import http from "http";
import { Server } from "colyseus";

const port = Number(process.env.PORT || 2567);

const server = http.createServer();
const gameServer = new Server({ server });

gameServer.listen(port);
console.log(`Listening on ws://localhost:${ port }`)

6. Create your room handler (e.g. MyRoom.ts)

// MyRoom.ts
import { Room, Client } from "colyseus";

export class MyRoom extends Room {
      onInit (options: any) {}
      onJoin (client: Client, options: any) {}
      onMessage (client: Client, message: any) {}
      onLeave (client: Client, consented: boolean) {}
      onDispose() {}
}

More on room handlers

See the Room API for more details about room handlers.

7. Import and register your room handler in the index.ts file:

// index.ts
// ...
import { MyRoom } from "./MyRoom";
// ...
gameServer.register('my_room', MyRoom);
// ...

8. Start the server!

npx ts-node index.ts

Using JavaScript

3. Create a index.js file for the server:

// index.js
const http = require("http");
const colyseus = require("colyseus");

const port = process.env.PORT || 2567;

const server = http.createServer();
const gameServer = new colyseus.Server({
      server: server
});

gameServer.listen(port);
console.log(`Listening on ws://localhost:${ port }`)

4. Create your room handler (e.g. MyRoom.js)

// MyRoom.js
const colyseus = require("colyseus")

export class MyRoom extends colyseus.Room {
      onInit (options) {}
      onJoin (client, options) {}
      onMessage (client, message) {}
      onLeave (client, consented) {}
      onDispose() {}
}

More on room handlers

See the Room API for more details about room handlers.

5. Import and register your room handler in the index.js file:

// index.js
// ...
const MyRoom = require("./MyRoom").MyRoom
// ...
gameServer.register('my_room', MyRoom);
// ...

6. Start the server!

node index.js

These modules can be useful while developing games on both NodeJS and the Browser.

These modules can be used only in the browser: