13 releases (4 breaking)

new 0.6.1 May 28, 2024
0.6.0 May 26, 2024
0.5.1 May 4, 2024
0.5.0 Apr 26, 2024
0.2.1 Mar 7, 2024

#8 in Games

Download history 401/week @ 2024-03-06 61/week @ 2024-03-13 461/week @ 2024-03-27 185/week @ 2024-04-03 119/week @ 2024-04-10 18/week @ 2024-04-17 120/week @ 2024-04-24 188/week @ 2024-05-01 5/week @ 2024-05-08 2/week @ 2024-05-15 148/week @ 2024-05-22

345 downloads per month

MIT license



Asphalt is a simple CLI tool used to upload assets to Roblox and easily reference them in code.


  • Upload images, audio, and even SVGs!
  • 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



aftman add jacktabscode/asphalt


cargo install asphalt


asphalt init

Guides you through setting up a new Asphalt project in the current directory.

asphalt sync

Uploads all assets in the asset_dir to Roblox. It will also generate a asphalt.lock.toml file which you should commit to source control.

asphalt list

Lists asset paths from the lockfile and their corresponding Roblox asset IDs.


Asphalt is configured with a project file called asphalt.toml. It is required for the program to run.

asset_dir = "test/"
write_dir = "output/"

typescript = true
luau = true
style = "flat"
output_name = "assets"

type = "user"
id = 9670971

"test/some_sound_on_roblox.ogg" = { id = 123456789 }
"test/some_image_on_roblox.png" = { id = 987654321 }


  • asset_dir: path
    • The directory of assets to upload to Roblox.
  • 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)


  • type: "user" or "group"
  • id: number


  • typescript: boolean (optional)
    • Generate a Typescript definition file.
  • luau: boolean (optional)
    • Use the luau file extension.
  • style: "flat" | "nested" (optional)
    • The code-generation style to use. Defaults to flat. If you would like to have an experience similar to Tarmac, use nested.
  • output_name: string (optional)
    • The name for the generated files. Defaults to assets.
  • strip_extension: boolean (optional)
    • Whether to strip the file extension. Defaults to false. If you would like to have an experience similar to Tarmac, use true.


  • id: number


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.


Thank you to Tarmac for the alpha bleeding and nested codegen implementations, which were used in this project.


~544K SLoC