Configuration
Config file resolving
All Mantle commands accept a PROJECT
argument which tells Mantle where to look for your config file.
Mantle uses the following rules to find your config file:
- If the
PROJECT
argument was not provided, use themantle.yml
file in the current directory as the config file (if it exists). - If the
PROJECT
argument was a directory, use themantle.yml
file in that directory as the config file (if it exists). - If the
PROJECT
argument was a file, use it as the config file (if it exists).
If no config file is found, Mantle will exit with an error code.
File path resolving
Many Mantle config properties require file paths or globs. All file paths should be written relative to the config file's directory.
For example, with the directory structure:
.
╰── project/
├── mantle.yml
├── game.rbxlx
╰── marketing/
├── game-icon.png
├── thumbnail-1.png
╰── thumbnail-2.png
You would use the config:
target:
experience:
configuration:
icon: marketing/game-icon.png
thumbnails:
- marketing/thumbnail-1.png
- marketing/thumbnail-2.png
places:
start:
file: game.rbxlx
Mantle will correctly find the referenced files no matter where you execute Mantle from.
YAML syntax
Mantle config files use YAML syntax, and should have either a .yml
or .yaml
file extension. To
quickly get started with the YAML syntax, see "Learn YAML in Y Minutes"
or read through the examples in this guide and in the Examples
repo.
Schema
You can view the JSON schema for the config file in the Releases
assets (only for versions above 0.11.0
). You can also use the schema to add autocomplete to your editor. For
VSCode, you can install the YAML extension
and add the following to your VSCode settings:
"yaml.schemas": {
"https://mantledeploy.vercel.app/schemas/v0.11.8/schema.json": "mantle.yml"
}
Now you should see autocomplete suggestions and documentation while editing your mantle.yml
config files.
Reference
owner
default: 'personal''personal' | object
The owner of the resources that will be created.
Value | Description |
---|---|
'personal' | All resources will be created in the authorizer user's account. |
group: <id> | All resources will be created in the specified group's account. |
owner: personal
owner:
group: 5723117
payments
default: 'owner''owner' | 'personal' | 'group'
Determines which account should make payments when creating resources
that cost Robux. Note that Mantle will never make purchases unless the
--allow-purchases
flag is enabled.
Value | Description |
---|---|
'owner' | All payments will come from the balance of the user or group specified by the owner property. |
'personal' | All payments will come from the balance of the authorized user. |
'group' | All payments will come from the balance of the group specified by the owner property. Payments can only be set to 'group' when the owner is also set to a group because Roblox does not currently allow groups to pay for resources outside of themselves. |
environments
required[object]
The list of environments which Mantle can deploy to.
environments:
- label: staging
branches: [dev, dev/*]
targetOverrides:
configuration:
icon: marketing/beta-game-icon.png
- label: production
branches: [main]
targetAccess: public
environments.*.label
requiredstring
The label of the environment that is used to identify the environment
via the --environment
flag. Must be unique across all environments.
environments.*.branches
[string]
An array of file globs to match against Git branches. If the
--environment
flag is not specified, Mantle will pick the first
environment which contains a matching file glob for the current Git
branch. If no environments match, Mantle will exit with a success code.
environments.*.tagCommit
boolean
Whether or not to tag the commit with place file versions after
successful deployments. It is recommended to only enable this on your
production environment. Tags will be of the format <label>-v<version>
where <label>
is the label of the place and <version>
is the place's
Roblox version.
For example, a start place with Roblox version 23 would have the tag
start-v23
.
environments.*.targetNamePrefix
'environmentLabel' | object
Adds a prefix to the target's name configuration. The implementation is dependent on the target's type. For Experience targets, all place names will be updated with the prefix.
Value | Description |
---|---|
'environmentLabel' | The target name prefix will use the format [<ENVIRONMENT>] where <ENVIRONMENT> is the value of the environment's label property in all caps. For example, if the environment's label was 'dev' and the target's name was "Made with Mantle", the resulting target name will be "[DEV] Made with Mantle". |
custom: <prefix> | The target name prefix will be the supplied value. |
environments:
- label: dev
targetNamePrefix: environmentLabel
- label: prod
environments:
- label: dev
targetNamePrefix:
custom: 'Prefix: '
- label: prod
environments.*.targetAccess
'public' | 'private' | 'friends'
Overrides the target's access. The implementation is dependent on the
target's type. For Experience targets, the
playability
property
will be overridden.
Value | Description |
---|---|
'public' | The target will be accessible to all Roblox users. |
'private' | The target will only be accessible to the authorized user. |
'friends' | The target will only be accessible to the authorized user and that user's Roblox friends. |
environments.*.targetOverrides
object
Environment-specific overrides for the target resource definition. This
will override all configuration, including changes made by the
targetNamePrefix
and
targetAccess
properties.
Override the target configuration. Should match the type of the target configuration.
target
requiredobject
Defines the target resource which Mantle will deploy to. Currently Mantle only supports targeting Experiences, but in the future it will support other types like Plugins and Models.
target:
experience: {}
target.experience
requiredobject
target.experience.configuration
object
The Experience's Roblox configuration.
target:
experience:
configuration:
genre: naval
playableDevices: [computer]
playability: private
privateServerPrice: 0
enableStudioAccessToApis: true
icon: marketing/game-icon.png
thumbnails:
- marketing/game-thumbnail-fall-update.png
- marketing/game-thumbnail-default.png
tip
In order to configure the name and description of an experience, use the
name
and
description
properties of the experience's start place
target.experience.configuration.genre
default: 'all''all' | 'adventure' | 'building' | 'comedy' | 'fighting' | 'fps' | 'horror' | 'medieval' | 'military' | 'naval' | 'rpg' | 'sciFi' | 'sports' | 'townAndCity' | 'western'
The experience's genre.
target.experience.configuration.playableDevices
default: ['computer', 'phone', 'tablet']['computer' | 'phone' | 'tablet' | 'console']
The devices that the experience can be played on.
target.experience.configuration.playability
default: 'private''public' | 'private' | 'friends'
Determines who has access to play the experience.
Value | Description |
---|---|
'public' | The experience will be playable by all Roblox users. |
'private' | The experience will only be playable by the authorized user. |
'friends' | The experience will only be playable to the authorized user and that user's Roblox friends. |
target.experience.configuration.paidAccess
default: 'disabled''disabled' | object
Determines whether or not paid access is be enabled, and if it is, how
much it costs. This should not be enabled when
privateServers
are
also enabled as they are incompatible.
Value | Description |
---|---|
'disabled' | Paid access will be disabled. |
price: <price> | Paid access will be enabled and will cost the provided number of Robux. Must be a minimum of 25. |
target:
experience:
configuration:
paidAccess:
price: 100
target.experience.configuration.privateServers
default: 'disabled''disabled' | 'free' | object
Determines whether or not private servers are enabled, and if they are,
how much they cost. This should not be enabled when
paidAccess
is also
enabled as they are incompatible.
Value | Description |
---|---|
'disabled' | Private servers will be disabled. |
'free' | Private servers will be enabled and will be free to purchase. |
price: <price> | Private servers will be enabled and will cost the provided number of Robux. |
target:
experience:
configuration:
privateServers: free
target:
experience:
configuration:
privateServers:
price: 100
target.experience.configuration.enableStudioAccessToApis
default: falseboolean
Whether or not studio should be able to use Roblox APIs for this place.
target.experience.configuration.allowThirdPartySales
default: falseboolean
Whether or not this experience should allow third-party sales.
target.experience.configuration.allowThirdPartyTeleports
default: falseboolean
Whether or not this experience should allow third-party teleports.
target.experience.configuration.avatarType
default: 'r15''r6' | 'r15' | 'playerChoice'
The types of avatars that players can use in this experience.
target.experience.configuration.avatarAnimationType
default: 'playerChoice''standard' | 'playerChoice'
The type of avatar animation that players can use in this experience.
target.experience.configuration.avatarCollisionType
default: 'outerBox''outerBox' | 'innerBox'
The type of avatar collision that players can use in this experience.
target.experience.configuration.avatarScaleConstraints
object
The scale constraints to apply to player avatars in the experience.
Defaults to Roblox's defaults. Each entry may include a min
, max
, or
both. If one is excluded, the default will be used.
Supported properties: bodyType
, head
, height
, proportions
,
width
.
target:
experience:
configuration:
avatarScaleConstraints:
height:
min: 0.95
width:
max: 0.9
proportions:
min: 30
max: 50
target.experience.configuration.avatarAssetOverrides
object
The asset overrides to apply to player avatars in the experience. Defaults to Roblox's defaults.
Supported properties: face
, head
, leftArm
, leftLeg
, rightArm
,
rightLeg
, torso
, tshirt
, shirt
, pants
target:
experience:
configuration:
avatarAssetOverrides:
face: 7699174
shirt: 5382048848
pants: 5611120855
target.experience.places
dictionary
The experience's places. There must be at least one place supplied with
the label 'start'
, which will be used as the start place for the
experience.
target:
experience:
places:
start:
file: game.rbxlx
configuration:
name: Pirate Wars!
description: |-
Duke it out on the high seas in your pirate ship!
🍂 Fall update: new cannons, new ship types!
maxPlayerCount: 10
serverFill: robloxOptimized
target.experience.places.<label>.file
string
A file path to a Roblox place (either .rbxl
or .rbxlx
).
target.experience.places.<label>.configuration
object
A place's Roblox configuration.
target.experience.places.<label>.configuration.name
default: 'Untitled Game'string
The display name of the place on the Roblox website and in-game. If the place is an experience's start place, it will be the experience's display name as well.
target.experience.places.<label>.configuration.description
default: 'Created with Mantle'string
The descirption of the place on the Roblox website and in-game. If the place is an experience's start place, it will be the experience's description as well.
target.experience.places.<label>.configuration.maxPlayerCount
default: 50uint32
The maximum number of players that can be in a server for the place.
target.experience.places.<label>.configuration.allowCopying
default: falseboolean
Whether or not other Roblox users can clone your place.
target.experience.places.<label>.configuration.serverFill
default: 'robloxOptimized''robloxOptimized' | 'maximum' | object
Determines how Roblox will fill your servers.
Value | Description |
---|---|
'robloxOptimized' | Roblox will attempt to automatically leave some space for friends to join. |
'maximum' | Roblox will never leave room for friends to join. |
reservedSlots: <count> | Roblox will always leave the provided number of slots available for friends to join. |
target:
experience:
places:
start:
file: game.rbxlx
configuration:
serverFill: maximum
target:
experience:
places:
start:
file: game.rbxlx
configuration:
serverFill:
reservedSlots: 5
target.experience.icon
string
A file path to an image that will be used as the experience's icon.
target.experience.thumbnails
[string]
An array of file paths to images that will be used as the experience's thumbnails. The order used here will be the order they appear on the Roblox webpage.
target.experience.socialLinks
[object]
A list of social links that will appear on the experience's webpage.
target:
experience:
socialLinks:
- title: Follow on Twitter
url: https://twitter.com/blakemdev
target.experience.socialLinks.*.title
requiredstring
The display name of the social link on the Roblox website.
target.experience.socialLinks.*.url
requiredstring
The URL of the social link. Must be one of the Roblox supported social link types.
target.experience.products
dictionary
Products that can be purchased within your experience for Robux.
target:
experience:
products:
fiftyGold:
name: 50 Gold
description: Add 50 gold to your wallet!
icon: products/50-gold.png
price: 25
hundredGold:
name: 100 Gold
description: Add 100 gold to your wallet!
icon: products/100-gold.png
price: 45
Because Roblox does not offer any way to delete developer products, when a product is "deleted" by Mantle, it is updated in the following ways:
- Its description is updated to:
Name: <name>\nDescription:\n<description>
- Its name is updated to
zzz_Deprecated(<date-time>)
where<date-time>
is the current date-time inYYYY-MM-DD hh::mm::ss.ns
format.
target.experience.products.<label>.name
requiredstring
The display name of the developer product on the Roblox website and in the experience.
target.experience.products.<label>.description
default: ''string
The description of the developer product on the Roblox website and in the experience.
target.experience.products.<label>.icon
string
A file path to an image to use as the product's icon on the Roblox website and in the experience.
target.experience.products.<label>.price
requireduint32
The price of the developer product in Robux.
target.experience.passes
dictionary
Passes that can be purchased within your experience for Robux.
target:
experience:
passes:
shipOfTheLine:
name: Ship of the Line
description: Get the best ship in the game!
icon: passes/ship-of-the-line.png
price: 499
Because Roblox does not offer any way to delete game passes, when a pass is "deleted" by Mantle, it is updated in the following ways:
- Its description is updated to:
Name: <name>\nPrice: <price>\nDescription:\n<description>
- Its name is updated to
zzz_Deprecated(<date-time>)
where<date-time>
is the current date-time inYYYY-MM-DD hh::mm::ss.ns
format.
target.experience.passes.<label>.name
requiredstring
The display name of the game pass on the Roblox website and in the experience.
target.experience.passes.<label>.description
default: ''string
The description of the game pass on the Roblox website and in the experience.
target.experience.passes.<label>.icon
requiredstring
A file path to an image to use as the pass's icon on the Roblox website and in the experience.
target.experience.passes.<label>.price
uint32
The price of the game pass in Robux. If not specified, the game pass will be off-sale.
target.experience.badges
dictionary
Badges that can be awarded within your experience.
target:
experience:
badges:
captureFirstShip:
name: Capture First Ship!
description: You captured your first enemy ship!
icon: badges/capture-first-ship.png
caution
Each user can create up to 5 badges for free every day. After that, badges cost 100 Robux each. By
default, Mantle does not have permission to make purchases with Robux, so if you go over your daily
quota, you will need to use the --allow-purchases
flag to create them.
Because Roblox does not offer any way to delete badges, when a badge is "deleted" by Mantle, it is updated in the following ways:
- It is disabled
- Its description is updated to:
Name: <name>\nEnabled: <enabled>\nDescription:\n<description>
- Its name is updated to
zzz_Deprecated(<date-time>)
where<date-time>
is the current date-time inYYYY-MM-DD hh::mm::ss.ns
format.
target.experience.badges.<label>.name
requiredstring
The display name of the badge on the Roblox website and in the experience.
target.experience.badges.<label>.description
default: ''string
The description of the badge on the Roblox website and in the experience.
target.experience.badges.<label>.icon
requiredstring
A file path to an image to use as the badge's icon on the Roblox website and in the experience.
target.experience.badges.<label>.enabled
default: trueboolean
Whether or not the badge is enabled.
target.experience.assets
[string | object]
A list of assets to include in your experience.
If set to a string, the value should be a file path or glob to an asset
or list of assets. The rbxgameasset
name of each matched file will be
its file name without the extension. For example,
assets/pirate-flag.png
will be given the rbxgameasset
name
pirate-flag
and will be accessible in the experience with
rbxgameasset://Images/pirate-flag
.
If set to an object, file
should be set to a file path (it will not be
interpreted as a glob), and name
will be the name of the
rbxgameasset
.
target:
experience:
assets:
- assets/*
- file: marketing/icon.png
name: game-icon
caution
Roblox provides each user a monthly quota of audio uploads. Mantle will let you know each time it uploads an audio asset how many uploads you have left and when your quota will reset.
Each file will be uploaded as the asset type matching its file extension. Supported asset types and their file extensions:
Asset type | File extensions |
---|---|
Image | .bmp , .gif , .jpeg , .jpg , .png , .tga |
Audio | .ogg , .mp3 |
target.experience.spatialVoice
object
Spatial voice configuration.
target.experience.spatialVoice.enabled
requiredboolean
Whether or not spatial voice is enabled for the experience.
target.experience.notifications
dictionary
Notification strings for your experience.
By default, the name of each notification (which is only visible to you in the creator portal) is set
to the label of the notification config. You can override this by setting the name
property.
target:
experience:
notifications:
customInvitePrompt:
content: '{displayName} is inviting you to join {experienceName}!'
target:
experience:
notifications:
customInvitePrompt:
name: Custom Invite Prompt
content: '{displayName} is inviting you to join {experienceName}!'
target.experience.notifications.<label>.name
string
The display name of the notification string on the Roblox website.
target.experience.notifications.<label>.content
requiredstring
The content of the notification string. Must include {experienceName} placeholder and may include {displayName} placeholder once.
state
default: 'local''local' | object | object
Defines how Mantle should manage state files (locally or remotely).
Value | Description |
---|---|
'local' | Mantle will save and load its state to and from a local .mantle-state.yml file. |
localKey: <key> | Mantle will save and load its state to and from a local file using the provided key with the format <key>.mantle-state.yml . |
remote: <config> | Mantle will save and load its state to and from a remote file stored in a cloud provider. Currently the only supported provider is Amazon S3. For more information, see the Remote State guide. |
state: local
state:
localKey: pirate-wars
state:
remote:
region: us-west-1
bucket: my-mantle-states
key: pirate-wars
state.localKey
requiredstring
state.remote
requiredobject
state.remote.region
required'ap-east-1' | 'ap-northeast-1' | 'ap-northeast-2' | 'ap-northeast-3' | 'ap-south-1' | 'ap-southeast-1' | 'ap-southeast-2' | 'ca-central-1' | 'eu-central-1' | 'eu-west-1' | 'eu-west-2' | 'eu-west-3' | 'eu-north-1' | 'eu-south-1' | 'me-south-1' | 'sa-east-1' | 'us-east-1' | 'us-east-2' | 'us-west-1' | 'us-west-2' | 'us-gov-east-1' | 'us-gov-west-1' | 'cn-north-1' | 'cn-northwest-1' | 'af-south-1' | object
The AWS region your S3 bucket is located in. If for some reason you need to use a region that is not defined, you can supply a custom one:
state:
remote:
region:
custom:
name: region-name
endpoint: region-endpoint
bucket: my-mantle-states
key: pirate-wars
state.remote.bucket
requiredstring
The name of your AWS S3 bucket.
state.remote.key
requiredstring
The key to use to store your state file. The file will be named with the format
<key>.mantle-state.yml
.