Distributing Code

At some point, you may want to share your project with other developers. Whether it’s a library or a full game, you can use Azul to distribute it. Azul allows for hermetic builds, meaning that your collaborators will receive an identical copy of your project.

Collaborators can then use azul push to mount your project at a specific path in their existing game (e.g. a package into ReplicatedStorage), or azul build to replace their entire place with your project.

The sourcemap

Understanding how the sourcemap works is important for distributing code with Azul. The sourcemap is a JSON file that contains all of the information needed to map your project into Roblox.

Note

Coming from Rojo? Rojo’s sourcemap.json is a thin, tooling-only file. Azul’s sourcemap is a heavier artifact, it can carry enough data (properties, attributes, tags) to reconstruct a project, and is meant to be distributed to collaborators.

By default, Azul will generate a sourcemap during live sync. It includes the following:

• The structure of your project (folders, instances, etc.)
• name, className and guid of all instances

The azul pack command can be used to generate a sourcemap that includes the following additional information:

• The properties, attributes and tags of all instances

Packed sourcemaps only keep a guid on instances that another instance references (e.g. a Weld’s Part0 & Part1), as an ID local to the file. Packing an unchanged place produces the same file (besides packedAt), so packed sourcemaps make for clean Git diffs.

If your project is entirely code, you can distribute it without a sourcemap. This is because the code itself is sufficient to recreate the project.

Package files

If you’re distributing a library, ship an azul.package.json at the root of your project. It tells Azul what to push and which sourcemap to use, so collaborators only need to pick a destination:

azul push -s ./AzulPackages/MyLibrary -d ReplicatedStorage.Libraries

Run azul pack and answer yes to “Is this a package?” to create one.

Tip

Want to know more? See Package Files.

Best practices

• Sourcemaps
  • Don’t distribute a sourcemap if your project is entirely code. Only consider distributing a sourcemap if your project contains assets (e.g. textures, models, audio), non-default properties, attributes or tags.
  • Don’t source control, edit, or manually alter the ./sourcemap.json generated by live sync. It’s regenerated on every sync and isn’t the file you distribute.
  • When distributing a sourcemap alongside your project, use azul pack with the -o flag to write it to a different output file. The recommended naming convention is *.sourcemap.json.
    • (e.g game.sourcemap.json, plugin.sourcemap.json)
  • Working on a game with others? Enable Pack on exit so the packed sourcemap is updated every time you disconnect.
  • Collaborators should use the distributed sourcemap with the --from-sourcemap flag on azul push or azul build.
    • (e.g. azul build --from-sourcemap game.sourcemap.json)
• For libraries: ship an azul.package.json so collaborators only need to pick a destination.
• Importing a full game: use azul build with the --destructive flag to remove any orphaned Instances that were deleted in the source project.

A few examples

Confused? Here are a few practical examples of real projects distributed with Azul, using the best practices outlined above:

• Azul Companion Plugin: The official Azul Studio plugin.
• BetterChassis: A Roblox vehicle framework that uses Azul to distribute its code and assets.
• Raycer: An arcade Roblox vehicle library inspired by A-Chassis.
• CameraPart Previewer Plugin: Simple Roblox Studio plugin for previewing how the Camera will look using Attachments or BaseParts.