Lobby tags

Lobby tags are an optional property that can be passed to the lobbies.find and lobbies.create endpoints to allow filtering which lobbies the matchmaker will route a player to.

To enable tags, set taggable to true.

matchmaker:
  game_modes:
    default:
      taggable: true

When passed to lobbies.create, the newly created lobby will have the given tags. When passed to lobbies.find, the matchmaker will attempt to return a lobby with a superset of the given tags. If no lobby is found, a new lobby is created with the given tags.

// Create Rivet client
import { RivetClient } from '@rivet-gg/api';
const RIVET = new RivetClient({ token: addYourTokenHere });

// Make request
await RIVET.matchmaker.lobbies.find({
  gameMode: 'default',
  tags: {
    map: "sandstorm",
    difficulty: "hard"
  }
});

Example

When passed to lobbies.find the matchmaker will only return lobbies that have a superset of the given tags.

Imagine this scenario where two lobbies were created with the tags and one without:

1. Lobby 1

   • worldId = 123abc
   • map = sandstorm

2. Lobby 2

   • worldId = foobar
   • map = sandstorm

3. Lobby 3

   • No tags

Here is what would happen with the following lobbies.find requests:

1. A lobbies.find request with no tags

   The matchmaker would connect the player to any of the 3 lobbies.

2. A lobbies.find request with the tags map = sandstorm

   The matchmaker would connect the player to either lobby 1 or lobby 2.

3. A lobbies.find request with the tags map = sandstorm, worldId = 123abc

   The matchmaker would only connect players to lobby 1.

4. A lobbies.find request with the tags map = sandstorm, worldId = foobar, difficulty = hard

   The matchmaker would error because there are no lobbies with the given tags. Note that there is a lobby with two of the requested tags, but it contains a subset of the tags in the request, not a superset.

5. A lobbies.find request with the tags map = tropic

   The matchmaker would error because there are no lobbies with the given tags.

Authentication

It can be useful to allow/disallow certain tags from being used when creating or finding lobbies. This can be done via custom external verification.