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

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.

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)
  • 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)
• 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.