Home

Awesome

<div align="center"> <h1>Tarmac</h1> </div> <div align="center"> <a href="https://github.com/Vorlias/tarmac/actions"> <img src="https://github.com/Vorlias/tarmac/workflows/CI/badge.svg" alt="GitHub Actions status" /> </a> </div> <hr />

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.

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

InputConfig

License

Tarmac is available under the MIT license. See LICENSE.txt for details.