Rojo Compatibility

Azul features a Rojo Compatibility Mode that allows you to build or push Rojo-style projects into Roblox Studio.

When this article refers to “Rojo-style” projects, it means that the project is structured similarly to Rojo and its project format. In practice, this means the feature will also work with tools like Argon. Note that full support for these tools is not guaranteed.

azul build --rojo
azul build --rojo --rojo-project default.project.json
azul push -s Packages -d ReplicatedStorage.Packages --rojo

In this mode, Azul will try to do the following:

• Read the default.project.json (or the provided project file) to interpret Rojo-style structure.
• If no default.project.json is provided, or none is found, Azul will attempt to interpret the Rojo-style structure and push it into Studio.

Tip

Azul is capable of reading nested project files, so you can have a default.project.json in your root folder and another one in a subfolder. The subfolder’s project file will be used for that subfolder’s contents.

Generating a Rojo project

azul pack can also write a Rojo project file from the packed sourcemap, so your project can be used with Rojo-based tooling:

azul pack --rojo
azul pack --rojo-output my-library.project.jsonc

• By default, the project is written to default.project.jsonc. Use --rojo-output to pick another path (it must end in .project.json or .project.jsonc).
• If you’re packing a package, the project is rooted at its packageRoot. Otherwise, it describes the whole place.
• References between instances (e.g. a Weld’s Part0) are kept using Rojo’s $id & Rojo_Target_* attributes.
• Azul asks before overwriting a project file it didn’t generate.

Caution

Rojo keys instances by name, so it can’t describe same-named siblings or names starting with $. If the packed instances have any, the sourcemap is still written, but the Rojo project is skipped with a list of the clashes. Rename them and pack again.

Supported Rojo features

This is a comprehensive list of Rojo features supported in the Rojo Compatibility Mode, with the following classification:

• ✅ - The feature is fully supported and works as expected
• ❌ - The feature is not available because it does not makes sense to include it
• 🔜 - The feature is not available but it’d be nice to include it at some point
• 🤷‍♀️ - The feature is not available yet; open to discussion about implementing this

Feature	Status	Notes
Scripts & folders (init.luau, *.luau, *.server.luau, *.client.luau)	✅
Rojo Project Files (*.project.json, *.project.jsonc)	✅	Nested project files are also supported.
JSON Models (*.model.json)	✅
XML or binary Models (*.rbxm, *.rbxmx)	❌	Azul does not yet support reading or writing rbxm/rbxmx files. When (or if) this is implemented for mainline Azul, this feature will be heavily considered.
Meta Files (*.meta.json)	🤷‍♀️	While supporting meta files is possible, I have not seen them used very often. A solid, real-world use case would be needed for it to be considered.
JSON Modules (*.json)	✅
Plain text files (*.txt)	🤷‍♀️	I have seen very few projects make use of the *.txt, *.csv or *.toml files.
Localization Tables (*.csv)	🤷‍♀️
TOML Modules (*.toml)	🤷‍♀️