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 }
*/

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 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'