How the matchmaker chooses lobbies

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


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

Competitive matchmaking

If you’re looking to build competitive matchmaking on top of Rivet, please read this first.

Determining the region

If no region is specificed in Lobbies.find, Rivet 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, Rivet Matchmaker will filter out full lobbies and then find the fullest lobby (i.e. least available spots).

This simplified exampe demonstrates how the matchmaker finds the correct lobby to join:

Providing multiple game modes

Lobbies.find allows the developer to provide multiple game modes to join. In this case, Rivet Matchmaker 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, Rivet Matchmaker 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, Lobbies.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.

Also see idle lobbies.

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

Rivet Matchmaker 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 Lobbies.find again, the players will be compacted in fewer, fuller lobbies.