Tarmac Tarmac is inspired by projects like Webpack that make it easy to reference assets from code. Installation Installing with Aftman The recommended way to install Tarmac is with Aftman. Add an entry to the [tools] section of your aftman.toml file: tarmac = "rojo-rbx/tarmac@0.7.5" Installing with Foreman Add an entry to the [tools] section of your foreman.toml file: tarmac = { source = "rojo-rbx/tarmac", version = "0.7.5" } Installing from GitHub Releases Pre-built binaries are available for 64-bit Windows, macOS, and Linux from the GitHub releases page. Basic Example 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 Command Line Interface For more information, run tarmac --help. Global Options 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. tarmac sync 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 tarmac upload-image 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." tarmac asset-list 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 tarmac create-cache-map 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 tarmac help Prints help information about Tarmac itself, or the given subcommand. Usage: tarmac help [<subcommand>] Project Format 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. spritesheet-padding-size, int, optional The pixel padding between images packed into a spritesheet that Tarmac should use. Defaults to 1. 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. InputConfig 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. codegen-base-path, path, optional Defines the base path for generating Lua code when codegen-path is also defined. Defaults to the directory containing tarmac.toml. License Tarmac is available under the MIT license. See LICENSE.txt for details.