Proposal: Public Room API

I’d like to discuss the API for listing and exposing rooms for the client-side.

Scenario

The user would like to manually select a room he’d like to join, based on the currently available list of rooms.

Current state of the framework:

• The server will select a room automatically for the user (via requestJoin()). The user can’t manually select between 3 available rooms, for example.
• The user can join a room by its id. But the framework doesn’t provide a built-in way to list room ids.

Proposal

Allowing to set metadata in the rooms (server-side), and querying available rooms on the client-side.

Public Room Stats

The room stats is a limited information about the spawned room. At first, I think these are the most important information to be public.

• id (the id of the room)
• clients (number of clients connected)
• maxClients (maximum number of clients allowed in that room instance)
• metadata (custom data, manually set for each room instance)

Setting the Room’s metadata:

// BattleRoom.ts
//...
  onInit (options) {
    this.setMetadata({
      image: "something.png"
    });
  }
//...

Requesting Room’s Stats

In the client-side, the developer could make a request to receive all available (unlocked) room’s stats via:

const client = new Colyseus.Client("ws://...");

client.getAvailableRooms("battle", (rooms, err) => {
  if (err) throw new Error(err);
  rooms.forEach((room) => {
    room.id // => "rye7lcbyFf"
    room.clients // => 1
    room.maxClients // => 10
    room.meta // => { "image": "something.png" }
  });
});

Considerations:

• The number of available rooms may be too long. It may be necessary to consider a search API for rooms based on some criteria (number of clients, metadata values, etc)
• The room id requested may not exist anymore when the user finally tries to connect to it.
• Real-time updates regarding room’s stats aren’t available this way.

Feedback

Sorry for the long post, if you’ve made it until here, your feedback is very welcome! 🚀 🚀 /cc @msholty-fd @JoaoMosmann @gregmax17 @takaaptech @AnubisCode

[endel]

Implemented on https://github.com/gamestdio/colyseus/pull/135 🎉

[oyed]

@talothman This is definitely something you should do yourself, Colyseus is per-server and as such per-region, you should build your own API (Or hardcode server options in your client, though API is a better option) that will return all of the available servers (A.K.A. Regions/Colyseus Instances) that the client can connect to. After that, it is simply just connecting and using the Rooms API.