Heads up! This repository was recently migrated from the rojo-rbx org to the Roblox org. Not much else has changed.
Tarmac is a resource compiler and asset manager for Roblox projects. It helps enable hermetic place builds when used with tools like Rojo.
Tarmac is inspired by projects like Webpack that make it easy to reference assets from code.
The recommended way to install Tarmac is with Foreman.
Add an entry to the [tools]
section of your foreman.toml
file:
foreman = { source = "Roblox/tarmac", version = "0.6.0" }
Pre-built binaries are available for 64-bit Windows, macOS, and Linux from the GitHub releases page.
Tarmac requires Rust 1.39.0 or newer to build.
You can build the latest release of Tarmac from crates.io:
cargo install tarmac
or build the latest work from the master branch:
cargo install --git https://github.com/Roblox/tarmac
The examples folder contains small, working projects using different features from Tarmac.
Tarmac is configured by a TOML file in the root of a project named tarmac.toml
. Tarmac uses this file to determine where to look for assets and what to do with them.
To tell Tarmac to manage PNG files in a folder named assets
, you can use:
name = "basic-tarmac-example"
# Most projects will define some 'inputs'.
# This tells Tarmac where to find assets that we'll use in our game.
[[inputs]]
glob = "assets/**/*.png"
codegen = true
codegen-path = "src/assets.lua"
codegen-base-path = "assets"
Run tarmac sync --target roblox
to have Tarmac upload any new or updated assets that your project depends on. You may need to pass a .ROBLOSECURITY
cookie explicitly via the --auth
argument.
Tarmac will generate Lua code in src/assets.lua
that looks something like this:
-- This file was @generated by Tarmac. It is not intended for manual editing.
return {
foo = {
bar = "rbxassetid://238549023",
baz = "rbxassetid://238549024",
}
}
These files will be turned into ModuleScript
instances by tools like Rojo. From there, it's easy to load this module and reference the assets within:
local assets = require(script.Parent.assets)
local decal = Instance.new("Decal")
decal.Texture = assets.foo.bar
For more information, run tarmac --help
.
These options can be specified alongside any subcommands and are all optional.
--help
,-h
- Prints help information about Tarmac and exits.
--version
,-V
- Prints version information about Tarmac and exits.
--auth <cookie>
- Explicitly defines the authentication cookie Tarmac should use to communicate with Roblox.
- If not specified, Tarmac will attempt to locate one from the local system.
--verbose
,-v
- Enables more verbose logging. Can be specified up to three times, which will increase verbosity further.
Detects changes to assets in the local project and attempts to synchronize them with an external service, like the Roblox cloud.
Usage:
tarmac sync [<config-path>] \
--target <roblox|debug|none>
--retry <number>
--retry-delay <60>
To sync the project in your current working directory with the Roblox cloud, use:
tarmac sync --target roblox
To validate that all inputs are already synced, use the none
target:
tarmac sync --target none
When tarmac gets rate limited while syncing to Roblox, use the --retry
argument to automatically attempt to re-upload. This will tell tarmac how many times it can attempt to re-upload each asset. The --retry-delay
sets the number of seconds to wait between each attempt.
tarmac sync --target roblox --retry 3
Uploads a single image as a decal and prints the ID of the resulting image asset to stdout.
Usage:
tarmac upload-image <image-path> \
--name <asset-name> \
--description <asset-description>
Example:
tarmac upload-image foo.png --name "Foo" --description "Foo is a placeholder name."
Outputs a list of all of the asset IDs referenced by the project. Each ID is separated by a newline.
Usage:
tarmac asset-list [<config-path>] \
--output <file-path>
Example:
tarmac asset-list --output asset-list.txt
Creates a mapping from asset IDs back to their source files. Also downloads packaged images to a given folder, generating links to those assets as well.
The mapping file is JSON.
Usage:
tarmac create-cache-map [<config-path>] \
--index-file <file-path> \
--cache-dir <cache-folder>
Example:
tarmac create-cache-map --index-file assets.json --cache-dir asset-cache
Prints help information about Tarmac itself, or the given subcommand.
Usage:
tarmac help [<subcommand>]
name
, string- The name of the Tarmac project, used in logging and error reporting.
max-spritesheet-size
, (int, int), optional- The maximum spritesheet size that Tarmac should use. Defaults to (1024, 1024), the maximum image size supported by Roblox.
asset-cache-path
, path, optional- If defined, Tarmac will re-download uploaded images to a local folder at the given path. Files in this folder not associated with assets in the project will be deleted.
asset-list-path
, path, optional- If defined, Tarmac will write a list of asset URLs used by the project to the given file. One URL is printed per line.
upload-to-group-id
, int, optional- If defined, Tarmac will attempt to upload all assets to the given Roblox Group. If unable, syncing will fail.
inputs
, list<InputConfig>, optional- A list of inputs that Tarmac will process.
includes
, list<path>, optional- A list of additional paths to search recursively for additional projects in. The inputs from discovered projects will be merged into this project, and other settings ignored.
- When a
tarmac.toml
file is found, Tarmac will include it and its includes and stop traversing that directory.
glob
, string- A path glob that should include any files for this input group.
- Tarmac uses the globset library and supports any syntax it supports.
codegen
, bool, optional- Whether Tarmac should generate Lua code for the assets contained in this input group. Defaults to false.
codegen-path
, path, optional- If defined and
codegen
is true, Tarmac will merge all generated Lua code for this input group into a single file.
- If defined and
codegen-base-path
, path, optional- Defines the base path for generating Lua code when
codegen-path
is also defined. Defaults to the directory containingtarmac.toml
.
- Defines the base path for generating Lua code when
Tarmac is available under the MIT license. See LICENSE.txt for details.