Installation
Run the following command in your project directory:
opengb module add lobbies
Status
Stable
License
Apache 2.0
Database
No Database
Actors
1 actor
The lobbies module is a casual matchmaker optimized to get your player connected to your game server in under a second in the optimal region & lobby. Supports multiple backends, including:
  • Rivet Dynamic Servers
  • Local Development

​
Getting started

​
Integration

To integrate your servers to the Lobbies system, you need to call these three scripts in your server code.
  • set_lobby_ready: Notifies the lobbies system that the server is ready to accept players
  • set_player_connected: Notifies the lobbies system of a player connection while confirming the connection’s legitimacy
  • set_player_disconnected: Notifies the lobbies system of a player disconnection
And don’t worry about notifying the lobbies system if your lobby closes or crashes, that gets taken internally by the Dynamic Server system. Although if you want to manually tell the lobbies system to stop letting in new players, you can call the lobbies.setClosed endpoint.

​
Connecting to lobbies

Once integrated, you can call the following scripts to find and join available lobbies in your client code.
  • find: Finds an available lobby and grants a player token to connect
  • join: Given a lobby’s id, grants a player token to be used for connection
If you want the client to be able to create a whole new lobby (for things like private games), you can also use the create script.

​
Getting other lobby info

Additionally, you can make use of these scripts to get more information about your game’s lobbies.
  • list_regions: Returns listing of all regions available in game
  • list: Returns listing of all the lobbies linked to the lobbies system
  • lobbies.players.getStatistics: Returns player count statistics by region and game mode
The Lobbies system is tightly integrated with Dynamic Servers to automatically boot lobbies on-demand when players need them. Read more about how Dynamic Servers operates your game servers here.

​
How the matchmaker chooses lobbies

This document explains the logic going on behind the scenes when a game calls find.

​
TL;DR

Lobbies will return the lobby in the closest region with the least spots available (i.e. max players - current players).

​
Determining the region

If no region is specified in find, OpenGB will use the GeoIP location provided by Cloudflare to find the nearest datacenter. GeoIP does not always provide the most optimal route to the datacenter, so we recommend providing the user with the ability to select their own region.

​
Determining the lobby

Once the region has been determined, Lobbies will filter out full lobbies and then find the fullest lobby (i.e. least available spots).

​
Providing multiple game modes

find allows the developer to provide multiple game modes to join. In this case, Lobbies will select the optimal lobby from all of the provided game modes. This can be helpful for games with low traffic but still want to provide multiple game modes to their users. In this situation, new players will be connected to any lobby for any game mode with players in it.

​
Full lobbies & no lobbies running

When all of the lobbies are full or there are no lobbies running, Lobbies will automatically create a new lobby for the game mode specified and connect the player to that lobby. If this is not the desired behavior, find can be called with prevent_auto_create_lobby as true. This will return a MATCHMAKER_NO_AVAILABLE_LOBBIES error when no lobby can accept players.

​
Making games feel full in off hours

​
The problem

Player counts in a given region usually fluxuate by at least 50% ever day during off hours. Games often feel more empty than they actually are as players are leaving the game because there are more lobbies with less players spread evenly across them. For example:
  • 9 AM: There are 3 empty lobbies and 15 players online. Now there are 5 players in each lobby.
  • 2 PM: Now there are 25 players online, so 2 more lobbies are booted bringing us to 5 lobbies. Now there are 5 players in each lobby.
  • 10 PM: Players are going to bed, so there are 10 players online with 5 lobbies. Now there are 2 players in each lobby.
Even though there are twice as many players online at 10 PM as there were at 9 AM, there are less players in each lobby.

​
How the matchmaker deals with this

Lobbies is designed to mitigate this issue by prioritizing filling a few lobbies instead of spreading players across all lobbies. Take our example at 10 PM where there are 5 lobbies with 2 players in each lobby. If 2 new players come online, they will all be put in the same lobby, so one of the lobbies will have 4 players in it while the rest still have 2 players in them..

​
Auto-merging lobbies

In our example, we still have 4 lobbies with only 2 players online. We recommend prompting players to find a new lobby when the lobby is almost empty. By having the players in these empty lobbies call find_or_create again, the players will be compacted in fewer, fuller lobbies.

​
Automatic region selection

The OpenGB uses the client’s IP address to determine the closest region. This allows us to find the optimal lobby for the player and connect them to a lobby in under a second. If you want to implement your own region selection logic, use list_regions to list all enabled regions for your game.

​
Which GeoIP database does OpenGB use under the hood?

We use Cloudflare’s provided geolocation. There are a series of existing GeoIP databases with varying accuracy that we researched. However, we found that Cloudflare provides the most consistently accurate client location since they have more routing information than just the client’s IP to work with.

​
Environment Variables

The following environment variables are automatically set for each lobby:
  • LOBBY_ID A unique identifier for the lobby. This is a UUID string.
  • LOBBY_VERSION The version of the lobby, as specified in the lobby configuration.
  • LOBBY_TOKEN A secure token used for authenticating the lobby with the OpenGB backend.
  • BACKEND_ENDPOINT The public endpoint URL for the OpenGB backend.