Custom games
The Rivet matchmaker allows for the creation of lobbies on demand via the
lobbies.create endpoint. This guide will discuss in detail all of
the configurations available with custom lobbies.
Creation
To create custom lobbies, you must first enable them in your version config:
rivet.yaml
# ...
matchmaker:
game_modes:
default:
actions:
create:
enabled: true
# Public custom lobbies will be listed in the response to `lobbies.list`, private custom
# lobbies will not
enable_public: true # Optional
enable_private: true # Optional
max_lobbies_per_identity: 5 # Optional
Now users can create a new custom lobby on-demand like so:
Request
curl
-X POST \
-H "Content-Type: application/json" \
-d "{ \"game_mode\": \"default\", \"region\": \"atl\", \"publicity\": \"private\" }" \
'https://matchmaker.api.rivet.gg/v1/lobbies/create'
Make sure you enable the publicity you intend to use in your
lobbies.create request by setting enable_public and/or
enable_private to true. If it is not enabled, you will receive a MATCHMAKER_CUSTOM_LOBBY_CONFIG_INVALID error
from the API call.
Customization
Additionally, users can input any arbitrary JSON to the
lobbies.create endpoint and have it be sent directly to the new
custom lobby that will be created. This allows users to customize game properties to their liking.
Request
curl
-X POST \
-H "Content-Type: application/json" \
-d "{ \"game_mode\": \"default\", \"publicity\": \"private\", \"lobby_config\": { \"roundDuration\": 120, \"gravity\": 4.6, \"coinsPerKill\": 100 } }" \
'https://matchmaker.api.rivet.gg/v1/lobbies/create'
For more info on verifying custom game config, see here.
Here's an example of how you might use the user's lobby config:
Game server
// Create Rivet client
import { RivetClient } from '@rivet-gg/api';
const RIVET = new RivetClient({ token: process.env.RIVET_TOKEN });
await RIVET.matchmaker.lobbies.ready({});
// Parse config
let config: any;
try {
config = JSON.parse(process.env.RIVET_LOBBY_CONFIG);
} catch(e) {
console.error("Invalid lobby config: ", e);
process.exit(1);
}
let roundDuration = config.roundDuration ?? 240;
let gravity = config.gravity ?? 9.8;
let coinsPerKill = config.coinsPerKill ?? 50;
// ...