Version 0.17 is out! 🎉 - Read the migration guide and upgrade your projects.
Built-in ToolsPlayground

Playground

The Colyseus Playground is a browser-based development tool for real-time debugging of your multiplayer server. It lets you create and manage WebSocket room connections, inspect synchronized state, send and receive messages, and test HTTP endpoints — all without writing any client-side code.

Installation

This package is installed by default on new projects created via npm create colyseus-app.

npm install --save @colyseus/playground

Then, import and mount it as an Express middleware:

app.config.ts
import { defineServer } from "colyseus";
import { playground } from "@colyseus/playground";
 
const server = defineServer({
    // ...
    express: (app) => {
        app.use("/playground", playground());
    }
});

Usage

Once mounted, start your server and navigate to http://localhost:2567/playground in your browser.

If you mounted the playground at a different path (e.g. app.use("/my-path", playground())), adjust the URL accordingly.

⚠️

The playground exposes full access to your rooms and server endpoints. Do not expose it in production without password protection. You can use express-basic-auth to restrict access:

npm install --save express-basic-auth
import basicAuth from "express-basic-auth";
 
const basicAuthMiddleware = basicAuth({
    users: { "admin": "admin" },
    challenge: true
});
 
app.use("/playground", basicAuthMiddleware, playground());

Features

  • Create room connections via joinOrCreate / create / join
  • When joinById is selected, provides a list of active rooms by id
  • Authenticate using credentials auto-detected from Auth Module
  • Simulate room connection drops to test reconnection logic
  • Visualize the client state in JSON format
  • Allow the client to send messages by type (auto-detected)
  • Built-in viewer and tester for server HTTP endpoints (similar to Postman)

Screenshots

Rooms

All rooms defined in your server configuration are automatically listed here, allowing you to create connections, inspect state, send messages, and simulate disconnections.

API Endpoints

All HTTP routes registered on your server are automatically detected and listed here, letting you test requests and inspect responses directly from the browser.

Contribute

This tool is built using React and TailwindCSS, making it easy for community members to contribute. See source-code

Built-in ToolsMonitoring Panel