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 name and metadata.

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 Colyseus from "@colyseus/sdk";
 
const client = new Colyseus.Client("http://localhost:2567");
 
client.joinOrCreate("lobby").then(function(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);
    });
});

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

Filtering rooms by name or metadata can be done by providing the filter option when joining the lobby:

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",
  }
});

Built-In Rooms Queue Room