rivet.yaml Specification
Naming
Workflow files must be name rivet.yaml
, rivet.toml
, or rivet.json
. We recommend using YAML for your configuration since it is easiest to read/write and provides validation & suggestions through our schema.
Namespacing
Rivet configs can override properties by naming them rivet.{namespace}.yaml
. For example, you can configure your generic config in rivet.yaml
and override the properties for production in rivet.prod.yaml
.
scripts
union of empty object and stringengine
objectengine.unity
empty objectengine.unreal
objectengine.unreal.game_module
stringName of the Unreal module that holds the game code. This is usually the value of
$.Modules[0].Name
in the fileMyProject.unproject
. Configures Rivet CLI behavior. Has no effect on server behavior.
engine.godot
empty objectengine.html5
empty objectengine.custom
empty object
cdn
objectCDN configuration for a given version.
cdn.build_command
stringConfigures Rivet CLI behavior. Has no effect on server behavior.
cdn.build_output
stringConfigures Rivet CLI behavior. Has no effect on server behavior.
cdn.build_env
union of empty object and stringConfigures Rivet CLI behavior. Has no effect on server behavior.
cdn.site_id
stringcdn.routes
array of objectsMultiple CDN version routes.
cdn.routes.glob
stringcdn.routes.priority
numberUnsigned 32 bit integer.
cdn.routes.middlewares
array of objectsMultiple CDN version middleware.
cdn.routes.middlewares.kind
objectcdn.routes.middlewares.kind.custom_headers
objectcdn.routes.middlewares.kind.custom_headers.headers
array of objectscdn.routes.middlewares.kind.custom_headers.headers.name
stringcdn.routes.middlewares.kind.custom_headers.headers.value
string
matchmaker
objectMatchmaker configuration for a given version.
matchmaker.game_modes
union of empty object and objectA list of game modes.
matchmaker.game_modes.regions
union of empty object and objectmatchmaker.game_modes.regions.tier
stringmatchmaker.game_modes.regions.idle_lobbies
objectConfiguration for how many idle lobbies a game version should have.
matchmaker.game_modes.regions.idle_lobbies.min
numbermatchmaker.game_modes.regions.idle_lobbies.max
number
matchmaker.game_modes.max_players
numbermatchmaker.game_modes.max_players_direct
numbermatchmaker.game_modes.max_players_party
numbermatchmaker.game_modes.docker
objectA game mode runtime running through Docker.
matchmaker.game_modes.docker.dockerfile
stringConfigures Rivet CLI behavior. Has no effect on server behavior.
matchmaker.game_modes.docker.build_args
union of empty object and stringConfigures Rivet CLI behavior. Has no effect on server behavior.
matchmaker.game_modes.docker.image
stringConfigures Rivet CLI behavior. Has no effect on server behavior.
matchmaker.game_modes.docker.image_id
stringmatchmaker.game_modes.docker.args
array of stringsmatchmaker.game_modes.docker.env
union of empty object and stringmatchmaker.game_modes.docker.network_mode
stringConfigures how the container's network is isolated from the host.
bridge
(default) networking isolates the container's network from the host & other containers.host
networking removes isolation between the container and the host. Only available in Rivet Open Source & Enterprise. Read more about bridge vs host networking here.matchmaker.game_modes.docker.ports
union of empty object and objectmatchmaker.game_modes.docker.ports.port
numberThe port number to connect to.
Related - cloud.version.matchmaker.PortProtocol - cloud.version.matchmaker.ProxyKind
matchmaker.game_modes.docker.ports.port_range
objectRange of ports that can be connected to. If configured,
network_mode
must equalhost
. Port ranges may overlap between containers, it is the responsibility of the developer to ensure ports are available before using. Read more about host networking here. Only available on Rivet Open Source & Enterprise.Related
- cloud.version.matchmaker.PortProtocol
- cloud.version.matchmaker.ProxyKind
matchmaker.game_modes.docker.ports.port_range.min
numberUnsigned 32 bit integer.
matchmaker.game_modes.docker.ports.port_range.max
numberUnsigned 32 bit integer.
matchmaker.game_modes.docker.ports.protocol
stringSignifies the protocol of the port. Note that when proxying through GameGuard (via
ProxyKind
), the port number returned by/find
,/join
, and/create
will not be the same as the port number configured in the config:- With HTTP, the port will always be 80. The hostname of the port correctly routes the incoming connection to the correct port being used by the game server.
- With HTTPS, the port will always be 443. The hostname of the port correctly routes the incoming connection to the correct port being used by the game server.
- Using TCP/UDP, the port will be a random number between 26000 and 31999. This gets automatically routed to the correct port being used by the game server.
Related - cloud.version.matchmaker.GameModeRuntimeDockerPort - cloud.version.matchmaker.ProxyKind - /docs/dynamic-servers/concepts/game-guard - matchmaker.lobbies.find
matchmaker.game_modes.docker.ports.proxy
stringHow this port should be proxied. Defaults to 'game-guard`.
matchmaker.game_modes.docker.ports.dev_port
numberConfigures Rivet CLI behavior. Has no effect on server behavior.
matchmaker.game_modes.docker.ports.dev_port_range
objectConfigures Rivet CLI behavior. Has no effect on server behavior.
matchmaker.game_modes.docker.ports.dev_port_range.min
numberUnsigned 32 bit integer.
matchmaker.game_modes.docker.ports.dev_port_range.max
numberUnsigned 32 bit integer.
matchmaker.game_modes.docker.ports.dev_protocol
stringConfigures Rivet CLI behavior. Has no effect on server behavior.
matchmaker.game_modes.listable
booleanmatchmaker.game_modes.taggable
booleanmatchmaker.game_modes.allow_dynamic_max_players
booleanmatchmaker.game_modes.actions
objectConfiguration for the connection types allowed for a game mode.
matchmaker.game_modes.actions.find
objectConfigures the requirements and authentication for the /find endpoint. If this value is not set in the config, the /find endpoint is still enabled.
matchmaker.game_modes.actions.find.enabled
booleanSets whether or not the /find endpoint is enabled.
matchmaker.game_modes.actions.find.identity_requirement
any valuematchmaker.game_modes.actions.find.verification
objectConfiguration that tells Rivet where to send validation requests and with what headers. When set, Rivet will send the
verification_data
property (given by the user in the find/join/create endpoint) to the given url along with the headers provided and some information about the requested lobby. The response of this request will determine if the user can join that lobby or not.matchmaker.game_modes.actions.find.verification.url
stringmatchmaker.game_modes.actions.find.verification.headers
union of empty object and string
matchmaker.game_modes.actions.join
objectConfigures the requirements and authentication for the /join endpoint. If this value is not set in the config, the /join endpoint is still enabled.
matchmaker.game_modes.actions.join.enabled
booleanSets whether or not the /join endpoint is enabled.
matchmaker.game_modes.actions.join.identity_requirement
any valuematchmaker.game_modes.actions.join.verification
objectConfiguration that tells Rivet where to send validation requests and with what headers. When set, Rivet will send the
verification_data
property (given by the user in the find/join/create endpoint) to the given url along with the headers provided and some information about the requested lobby. The response of this request will determine if the user can join that lobby or not.matchmaker.game_modes.actions.join.verification.url
stringmatchmaker.game_modes.actions.join.verification.headers
union of empty object and string
matchmaker.game_modes.actions.create
objectConfigures the requirements and authentication for the /create endpoint. If this value is not set in the config, the /create endpoint is NOT enabled.
matchmaker.game_modes.actions.create.enabled
booleanSets whether or not the /create endpoint is enabled.
matchmaker.game_modes.actions.create.identity_requirement
any valuematchmaker.game_modes.actions.create.verification
objectConfiguration that tells Rivet where to send validation requests and with what headers. When set, Rivet will send the
verification_data
property (given by the user in the find/join/create endpoint) to the given url along with the headers provided and some information about the requested lobby. The response of this request will determine if the user can join that lobby or not.matchmaker.game_modes.actions.create.verification.url
stringmatchmaker.game_modes.actions.create.verification.headers
union of empty object and string
matchmaker.game_modes.actions.create.enable_public
booleanDefaults to false when unset.
matchmaker.game_modes.actions.create.enable_private
booleanDefaults to true when unset.
matchmaker.game_modes.actions.create.max_lobbies_per_identity
any value
matchmaker.game_modes.tier
stringmatchmaker.game_modes.idle_lobbies
objectConfiguration for how many idle lobbies a game version should have.
matchmaker.game_modes.idle_lobbies.min
numbermatchmaker.game_modes.idle_lobbies.max
number
matchmaker.captcha
objectMatchmaker captcha configuration.
matchmaker.captcha.requests_before_reverify
numberDenotes how many requests a connection can make before it is required to reverify a captcha.
matchmaker.captcha.verification_ttl
numberDenotes how long a connection can continue to reconnect without having to reverify a captcha (in milliseconds).
matchmaker.captcha.hcaptcha
objecthCpatcha configuration.
matchmaker.captcha.hcaptcha.level
any valuematchmaker.captcha.hcaptcha.site_key
stringSite key for your hCaptcha application. Must be set.
matchmaker.captcha.hcaptcha.secret_key
stringSecret key for your hCaptcha application. Must be set.
matchmaker.captcha.turnstile
objectTurnstile captcha configuration.
matchmaker.captcha.turnstile.site_key
stringmatchmaker.captcha.turnstile.secret_key
string
matchmaker.dev_hostname
stringConfigures Rivet CLI behavior. Has no effect on server behavior.
matchmaker.regions
union of empty object and objectmatchmaker.regions.tier
stringmatchmaker.regions.idle_lobbies
objectConfiguration for how many idle lobbies a game version should have.
matchmaker.regions.idle_lobbies.min
numbermatchmaker.regions.idle_lobbies.max
number
matchmaker.max_players
numbermatchmaker.max_players_direct
numbermatchmaker.max_players_party
numbermatchmaker.docker
objectA game mode runtime running through Docker.
matchmaker.docker.dockerfile
stringConfigures Rivet CLI behavior. Has no effect on server behavior.
matchmaker.docker.build_args
union of empty object and stringConfigures Rivet CLI behavior. Has no effect on server behavior.
matchmaker.docker.image
stringConfigures Rivet CLI behavior. Has no effect on server behavior.
matchmaker.docker.image_id
stringmatchmaker.docker.args
array of stringsmatchmaker.docker.env
union of empty object and stringmatchmaker.docker.network_mode
stringConfigures how the container's network is isolated from the host.
bridge
(default) networking isolates the container's network from the host & other containers.host
networking removes isolation between the container and the host. Only available in Rivet Open Source & Enterprise. Read more about bridge vs host networking here.matchmaker.docker.ports
union of empty object and objectmatchmaker.docker.ports.port
numberThe port number to connect to.
Related - cloud.version.matchmaker.PortProtocol - cloud.version.matchmaker.ProxyKind
matchmaker.docker.ports.port_range
objectRange of ports that can be connected to. If configured,
network_mode
must equalhost
. Port ranges may overlap between containers, it is the responsibility of the developer to ensure ports are available before using. Read more about host networking here. Only available on Rivet Open Source & Enterprise.Related
- cloud.version.matchmaker.PortProtocol
- cloud.version.matchmaker.ProxyKind
matchmaker.docker.ports.port_range.min
numberUnsigned 32 bit integer.
matchmaker.docker.ports.port_range.max
numberUnsigned 32 bit integer.
matchmaker.docker.ports.protocol
stringSignifies the protocol of the port. Note that when proxying through GameGuard (via
ProxyKind
), the port number returned by/find
,/join
, and/create
will not be the same as the port number configured in the config:- With HTTP, the port will always be 80. The hostname of the port correctly routes the incoming connection to the correct port being used by the game server.
- With HTTPS, the port will always be 443. The hostname of the port correctly routes the incoming connection to the correct port being used by the game server.
- Using TCP/UDP, the port will be a random number between 26000 and 31999. This gets automatically routed to the correct port being used by the game server.
Related - cloud.version.matchmaker.GameModeRuntimeDockerPort - cloud.version.matchmaker.ProxyKind - /docs/dynamic-servers/concepts/game-guard - matchmaker.lobbies.find
matchmaker.docker.ports.proxy
stringHow this port should be proxied. Defaults to 'game-guard`.
matchmaker.docker.ports.dev_port
numberConfigures Rivet CLI behavior. Has no effect on server behavior.
matchmaker.docker.ports.dev_port_range
objectConfigures Rivet CLI behavior. Has no effect on server behavior.
matchmaker.docker.ports.dev_port_range.min
numberUnsigned 32 bit integer.
matchmaker.docker.ports.dev_port_range.max
numberUnsigned 32 bit integer.
matchmaker.docker.ports.dev_protocol
stringConfigures Rivet CLI behavior. Has no effect on server behavior.
matchmaker.tier
stringmatchmaker.idle_lobbies
objectConfiguration for how many idle lobbies a game version should have.
matchmaker.idle_lobbies.min
numbermatchmaker.idle_lobbies.max
number
matchmaker.lobby_groups
any value
kv
empty objectKV configuration for a given version.
identity
any value