Skip to main content

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:

  1. If the PROJECT argument was not provided, use the mantle.yml file in the current directory as the config file (if it exists).
  2. If the PROJECT argument was a directory, use the mantle.yml file in that directory as the config file (if it exists).
  3. 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:

project/mantle.yml
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.

ValueDescription
'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.
Personal Example (Default)
owner: personal
Group Example
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.

ValueDescription
'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.

Example
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.

ValueDescription
'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.
Environment Label Example
environments:
- label: dev
targetNamePrefix: environmentLabel
- label: prod
Custom Example
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.

ValueDescription
'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.

Example
target:
experience: {}

target.experiencerequiredobject

target.experience.configurationobject

The Experience's Roblox configuration.

Example
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.

ValueDescription
'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.

ValueDescription
'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.
Enabled Example
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.

ValueDescription
'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.
Enabled for Free Example
target:
experience:
configuration:
privateServers: free
Enabled for Price Example
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.

Example
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

Example
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.

Example
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.

ValueDescription
'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.
Maximum Example
target:
experience:
places:
start:
file: game.rbxlx
configuration:
serverFill: maximum
Reserved Slots Example
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.

A list of social links that will appear on the experience's webpage.

Example
target:
experience:
socialLinks:
- title: Follow on Twitter
url: https://twitter.com/blakemdev

The display name of the social link on the Roblox website.

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.

Example
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:

  1. Its description is updated to: Name: <name>\nDescription:\n<description>
  2. Its name is updated to zzz_Deprecated(<date-time>) where <date-time> is the current date-time in YYYY-MM-DD hh::mm::ss.ns format.

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.

Example
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:

  1. Its description is updated to: Name: <name>\nPrice: <price>\nDescription:\n<description>
  2. Its name is updated to zzz_Deprecated(<date-time>) where <date-time> is the current date-time in YYYY-MM-DD hh::mm::ss.ns format.

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.

Example
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:

  1. It is disabled
  2. Its description is updated to: Name: <name>\nEnabled: <enabled>\nDescription:\n<description>
  3. Its name is updated to zzz_Deprecated(<date-time>) where <date-time> is the current date-time in YYYY-MM-DD hh::mm::ss.ns format.

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.

Example
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 typeFile 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.

Example
target:
experience:
notifications:
customInvitePrompt:
content: '{displayName} is inviting you to join {experienceName}!'
Example with custom name
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).

ValueDescription
'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.
Local State Example (Default)
state: local
Custom Local State Example
state:
localKey: pirate-wars
Remote State Example
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:

Custom Region Example
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.