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
PROJECTargument was not provided, use themantle.ymlfile in the current directory as the config file (if it exists). - If the
PROJECTargument was a directory, use themantle.ymlfile in that directory as the config file (if it exists). - If the
PROJECTargument 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
ownerdefault: '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
paymentsdefault: '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. |
environmentsrequired[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.*.labelrequiredstring
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.*.tagCommitboolean
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.*.targetOverridesobject
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.
targetrequiredobject
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.experiencerequiredobject
target.experience.configurationobject
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.genredefault: 'all''all' | 'adventure' | 'building' | 'comedy' | 'fighting' | 'fps' | 'horror' | 'medieval' | 'military' | 'naval' | 'rpg' | 'sciFi' | 'sports' | 'townAndCity' | 'western'
The experience's genre.
target.experience.configuration.playableDevicesdefault: ['computer', 'phone', 'tablet']['computer' | 'phone' | 'tablet' | 'console']
The devices that the experience can be played on.
target.experience.configuration.playabilitydefault: '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.paidAccessdefault: '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.privateServersdefault: '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.enableStudioAccessToApisdefault: falseboolean
Whether or not studio should be able to use Roblox APIs for this place.
target.experience.configuration.allowThirdPartySalesdefault: falseboolean
Whether or not this experience should allow third-party sales.
target.experience.configuration.allowThirdPartyTeleportsdefault: falseboolean
Whether or not this experience should allow third-party teleports.
target.experience.configuration.avatarTypedefault: 'r15''r6' | 'r15' | 'playerChoice'
The types of avatars that players can use in this experience.
target.experience.configuration.avatarAnimationTypedefault: 'playerChoice''standard' | 'playerChoice'
The type of avatar animation that players can use in this experience.
target.experience.configuration.avatarCollisionTypedefault: 'outerBox''outerBox' | 'innerBox'
The type of avatar collision that players can use in this experience.
target.experience.configuration.avatarScaleConstraintsobject
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.avatarAssetOverridesobject
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.placesdictionary
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>.filestring
A file path to a Roblox place (either .rbxl or .rbxlx).
target.experience.places.<label>.configurationobject
A place's Roblox configuration.
target.experience.places.<label>.configuration.namedefault: '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.descriptiondefault: '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.maxPlayerCountdefault: 50uint32
The maximum number of players that can be in a server for the place.
target.experience.places.<label>.configuration.allowCopyingdefault: falseboolean
Whether or not other Roblox users can clone your place.
target.experience.places.<label>.configuration.serverFilldefault: '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.iconstring
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.*.titlerequiredstring
The display name of the social link on the Roblox website.
target.experience.socialLinks.*.urlrequiredstring
The URL of the social link. Must be one of the Roblox supported social link types.
target.experience.productsdictionary
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.nsformat.
target.experience.products.<label>.namerequiredstring
The display name of the developer product on the Roblox website and in the experience.
target.experience.products.<label>.descriptiondefault: ''string
The description of the developer product on the Roblox website and in the experience.
target.experience.products.<label>.iconstring
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>.pricerequireduint32
The price of the developer product in Robux.
target.experience.passesdictionary
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.nsformat.
target.experience.passes.<label>.namerequiredstring
The display name of the game pass on the Roblox website and in the experience.
target.experience.passes.<label>.descriptiondefault: ''string
The description of the game pass on the Roblox website and in the experience.
target.experience.passes.<label>.iconrequiredstring
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>.priceuint32
The price of the game pass in Robux. If not specified, the game pass will be off-sale.
target.experience.badgesdictionary
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.nsformat.
target.experience.badges.<label>.namerequiredstring
The display name of the badge on the Roblox website and in the experience.
target.experience.badges.<label>.descriptiondefault: ''string
The description of the badge on the Roblox website and in the experience.
target.experience.badges.<label>.iconrequiredstring
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>.enableddefault: 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.spatialVoiceobject
Spatial voice configuration.
target.experience.spatialVoice.enabledrequiredboolean
Whether or not spatial voice is enabled for the experience.
target.experience.notificationsdictionary
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>.namestring
The display name of the notification string on the Roblox website.
target.experience.notifications.<label>.contentrequiredstring
The content of the notification string. Must include {experienceName} placeholder and may include {displayName} placeholder once.
statedefault: '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.localKeyrequiredstring
state.remoterequiredobject
state.remote.regionrequired'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.bucketrequiredstring
The name of your AWS S3 bucket.
state.remote.keyrequiredstring
The key to use to store your state file. The file will be named with the format
<key>.mantle-state.yml.