API Bad Query Parameter

Matchmaker

Serverless Lobbies

Identity

Cloud

Rivet

Overview

Sign Up for Beta

Discord

Dashboard

Introduction

The GUI, CLI, and API

Libraries

⏱️ 5 Minute Crash Course

Tanks (TypeScript + Canvas + Socket.io)

Third-Person Template (Unreal Engine)

2D Bomber (Godot)

Handling game tokens

Development tokens

Tokenless player authentication for web

Types of tokens

Authoritative vs peer-to-peer networking

Who is Rivet buit for?

Who is Rivet not built for?

Missing Entitlement

Entitlement Expired

NSFW Content Detected in Upload

Validation Error

UUID Invalid

CDN Too Many Auth Users

Game User Link Failed

API Bad Header

API Unauthorized

API Bad Body

API Missing Header

API Bad Query

API Invalid IP

API Bad Headers

API Forbidden

API Bad Content Length

API Not Found

API Rate Limit

API Bad Cookie

API Missing Cookie

Game Mode Not Found

Matchmaker Lobby Stopped

Matchmaker Lobby Not Found

Matchmaker Player Already Connected

Matchmaker Too Many Lobbies

Matchmaker Player In Different Lobby

Matchmaker Player Removed

Matchmaker Lobby Closed

MATCHMAKER_REGION_NOT_ENABLED_FOR_GAME_MODE

Matchmaker Region Not Enabled

Matchmaker Too Many Players From Source

Matchmaker Lobby Not Started

Matchmaker Lobby Full

Matchmaker Player Registration Expired

Matchmaker No Available Lobbies

Device Link Already Complete

Hostname Taken

CLOUD_TOO_MANY_PENDING_HOSTNAMES_FOR_GROUP

Too Many Pending Hostnames

CDN Too Many Domains

CDN Invalid Auth User Password

CDN Invalid Domain

Captcha Origin Not Allowed

Captcha Failed

Captcha Invalid

Captcha Required

Game Not Found

Group Join Request Already Exists

Group Full

Group Member Banned

Group Not Developer Group

Group Invalid Developer Status

Failed to consume group invite

Group Not Joinable

Group Not Member

Group Insufficient Permissions

Group Not Found

Group Already Member

Group cannot request join

Party Full

Party Not Found

Cannot Set Party Leader To Self

Cannot Kick Self

Unexpected Invite Alias

Already In Party

Party Not in Game

Identity Not Party Leader

Invite Not Found

Invite Alias Not Unique

Bad Invite Alias Length

Leader Not In Same Party

Too Many Invites

Invite Alias Not Found

Party Not Joinable

Bad Party Size

Identity Not In Any Party

Invalid Chat Topic

Chat Thread Not Found

Invalid Chat Body

Identity Not Registered

Identity Not Found

Identity Not Admin

Wrong Identity

KV Value Too Long

KV Entries Missing

KV Batch Too Large

KV Key Validation Error

KV Keys Missing

Token Revoked

Token Exchange Failed

Generic Token Error

Token Expired

Refresh Token Not Found

Token Invalid

Flexible matchmaker for placing players in lobbies with no wait times.

How the matchmaker chooses lobbies

Lobby environment variables

Automatic region selection

Competitive matchmaking

Finds a lobby based on the given criteria.
If a lobby is not found and `prevent_auto_create_lobby` is `true`, 
a new lobby will be created.


⭐️ matchmaker.lobbies.find

Joins a specific lobby.
This request will use the direct player count configured for the
lobby group.


⭐️ matchmaker.lobbies.join

Marks the current lobby as ready to accept connections.  Players will not be able to connect to this lobby until the  lobby is flagged as ready.

⭐️ matchmaker.lobbies.ready

Validates the player token is valid and has not already been consumed then
marks the player as connected.
# Player Tokens and Reserved Slots
Player tokens reserve a spot in the lobby until they expire. This allows for
precise matchmaking up to exactly the lobby's player limit, which is
important for games with small lobbies and a high influx of players.
By calling this endpoint with the player token, the player's spot is marked
as connected and will not expire. If this endpoint is never called, the
player's token will expire and this spot will be filled by another player.
# Anti-Botting
Player tokens are only issued by caling `lobbies.join`, calling `lobbies.find`, or
from the `GlobalEventMatchmakerLobbyJoin` event.
These endpoints have anti-botting measures (i.e. enforcing max player
limits, captchas, and detecting bots), so valid player tokens provide some
confidence that the player is not a bot.
Therefore, it's important to make sure the token is valid by waiting for
this endpoint to return OK before allowing the connected socket to do
anything else. If this endpoint returns an error, the socket should be
disconnected immediately.
# How to Transmit the Player Token
The client is responsible for acquiring the player token by caling
`lobbies.join`, calling `lobbies.find`, or from the `GlobalEventMatchmakerLobbyJoin`
event.  Beyond that, it's up to the developer how the player token is
transmitted to the lobby.
If using WebSockets, the player token can be transmitted as a query
parameter.
Otherwise, the player token will likely be automatically sent by the client
once the socket opens. As mentioned above, nothing else should happen until
the player token is validated.


