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.

rivet.yaml

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.

Request

POST

https://matchmaker.api.rivet.gg/v1/lobbies/find

// 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"
  }
});

Tags are immutable. After a lobby is created, its tags cannot be changed.

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:

Lobby 1
- worldId = 123abc
- map = sandstorm
Lobby 2
- worldId = foobar
- map = sandstorm
Lobby 3
- No tags

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

This example uses prevent_auto_create_lobby to demonstrate the errors returned. If auto creating lobbies is enabled, cases 4 and 5 would create a new lobby with the given tags and cases 1-3 would create a new lobby with the given tags only if all available servers are full.

A lobbies.find request with no tags

The matchmaker would connect the player to any of the 3 lobbies.
A lobbies.find request with the tags map = sandstorm

The matchmaker would connect the player to either lobby 1 or lobby 2.
A lobbies.find request with the tags map = sandstorm, worldId = 123abc

The matchmaker would only connect players to lobby 1.
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.
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.