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
// 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:
-
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 tagsThe matchmaker would connect the player to any of the 3 lobbies.
-
A
lobbies.find
request with the tagsmap = sandstorm
The matchmaker would connect the player to either lobby 1 or lobby 2.
-
A
lobbies.find
request with the tagsmap = sandstorm
,worldId = 123abc
The matchmaker would only connect players to lobby 1.
-
A
lobbies.find
request with the tagsmap = 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 tagsmap = 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.