Lobby Room

The built-in LobbyRoom provides a live listing of available rooms in your game server.

Features:

Live listing for rooms with enableRealtimeListing().
Automatic updates when rooms are created, joined, left, or disposed.
Filter support by room name, optionally narrowed by metadata.

Rooms flagged private or unlisted never appear in the lobby listing. (locked rooms remain listed, marked as locked.)

The source-code for LobbyRoom is available here. You can extend it for custom listing behavior.

Server

Expose the lobby room

server.ts

import { defineServer, defineRoom, LobbyRoom } from "colyseus";
 
const server = defineServer({
  rooms: {
    lobby: defineRoom(LobbyRoom)
  }
})

Enable realtime listing on your game room

When realtime listing is enabled, the LobbyRoom is notified automatically during onCreate(), onJoin(), onLeave() and onDispose().

server.ts

import { defineServer, defineRoom, LobbyRoom } from "colyseus";
 
const server = defineServer({
  rooms: {
    lobby: defineRoom(LobbyRoom),
    my_room: defineRoom(MyRoom).enableRealtimeListing()
  }
})

Client

The LobbyRoom will send messages to the client whenever a room is added, removed or updated.

client.ts

import { Client, RoomAvailable } from "@colyseus/sdk";
 
const client = new Client("http://localhost:2567");
const lobby = await client.joinOrCreate("lobby");
 
let allRooms: RoomAvailable[] = [];
 
lobby.onMessage("rooms", (rooms) => {
  allRooms = rooms;
});
 
lobby.onMessage("+", ([roomId, room]) => {
  const roomIndex = allRooms.findIndex((room) => room.roomId === roomId);
  if (roomIndex !== -1) {
    allRooms[roomIndex] = room;
 
  } else {
    allRooms.push(room);
  }
});
 
lobby.onMessage("-", (roomId) => {
  allRooms = allRooms.filter((room) => room.roomId !== roomId);
});

client.ts

import * as Colyseus from "@colyseus/sdk";
 
const client = new Colyseus.Client("http://localhost:2567");
 
client.joinOrCreate("lobby").then(function(lobby) {
    let allRooms = [];
 
    lobby.onMessage("rooms", (rooms) => {
        allRooms = rooms;
    });
 
    lobby.onMessage("+", ([roomId, room]) => {
        const roomIndex = allRooms.findIndex((room) => room.roomId === roomId);
        if (roomIndex !== -1) {
            allRooms[roomIndex] = room;
 
        } else {
            allRooms.push(room);
        }
    });
 
    lobby.onMessage("-", (roomId) => {
        allRooms = allRooms.filter((room) => room.roomId !== roomId);
    });
});

LobbyClient.cs

using Colyseus;
 
Client client = new Client("http://localhost:2567");
Room lobbyRoom = await client.JoinOrCreate("lobby");
 
List<RoomAvailable> allRooms = new List<RoomAvailable>();
 
lobbyRoom.OnMessage("rooms", (RoomAvailable[] rooms) =>
{
  allRooms.Clear();
  allRooms.AddRange(rooms);
});
 
lobbyRoom.OnMessage("+", (object[] message) =>
{
  string roomId = (string)message[0];
  var room = (RoomAvailable)message[1];
  int roomIndex = allRooms.FindIndex((r) => r.roomId == roomId);
  if (roomIndex != -1) {
    allRooms[roomIndex] = room;
  } else {
    allRooms.Add(room);
  }
});
 
lobbyRoom.OnMessage("-", (string roomId) =>
{
  allRooms.RemoveAll((r) => r.roomId == roomId);
});

lobby.lua

local Colyseus = require("colyseus.sdk")
 
local client = Colyseus.Client("http://localhost:2567")
 
client:join_or_create("lobby", {}, function(err, lobby)
    if err ~= nil then
        print("join error: " .. err)
        return
    end
 
    local all_rooms = {}
 
    lobby:on_message("rooms", function(rooms)
        all_rooms = rooms
    end)
 
    lobby:on_message("+", function(message)
        local room_id = message[1]
        local room = message[2]
        local found = false
        for i, r in ipairs(all_rooms) do
            if r.roomId == room_id then
                all_rooms[i] = room
                found = true
                break
            end
        end
        if not found then
            table.insert(all_rooms, room)
        end
    end)
 
    lobby:on_message("-", function(room_id)
        for i, r in ipairs(all_rooms) do
            if r.roomId == room_id then
                table.remove(all_rooms, i)
                break
            end
        end
    end)
end)

Lobby.hx

import io.colyseus.Client;
import io.colyseus.Room;
 
var client = new Client("http://localhost:2567");
client.joinOrCreate("lobby", [], function(err, lobby: Room<Dynamic>) {
    if (err != null) {
        trace("[Lobby] error: " + err);
        return;
    }
 
    var allRooms:Array<Dynamic> = [];
 
    lobby.onMessage("rooms", (rooms: Array<Dynamic>) -> {
        allRooms = rooms;
    });
 
    lobby.onMessage("+", (message: Dynamic) -> {
        var roomId:String = message[0];
        var room:Dynamic = message[1];
        var found = false;
        for (i in 0...allRooms.length) {
            if (allRooms[i].roomId == roomId) {
                allRooms[i] = room;
                found = true;
                break;
            }
        }
        if (!found) {
            allRooms.push(room);
        }
    });
 
    lobby.onMessage("-", (roomId: String) -> {
        allRooms = allRooms.filter((room) -> room.roomId != roomId);
    });
});

Filtering rooms

Filter the listing by providing the filter option when joining the lobby. A filter must include name. The name check runs unconditionally, so a metadata-only filter matches nothing. Use metadata to narrow within a room name:

client.ts

const lobby = await client.joinOrCreate("lobby", {
  filter: {
    name: "my_room",
    metadata: {
      gameMode: "deathmatch",
    }
  }
});

Alternatively, you can also dynamically change the filter by sending a "filter" message to the lobby room:

lobby.send("filter", {
  name: "my_room",
  metadata: {
    gameMode: "deathmatch",
  }
});

Visibility & Access Queue Room