Colyseus Multiplayer Framework

0.17.9 · active · verified Sun Apr 19

Colyseus is an authoritative multiplayer framework for Node.js, designed for real-time applications and games. The current stable version is 0.17.9, with consistent releases bringing new features and stability improvements, such as its recent first-class Vite integration. It differentiates itself by offering robust server-side state synchronization, leveraging WebSockets for communication, and providing comprehensive SDKs for a wide array of client platforms including TypeScript, React, Unity, Godot, and GameMaker. This broad support makes it a versatile choice for developers targeting multiple environments, ensuring consistent multiplayer experiences across different game engines and web frameworks. It supports various configurable transport layers and presence/driver integrations, such as Redis, for scaling and flexibility.

Common errors

Warnings

Install

Imports

Quickstart

Demonstrates setting up a basic Colyseus server with a room and state definition within a Vite project using the official plugin, enabling integrated development.

import { defineConfig } from 'vite';
import { colyseus } from 'colyseus/vite';
import { Server, Room } from 'colyseus';
import { Schema, type } from '@colyseus/schema';

// Define your Room State using Colyseus Schema
class MyState extends Schema {
  @type('string') message: string = 'Hello, Colyseus!';
}

// Define your Colyseus Room logic
class MyRoom extends Room<MyState> {
  onCreate(options: any) {
    this.setState(new MyState());
    console.log('MyRoom created with options:', options);
    this.onMessage('hello', (client, message) => {
      console.log(`${client.sessionId} sent: ${message}`);
      this.state.message = `${client.sessionId} says: ${message}`;
      client.send('ack', `Server received: ${message}`);
    });
  }

  onJoin(client: any, options: any) {
    console.log(`${client.sessionId} joined MyRoom.`);
    this.broadcast('player_joined', `${client.sessionId} has joined!`);
  }

  onLeave(client: any, consented: boolean) {
    console.log(`${client.sessionId} left MyRoom (consented: ${consented}).`);
    this.broadcast('player_left', `${client.sessionId} has left!`);
  }

  onDispose() {
    console.log('MyRoom disposed.');
  }
}

// Create a Colyseus Server instance
const gameServer = new Server();
gameServer.define('my_room', MyRoom);

export default defineConfig({
  plugins: [
    colyseus({
      serverEntry: '/src/server/index.ts', // Adjust path to your server entry file
      serveClient: true, // Serve client-side assets alongside the server
      devServer: {
        server: gameServer,
        port: Number(process.env.COLYSEUS_PORT ?? 2567), // Default Colyseus port or env variable
      },
    }),
  ],
  build: {
    rollupOptions: {
      external: ['@colyseus/tools'] // Example: Externalize if not bundling server tools
    }
  }
});

view raw JSON →