Playground

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

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)

⚠️

The playground exposes full access to your rooms and server endpoints. Do not expose it in production without password protection. See Password protection below.

Installation

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

npm install --save @colyseus/playground

pnpm add @colyseus/playground

yarn add @colyseus/playground

bun add @colyseus/playground

Mounting

The playground can be mounted in two ways.

Standard router (recommended)

Spread playground() into createRouter and set the prefix to the path you want it served from:

app.config.ts

import { defineServer, createRouter } from "colyseus";
import { playground } from "@colyseus/playground";
 
const server = defineServer({
    routes: createRouter({
        ...playground({ prefix: "/playground" }),
    })
});

prefix defaults to '', which serves the playground from the root. When spreading into createRouter you almost always want to pass an explicit prefix such as "/playground".

Express middleware

Use this mode if you rely on existing Express middleware or libraries:

app.config.ts

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

In express-middleware mode the prefix option is ignored. Express strips its own mount path before dispatching.

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, adjust the URL accordingly.

Password protection

The playground exposes full access to your rooms and server endpoints. Do not expose it in production without password protection. Pass a guard middleware through the playground’s use option. Colyseus ships with a built-in basicAuth:

app.config.ts

import { defineServer, createRouter, basicAuth } from "colyseus";
import { playground } from "@colyseus/playground";
 
const guard = basicAuth({ users: { admin: "s3cret" } });
 
const server = defineServer({
    routes: createRouter({
        ...playground({ prefix: "/playground", use: [guard] }),
    })
});

The use option works in both mounting modes, so you can pass the same guard when mounting via Express:

app.config.ts

app.use("/playground", playground({ use: [guard] }));

See HTTP Routes → Basic authentication for basicAuth options and behavior.

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 Tools Monitoring Panel