Match-maker API

The methods described below are provided by the matchMaker singleton, which can be imported from the "colyseus" package:

import { matchMaker } from "colyseus";

const matchMaker = require("colyseus").matchMaker;

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 on gameServer.define().
• 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 on gameServer.define().
• 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 on gameServer.define().
• 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 on gameServer.define().
• 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 }
*/

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 client-side from creating rooms

You can restrict the client-side to be allowed only to call specific matchmaking methods.

Example: by exposing only join, joinById, and reconnect methods, the client-side 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'