⭐️ matchmaker.players.connected

Marks a player as disconnected. # Ghost Players If players are not marked as disconnected, lobbies will result with "ghost players" that the matchmaker thinks exist but are no longer connected to the lobby.

⭐️ matchmaker.players.disconnected

If `is_closed` is `true`, players will be prevented from joining the lobby.
Does not shutdown the lobby.


matchmaker.lobbies.setClosed

matchmaker.lobbies.list

Gives matchmaker statistics about the players in game.

matchmaker.players.getStatistics

Returns a list of regions available to this namespace.
Regions are sorted by most optimal to least optimal. The player's IP address
is used to calculate the regions' optimality.


matchmaker.regions.list

Auto-scaling game lobbies boot up to meet demand.

Rivet Game Guard

Supported protocols

Ports

Available regions

Available tiers

Versioned CDN lets you host assets and webpages with a provided or custom domain and managed SSL.

Allow identities to authenticate and play with friends across multiple games.

Following & friend mechanics

Friend discovery mechanisms

Returns all events relative to the current identity.

⭐️ identity.events.watch

Begins the process for linking an identity with the Rivet Hub.
# Importance of Linking Identities
When an identity is created via `rivet.api.identity#SetupIdentity`, the identity is temporary
and is not shared with other games the user plays.
In order to make the identity permanent and synchronize the identity with
other games, the identity must be linked with the hub.
# Linking Process
The linking process works by opening `identity_link_url` in a browser then polling
`rivet.api.identity#GetGameLink` to wait for it to complete.
This is designed to be as flexible as possible so `identity_link_url` can be opened
on any device. For example, when playing a console game, the user can scan a
QR code for `identity_link_url` to authenticate on their phone.


⭐️ identity.links.prepare

Gets or creates an identity.
Passing an existing identity token in the body refreshes the token.
Temporary Accounts
Until the identity is linked with the Rivet Hub (see `PrepareGameLink`), this identity will be temporary but still behave like all other identities.
This is intended to allow users to play the game without signing up while still having the benefits of having an account. When they are ready to save their account, they should be instructed to link their account (see `PrepareGameLink`).
Storing Token
`identity_token` should be stored in some form of persistent storage. The token should be read from storage and passed to `Setup` every time the client starts.

⭐️ identity.setup

Returns the current status of a linking process. Once `status` is `complete`, the identity's profile should be fetched again since they may have switched accounts.

identity.links.get

group.listSuggested

group.create

Prepares an avatar image upload.
Complete upload with `rivet.api.group#CompleteAvatarUpload`.

group.prepareAvatarUpload

Validate contents of group profile. Use to provide immediate feedback on profile changes before committing them.

group.validateProfile

group.search

Completes an avatar image upload. Must be called after the file upload
process completes.
Call `rivet.api.group#PrepareAvatarUpload` first.

group.completeAvatarUpload

Returns a group's bans. Must have valid permissions to view.

group.getBans

Unbans an identity from a group. Must be the owner of the group to perform this action.

group.unbanIdentity

Bans an identity from a group. Must be the owner of the group to perform this action. The banned identity will no longer be able to create a join request or use a group invite.

group.banIdentity

Creates a group invite. Can be shared with other identities to let them join this group.

group.invites.createInvite

Resolves a join request for a given group.

group.joinRequests.resolveJoinRequest

Returns a group's join requests. Must have valid permissions to view.

group.getJoinRequests

Kicks an identity from a group. Must be the owner of the group to perform this action.

group.kickMember

group.leave

group.getMembers

group.getProfile

group.updateProfile

group.getSummary

Transfers ownership of a group to another identity.

group.transferOwnership

Prepares an avatar image upload. Complete upload with `CompleteIdentityAvatarUpload`.

identity.prepareAvatarUpload

Completes an avatar image upload. Must be called after the file upload process completes.

identity.completeAvatarUpload

identity.getHandles

identity.getSummaries

identity.updateStatus

identity.search

Removes the current identity's game activity.

identity.removeGameActivity

Sets the current identity's game activity. This activity will automatically be removed when the identity goes offline.

identity.setGameActivity

identity.signupForBeta

Overview

Guides

Concepts

FAQ

Errors

API Bad Query Parameter