Colyseus: Proposal: Public Room API

[endel]

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

[talothman]

Region a consideration at all? Information on where the Server the Room is hosted in could be helpful. Not sure if variables like that are exposed to the Room though.

[TinyDobbins]

to adding the RoomAPI - definitely good idea.
no need to worry about the number of available rooms - usually that depends on the server configuration.
for example in gunfight game 50 rooms (10 players per room) per server. if to allow to create more - server can't take and will slow down all processes. summary: the number of rooms - constant.

on client side - I show only no full rooms and where time of round is okay to connecting. for example if you gameplay is a battle 3minutes, no point in connecting when there is only 10-15 seconds before the end of round. and etc. summary: need to do filter on client side depends on type of the game.

about the 3rd item, no need to do that in real-time, enought to do it via calling the command.

I think that good idea to develop RoomAPI via http request, because via router easy to do a lot of usefull commands such as:
1) ping - server
2) countOfRooms
3) listOfRooms
4) checkRoom (if exists and no full)

[oyed]

@talothman You could add this yourself in the metadata, though as you have to be connected to a Server to request the Rooms via the API, I'd assume the client has already chosen a region-based server.

[talothman]

@oyed, good point. adding location as possibly something the client could request initially and have the server handle could be helpful in giving the client more space to decide what region they want to be hosted on. kinda like the region filter in Rocket League.

[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.

[talothman]

Thanks for clarifying. Good points.

[endel]

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