{"id":10651,"library":"colyseus","title":"Colyseus Multiplayer Framework","description":"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.","status":"active","version":"0.17.9","language":"javascript","source_language":"en","source_url":"git://github.com/colyseus/colyseus","tags":["javascript","colyseus","multiplayer","netcode","realtime","networking","websockets","typescript"],"install":[{"cmd":"npm install colyseus","lang":"bash","label":"npm"},{"cmd":"yarn add colyseus","lang":"bash","label":"yarn"},{"cmd":"pnpm add colyseus","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core server-side functionalities, required for the Colyseus server instance.","package":"@colyseus/core","optional":false},{"reason":"Required for defining and synchronizing room state with binary delta compression.","package":"@colyseus/schema","optional":false},{"reason":"Optional package for authentication and authorization features.","package":"@colyseus/auth","optional":true},{"reason":"Optional Redis-backed room driver for scaling across multiple processes/servers.","package":"@colyseus/redis-driver","optional":true},{"reason":"Optional Redis-backed presence system for managing user presence across servers.","package":"@colyseus/redis-presence","optional":true},{"reason":"Optional transport layer using uWS.js for high performance.","package":"@colyseus/uwebsockets-transport","optional":true},{"reason":"Optional default WebSocket transport layer.","package":"@colyseus/ws-transport","optional":true},{"reason":"Optional transport layer for h3 (e.g., Nuxt, Nitro) environments.","package":"@colyseus/h3-transport","optional":true},{"reason":"Optional transport layer optimized for Bun runtime.","package":"@colyseus/bun-websockets","optional":true},{"reason":"Required for using the Colyseus Vite plugin for integrated development workflow.","package":"vite","optional":true}],"imports":[{"note":"Colyseus recommends ESM `import` statements for Node.js 20+ environments. While CommonJS `require` might work in some configurations, ESM is the standard.","wrong":"const { Server } = require('colyseus');","symbol":"Server","correct":"import { Server } from 'colyseus';"},{"note":"The `Room` class is the fundamental building block for defining multiplayer game logic and state. Use ESM `import` for modern Node.js environments.","wrong":"const { Room } = require('colyseus');","symbol":"Room","correct":"import { Room } from 'colyseus';"},{"note":"The Vite plugin for Colyseus is exposed via a subpath export. It must be imported specifically from `'colyseus/vite'`.","wrong":"import { colyseus } from 'colyseus'; // Incorrect path","symbol":"colyseus (Vite plugin)","correct":"import { colyseus } from 'colyseus/vite';"},{"note":"Schema-related classes and types for defining synchronized state are part of the separate `@colyseus/schema` package, not directly from the main `colyseus` package.","wrong":"import { Schema } from 'colyseus';","symbol":"Schema","correct":"import { Schema, type ArraySchema, type MapSchema } from '@colyseus/schema';"}],"quickstart":{"code":"import { defineConfig } from 'vite';\nimport { colyseus } from 'colyseus/vite';\nimport { Server, Room } from 'colyseus';\nimport { Schema, type } from '@colyseus/schema';\n\n// Define your Room State using Colyseus Schema\nclass MyState extends Schema {\n  @type('string') message: string = 'Hello, Colyseus!';\n}\n\n// Define your Colyseus Room logic\nclass MyRoom extends Room<MyState> {\n  onCreate(options: any) {\n    this.setState(new MyState());\n    console.log('MyRoom created with options:', options);\n    this.onMessage('hello', (client, message) => {\n      console.log(`${client.sessionId} sent: ${message}`);\n      this.state.message = `${client.sessionId} says: ${message}`;\n      client.send('ack', `Server received: ${message}`);\n    });\n  }\n\n  onJoin(client: any, options: any) {\n    console.log(`${client.sessionId} joined MyRoom.`);\n    this.broadcast('player_joined', `${client.sessionId} has joined!`);\n  }\n\n  onLeave(client: any, consented: boolean) {\n    console.log(`${client.sessionId} left MyRoom (consented: ${consented}).`);\n    this.broadcast('player_left', `${client.sessionId} has left!`);\n  }\n\n  onDispose() {\n    console.log('MyRoom disposed.');\n  }\n}\n\n// Create a Colyseus Server instance\nconst gameServer = new Server();\ngameServer.define('my_room', MyRoom);\n\nexport default defineConfig({\n  plugins: [\n    colyseus({\n      serverEntry: '/src/server/index.ts', // Adjust path to your server entry file\n      serveClient: true, // Serve client-side assets alongside the server\n      devServer: {\n        server: gameServer,\n        port: Number(process.env.COLYSEUS_PORT ?? 2567), // Default Colyseus port or env variable\n      },\n    }),\n  ],\n  build: {\n    rollupOptions: {\n      external: ['@colyseus/tools'] // Example: Externalize if not bundling server tools\n    }\n  }\n});","lang":"typescript","description":"Demonstrates setting up a basic Colyseus server with a room and state definition within a Vite project using the official plugin, enabling integrated development."},"warnings":[{"fix":"Update your Node.js installation to version 20.x or later. Ensure your deployment environment also meets this minimum requirement.","message":"Colyseus now requires Node.js version 20.x or higher. Projects running on older Node.js versions must upgrade their environment to ensure compatibility and correct execution.","severity":"breaking","affected_versions":">=0.17.0"},{"fix":"Update `@colyseus/sdk` to version 0.17.40 or higher to correctly interpret the new reconnection close codes during development. This improves the HMR experience.","message":"Reconnection behavior in `devMode` has been updated (since v0.17.13 for transports). The server now sends `MAY_TRY_RECONNECT` close codes instead of `FAILED_TO_RECONNECT` during HMR reloads. This allows the client SDK to retry reconnection attempts more gracefully in development.","severity":"gotcha","affected_versions":">=0.17.13 (transports), >=0.17.40 (sdk)"},{"fix":"Upgrade `@colyseus/sdk` to version 0.17.40 or newer. This release includes fixes to the type definitions, resolving erroneous type inference issues.","message":"Type inference for `client.http.*` methods in `@colyseus/sdk` was previously flawed, potentially incorrectly requiring `query` and `params` arguments on endpoints that did not declare them, especially when `strictNullChecks` was disabled in TypeScript.","severity":"gotcha","affected_versions":">=0.17.40 (@colyseus/sdk)"},{"fix":"Review any custom server shutdown or reconnection logic. While standard setups may not require code changes, this affects the sequence of events during graceful shutdown and room state management. Ensure `onLeave` handles client disconnections as expected.","message":"A fix in `gracefullyShutdown` ordering (in `@colyseus/core` 0.17.41) ensures pending `allowReconnection()` deferreds are rejected before room states are cached. This guarantees `onLeave()` cleanup routines run prior to state caching, preventing stale player data in restored room states.","severity":"breaking","affected_versions":">=0.17.41 (@colyseus/core)"},{"fix":"Add or verify these compiler options in your `tsconfig.json`:\n```json\n{\n  \"compilerOptions\": {\n    \"experimentalDecorators\": true,\n    \"useDefineForClassFields\": false\n  }\n}\n```","message":"When using TypeScript with schema decorators (`@type()`), it's crucial to set `\"experimentalDecorators\": true` and `\"useDefineForClassFields\": false` in your `tsconfig.json` for proper property accessor definition, especially when targeting ES2022 or higher.","severity":"gotcha","affected_versions":"*"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure your project uses ES Module `import` statements (e.g., `import { Server } from 'colyseus';`). If you are running Node.js >= 20.x, it's recommended to set `\"type\": \"module\"` in your `package.json` for top-level ESM support. For TypeScript, configure `\"module\": \"Node16\"` or `\"ES2022\"` in `tsconfig.json`.","cause":"This error occurs when attempting to use CommonJS `require()` syntax to load a Colyseus module (or its dependencies) in a Node.js environment configured for ES Modules, or if the package itself is ESM-only. Colyseus increasingly favors ESM.","error":"ERR_REQUIRE_ESM: require() of ES Module ... not supported. Instead change the require of ... to a dynamic import()"},{"fix":"Verify that the Vite plugin is imported from the correct subpath using named imports: `import { colyseus } from 'colyseus/vite';`.","cause":"This typically indicates an incorrect import path for the Colyseus Vite plugin or a misuse of its export, often a default import when a named import from a subpath is expected.","error":"TypeError: (0 , colyseus_vite_1.colyseus) is not a function"},{"fix":"Update the `@colyseus/sdk` package to version 0.17.40 or newer. This version contains type definition corrections that resolve this issue.","cause":"This error arises from the incorrect type inference in `@colyseus/sdk` (fixed in 0.17.40) where `client.http` methods incorrectly mandated `query` or `params` even when not needed for the specific API endpoint.","error":"Property 'query' is missing in type '{}' but required in type 'ClientHttpRequestOptions'"},{"fix":"Increase the `seatReservationTime` in your Colyseus server configuration to allow more time for clients to connect. Verify your server's network and scaling setup. Crucially, ensure all `@colyseus/*` packages in your `package.json` are consistent in their major/minor version (e.g., all `0.17.x`).","cause":"This error means that the client failed to establish a connection to a reserved room within the allocated time. Common causes include the server being under heavy load, incorrect network configuration, or mixed Colyseus package versions (e.g., mixing 0.14.x and 0.15.x).","error":"Error: seat reservation expired"}],"ecosystem":"npm"}