Match-maker API

The Match-maker API gives you server-side control over room management and player matchmaking in Colyseus.

You can programmatically create rooms, join players to existing rooms, query and search for available rooms, reserve seats for players, monitor statistics like connected users (CCU) and room counts across processes, and even call methods on rooms running in different processes—all programmatically from your server code rather than relying solely on client requests.

import { matchMaker } from "colyseus";

Stats

Colyseus internally keeps track of statistics for the matchmaker.

Fetch All

Fetch all stats from all processes.

Returns an array of objects with the following properties:

• processId: the id of the process.
• roomCount: the number of rooms on the process.
• ccu: the number of connected clients on the process.

import { matchMaker } from "colyseus";
const stats = await matchMaker.stats.fetchAll();
 
console.log(stats);
// => [
//    { processId: "xxx", roomCount: 10, ccu: 100 },
//    { processId: "yyy", roomCount: 9, ccu: 90 },
// ]

Get Global CCU

Get the total number of connected clients across all processes.

import { matchMaker } from "colyseus";
const globalCCU = await matchMaker.stats.getGlobalCCU();
 
console.log(globalCCU);
// => 190

Get Local CCU

Get the number of connected clients on the current process.

matchMaker.stats.local.ccu

Get Local Room Count

Get the number of rooms on the current process.

matchMaker.stats.local.roomCount

Match-making

Create a Room

Creates a new room and return its cached data.

matchMaker.createRoom(roomName, options)

Parameters:

• roomName: the identifier you defined in the rooms configuration of defineServer().
• options: options for onCreate.

const room = await matchMaker.createRoom("battle", { mode: "duo" });
console.log(room);
/*
  { "roomId": "xxxxxxxxx", "processId": "yyyyyyyyy", "name": "battle", "locked": false }
*/

Join or Create a Room

Join or create a room and return a client seat reservation.

matchMaker.joinOrCreate(roomName, options)

Parameters:

• roomName: the identifier you defined in the rooms configuration of defineServer().
• options: options for the client seat reservation (for onJoin/onAuth).

const reservation = await matchMaker.joinOrCreate("battle", { mode: "duo" });
console.log(reservation);
/*
  {
    "sessionId": "zzzzzzzzz",
    "room": { "roomId": "xxxxxxxxx", "processId": "yyyyyyyyy", "name": "battle", "locked": false }
  }
*/

Reserve A Seat For

Creates a seat reservation in a specific room.

matchMaker.reserveSeatFor(room, clientOptions, authData)

Parameters:

• room: room data (result from createRoom(), etc).
• clientOptions: options for onJoin.
• authData: authentication data (available during onJoin as client.auth)

const room = await matchMaker.findOneRoomAvailable("battle", { mode: "duo" });
const reservation = await matchMaker.reserveSeatFor(room);
console.log(reservation);
/*
  {
    "sessionId": "zzzzzzzzz",
    "room": { "roomId": "xxxxxxxxx", "processId": "yyyyyyyyy", "name": "battle", "locked": false }
  }
*/

Join existing Room

Join a room and return seat reservation. An exception is thrown if there are no rooms available for roomName.

matchMaker.join(roomName, options)

Parameters:

• roomName: the identifier you defined in the rooms configuration of defineServer().
• options: options for the client seat reservation (for onJoin/onAuth).

const reservation = await matchMaker.join("battle", { mode: "duo" });
console.log(reservation);
/*
  {
    "sessionId": "zzzzzzzzz",
    "room": { "roomId": "xxxxxxxxx", "processId": "yyyyyyyyy", "name": "battle", "locked": false }
  }
*/

Join Room by ID

Join a room by id and return client seat reservation. An exception is thrown if a room is not found for roomId.

matchMaker.joinById(roomId, options)

Parameters:

• roomId: the id of a specific room instance.
• options: options for the client seat reservation (for onJoin/onAuth).

const reservation = await matchMaker.joinById("xxxxxxxxx", {});
console.log(reservation);
/*
  {
    "sessionId": "zzzzzzzzz",
    "room": { "roomId": "xxxxxxxxx", "processId": "yyyyyyyyy", "name": "battle", "locked": false }
  }
*/

Create and Reserve a Seat

Create a new room and return client seat reservation.

matchMaker.create(roomName, options)

Parameters:

• roomName: the identifier you defined in the rooms configuration of defineServer().
• options: options for the client seat reservation (for onJoin/onAuth).

const reservation = await matchMaker.create("battle", { mode: "duo" });
console.log(reservation);
/*
  {
    "sessionId": "zzzzzzzzz",
    "room": { "roomId": "xxxxxxxxx", "processId": "yyyyyyyyy", "name": "battle", "locked": false }
  }
*/

Search for Rooms

Perform a query against cached rooms.

matchMaker.query(conditions, sortOptions?)

Parameters:

• conditions: key-value conditions object.
• sortOptions: key-value sort object.

const rooms = await matchMaker.query({ name: "battle", mode: "duo" });
console.log(rooms);
/*
[
    { "roomId": "xxxxxxxxx", "processId": "yyyyyyyyy", "name": "battle", "locked": false },
    { "roomId": "xxxxxxxxx", "processId": "yyyyyyyyy", "name": "battle", "locked": false },
    { "roomId": "xxxxxxxxx", "processId": "yyyyyyyyy", "name": "battle", "locked": false }
]
*/

const rooms = await matchMaker.query({ name: "battle", mode: "duo" }, { clients: -1});

Find One Room Available

Find for a public and unlocked room available.

matchMaker.findOneRoomAvailable(roomName, options)

Parameters:

• roomName: the id of a specific room instance.
• options: options for the client seat reservation (for onJoin/onAuth).

const room = await matchMaker.findOneRoomAvailable("battle", { mode: "duo" });
console.log(room);
/*
  { "roomId": "xxxxxxxxx", "processId": "yyyyyyyyy", "name": "battle", "locked": false }
*/

Get Room by ID

Get room data by id. This method will return the cached room data. It is safe to call from any process.

matchMaker.getRoomById(roomId)

Parameters:

• roomId: the id of a specific room instance.

const room = await matchMaker.getRoomById("xxxxxxxxx");
console.log(room);
/*
  { "roomId": "xxxxxxxxx", "processId": "yyyyyyyyy", "name": "battle", "locked": false }
*/

Get Local Room by ID

Get the actual Room instance by id. This method only returns the room instance if it’s available in the current process, otherwise it will return undefined.

matchMaker.getLocalRoomById(roomId)

Parameters:

• roomId: the id of a specific room instance.

const room = await matchMaker.getLocalRoomById("xxxxxxxxx");
room.clients[0].send("hello", "world");

Remote Room Call

Call a method or return a property on a remote room.

matchMaker.remoteRoomCall(roomId, method, args)

Parameters:

• roomId: the id of a specific room instance.
• method: method or attribute to call or retrieve.
• args: array of arguments.

// call lock() on a remote room by id
await matchMaker.remoteRoomCall("xxxxxxxxx", "lock");

Restricting the frontend from creating rooms

You can restrict the frontend to be allowed only to call specific matchmaking methods.

Example: by exposing only join, joinById, and reconnect methods, the frontend is not going to be able to perform create or joinOrCreate calls.

import { matchMaker } from "colyseus";
 
matchMaker.controller.exposedMethods = ['join', 'joinById', 'reconnect'];

Possible values for exposedMethods are:

• 'create'
• 'join'
• 'joinById'
• 'joinOrCreate'
• 'reconnect'