Colyseus Multiplayer Framework

Colyseus is an open-source Node.js framework for building authoritative game servers — with real-time state synchronization, matchmaking, and effortless integration into any game engine or frontend.

Key Features

Rooms and Matchmaking — From a single Room definition, clients are matched into multiple Room instances.
State Synchronization — Define your state on the server, and it’s automatically synchronized to all connected clients.
Scalable — Built for horizontal and vertical scalability across multiple processes.
Deploy Anywhere — Self-host for free, or use Colyseus Cloud for managed hosting.

How does it look like?

Create a server

Create and start a new Colyseus server using the following commands:

Terminal: Node.js

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

Define your Room State

The Room state is the data structure that will be synchronized between the server and the connected clients:

src/rooms/MyState.ts

import { Schema, MapSchema, type } from "@colyseus/schema";
 
export class Player extends Schema {
    @type("number") x: number = 0;
    @type("number") y: number = 0;
}
 
export class MyState extends Schema {
    @type({ map: Player }) players = new MapSchema<Player>();
}

Create your Room code

Define the game logic and client interactions with the game state within your Room code.

src/rooms/MyRoom.ts

import { Room, Client } from "@colyseus/core";
import { MyState, Player } from "./MyState";
 
export class MyRoom extends Room {
    maxClients = 4;
    state = new MyState();
 
    messages = {
        doSomething: (client, payload) => {
            // handle client's "doSomething" message
        }
    }
 
    // Called when the room is created
    onCreate(options) { }
 
    // Called when a client joins the room
    onJoin(client: Client, options: any) {
        this.state.players.set(client.sessionId, new Player());
    }
 
    // Called when a client leaves the room
    onLeave(client: Client, options: any) {
        this.state.players.delete(client.sessionId);
    }
 
    // Called when the room is disposed
    onDispose() { }
}

Expose the Room identifier

Exposing the room type allows clients to connect to the server and dynamically create instances of it.

src/app.config.ts

import { defineServer, defineRoom } from "colyseus";
import { MyRoom } from "./MyRoom";
 
const server = defineServer({
    rooms: {
        my_room: defineRoom(MyRoom),
    },
});

Join the Room from the client SDK

Communication between the client and server occurs through room connections. Below are examples for each SDK showing how to join a room and listen for state changes:

client.ts

import { Client, Callbacks } from "@colyseus/sdk";
 
async function connect() {
    const client = new Client('http://localhost:2567');
    const room = await client.joinOrCreate('my_room', {
        /* custom join options */
    });
    const callbacks = Callbacks.get(room);
 
    // Listen to 'player' instance additions
    callbacks.onAdd("players", (player, sessionId) => {
        console.log('Player joined:', player);
    });
 
    // Listen to 'player' instance removals
    callbacks.onRemove("players", (player, sessionId) => {
        console.log('Player left:', player);
    });
 
    // Send messages to the server
    room.send("doSomething", {/* ... */});
 
    return room;
}
 
connect();

Client.cs

using Colyseus;
 
async void Connect() {
    var client = new Client("http://localhost:2567");
 
    try {
        var room = await client.JoinOrCreate<MyRoomState>("my_room");
        var callbacks = Colyseus.Schema.Callbacks.Get(room);
 
        // Listen to 'player' instance additions
        callbacks.OnAdd(state => state.players, (sessionId, player) => {
            Debug.Log($"Player joined: {sessionId}");
        });
 
        // Listen to 'player' instance removals
        callbacks.OnRemove(state => state.players, (sessionId, player) => {
            Debug.Log($"Player left: {sessionId}");
        });
 
        // Send messages to the server
        room.Send("doSomething", new { /* ... */ });
 
    } catch (Exception ex) {
        Debug.Log("join error");
        Debug.Log(ex.Message);
    }
}

client.lua

local ColyseusSDK = require("colyseus.sdk")
 
local client = ColyseusSDK.Client("http://localhost:2567")
 
client:join_or_create("my_room", {--[[custom join options]]}, function(err, room)
    if (err ~= nil) then
        print("join error: " .. err)
        return
    end
 
    local callbacks = ColyseusSDK.callbacks(room)
 
    -- Listen to 'player' instance additions
    callbacks:on_add("players", function(player, sessionId)
        print("Player joined:", sessionId)
    end)
 
    -- Listen to 'player' instance removals
    callbacks:on_remove("players", function(player, sessionId)
        print("Player left:", sessionId)
    end)
 
    -- Send messages to the server
    room:send("doSomething", {--[[ ... ]]})
end)

Client.hx

import io.colyseus.Client;
import io.colyseus.serializer.schema.Callbacks;
 
class Main {
    static function main() {
        var client = new Client("http://localhost:2567");
 
        client.joinOrCreate("my_room", [], MyRoomState, function(err, room) {
            if (err != null) {
                trace("join error: " + err);
                return;
            }
 
            var callbacks = Callbacks.get(room);
 
            // Listen to 'player' instance additions
            callbacks.onAdd("players", function(player, sessionId) {
                trace("Player joined: " + sessionId);
            });
 
            // Listen to 'player' instance removals
            callbacks.onRemove("players", function(player, sessionId) {
                trace("Player left: " + sessionId);
            });
 
            // Send messages to the server
            room.send("doSomething", [/* ... */]);
        });
    }
}

Explore more

Explore more about Colyseus by following the tutorials and example projects:

Example Projects Tutorials

Getting Started