20 releases (6 breaking)
0.8.1 | Aug 6, 2024 |
---|---|
0.8.0 | Jul 1, 2024 |
0.7.2 | Jun 16, 2024 |
0.4.0 | Mar 30, 2024 |
#64 in Games
31 downloads per month
69KB
1.5K
SLoC
Asphalt
Asphalt is a simple CLI tool used to upload assets to Roblox and easily reference them in code.
Features
- Upload images, SVGs, sounds, models, and animations to Roblox
- Generate Luau code to reference the uploaded assets
- Generate Typescript definitions for roblox-ts users
- Uses the Open Cloud API
- Supports uploading to groups
- Define existing uploaded assets, so all of your stuff can be referenced in one place
- Alpha bleeds images for crisp edges when scaled
Installation
Aftman
aftman add jacktabscode/asphalt
Rokit
rokit add jacktabscode/asphalt
Cargo (build from source)
cargo install asphalt
Commands
asphalt init
Guides you through setting up a new Asphalt project in the current directory.
asphalt sync
Syncs all assets in asset_dir
.
There are three targets you can use to sync assets:
-
cloud
: Uploads your assets to Roblox. This will generate aasphalt.lock.toml
file which you should commit to source control. This is the default target. -
studio
: Syncs assets locally to Roblox Studio. This is useful for testing assets in Studio before uploading them to Roblox. -
debug
: Syncs assets to an.asphalt-debug
folder in the current directory.
asphalt sync # Equivalent to --target cloud
asphalt sync --target studio
asphalt sync --target debug
You can also perform a dry run to verify which assets will be synced. This displays the assets that would be synced without syncing them.
asphalt sync --dry-run
asphalt list
Lists asset paths from the lockfile and their corresponding Roblox asset IDs.
Configuration
Asphalt is configured with a project file called asphalt.toml
. It is required for the program to run.
Example
asset_dir = "assets/"
exclude_assets = ["**/*.txt", "**/*.DS_Store"]
write_dir = "src/shared/"
[codegen]
typescript = true
style = "flat"
output_name = "assets"
[creator]
type = "user"
id = 9670971
[existing]
"test/some_sound_on_roblox.ogg" = { id = 123456789 }
"test/some_image_on_roblox.png" = { id = 987654321 }
Format
asset_dir
: path- The directory of assets to upload to Roblox.
exclude_assets
: array (optional)- An array of glob patterns to exclude when processing the assets directory.
write_dir
: path- The directory to output the generated code to. This should probably be somewhere in your game's source folder.
creator
: Creator- The Roblox creator to upload the assets under.
codegen
: Codegen- Code generation options.
existing
: map<string, ExistingAsset> (optional)
Creator
type
: "user" or "group"id
: number
Codegen
typescript
: boolean (optional)- Generate a Typescript definition file.
style
: "flat" | "nested" (optional)- The code-generation style to use. Defaults to
flat
. If you would like to have an experience similar to Tarmac, usenested
.
- The code-generation style to use. Defaults to
output_name
: string (optional)- The name for the generated files. Defaults to
assets
.
- The name for the generated files. Defaults to
strip_extension
: boolean (optional)- Whether to strip the file extension. Defaults to
false
. If you would like to have an experience similar to Tarmac, usetrue
.
- Whether to strip the file extension. Defaults to
ExistingAsset
id
: number
Code Generation
The formatting of code generation (such as spaces, tabs, width, and semicolons) is not guaranteed by Asphalt and may change between releases without being noted as a breaking change.
Therefore, it is recommended to add Asphalt's generated files to your linter/formatter's "ignore" list. Here are instructions for the most commonly used tools:
API Key
You will need an API key to sync with Asphalt. You can specify this using the --api-key
argument, or the ASPHALT_API_KEY
environment variable.
You can get one from the Creator Dashboard. Make sure you select the correct group and Asset-related permissions.
Cookie
You will need a cookie to upload animations to Roblox. This is because the Open Cloud API does not support them. It will automatically detected from the current Roblox Studio installation. Otherwise, you can specify this using the --cookie
argument, or the ASPHALT_COOKIE
environment variable.
You will probably want to disable Session Protection if you are using Asphalt in an environment where your IP address changes frequently.
Animations
[!WARNING] This feature is experimental, and Roblox may break the API we use or change its behavior without warning.
To upload animations, make sure you specify a cookie as noted above.
Asphalt expects a single KeyframeSequence to be saved as either a .rbxm
or .rbxmx
file.
Attributions
Thank you to Tarmac for the alpha bleeding and nested codegen implementations, which were used in this project.
Dependencies
~25–41MB
~707K SLoC