Azalea

Azalea is an EXPERIMENTAL software suite designed to manipulate Roblox model files for use within sandboxed Roblox environments, such as OpenSB.

Get started (install + command guide)

cargo install --locked --git https://github.com/techs-sus/azalea.git --features="base122 cli"
# ^^^ azalea is now in your shell as `azalea`

# You can also install or run with Nix:
# nix shell github:techs-sus/azalea

# -s is optional: you can specify a location for a specialized decoder to be generated
# if using -s: this command is limiting, you should migrate to other commands such as generate-full-script.
azalea encode -i input.rbxm -o output.bin -s specializedDecoder.luau -m

# All examples below:
# -i = --input (can be multiple files, or one file, REQUIRED)
# -o = --output (either a file, or a directory (then multiple inputs must be present), REQUIRED)
# -f = --format (with stylua, optional)
# -m = --minify (with darklua, optional): WARNING! Darklua is extra cautious when emitting strings and explodes file size.
# -c = --compat (makes code generated Lua 5.1 compatible; done via darklua, optional)

# generates a full decoder: can decode any file under azalea's format
azalea generate-full-decoder -o output.luau -f

# Examples which generate tailored code for a model:
# --novel: Supports ModuleScript loading by inlining ModuleScript sources. Completely avoids loadstring and supports require-by-string.
# --legacy: Enables any environment with NewScript and NewLocalScript to run. Shims require and NewModuleScript using loadstring. Broken in many games and will never support require-by-string.
# (default) --opensb: Enables OpenSB or any environment with NewScript, NewLocalScript, and NewModuleScript to run. Relies on the environment to support require-by-string.
# --studio: Enables Studio or any environment with Source access support to run.
# (optional, defaults to 11) --level: Zstandard compression level, 1 to 22; 22 produces the smallest output but is the slowest

# generates a full script: input.rbxm must have a root ModuleScript (such as a MainModule)
azalea generate-full-script -i input.rbxm -o output.luau -m

# generates an embeddable script, useful for embedding assets; script returns model root
azalea generate-embeddable-script -i input.rbxm -o output.luau -m

Notes

We supply a configurable alphabet base122 encoder in Rust and a decoder in Luau. (src/base122.rs, src/luau/base122.luau)

We use Base123 (base122 + ampersands) to embed binary data into the output scripts. We chose Base122 encoded data as it is ~14% smaller than Base64 encoded data.

A flake.nix is provided at flake.nix. It provides:

• a formatter usable with nix flake fmt (formats the entire flake)
• a devshell usable with nix develop
• a package usable in your flake via azalea.packages.${system}.default (where azalea is an input)
• if nix-direnv installed, you can run direnv allow to automatically enter a devshell when cd'ing into the project directory

We use bun for:

• generating files required for tests via bun run generate
• running tests via bun run tests; you need either run-in-roblox (preferred) or run-in-cloud in your PATH
• comparing format efficency via bun run compareExamples
• little shell scripts as bash & powershell are weird and cross platform support is nice

Format details:

• ULEB128 is used for referents and other things
• completely chunkless, roblox uses chunks
• roblox uses lz4 and zstd, we only use zstd
• can change at any time, not formalized or standardized

Platform support:

• Legacy is any compliant Luau implementation (NewScript and NewLocalScript but no NewModuleScript)
• OpenSB is any compliant OpenSB implementation (Luau + NewModuleScript), usually https://github.com/Open-SB/OpenSB.
• Studio is the environment in which plugins run or the command bar runs. It uses Script.Source (and other alike properties) to create LuaSourceContainer's.

Output of bun run compareExamples (format efficency, +'s added for color):

+ win! examples\attributes-and-tags.bin.zst (via Azalea) is smaller than examples\attributes-and-tags.rbxm (via Roblox) by 5.8 KiB
+ win! examples\fusion-0.3-release.bin.zst (via Azalea) is smaller than examples\fusion-0.3-release.rbxm (via Roblox) by 21.15 KiB
+ win! examples\graphql-3.10.0-release.bin.zst (via Azalea) is smaller than examples\graphql-3.10.0-release.rbxm (via Roblox) by 169.8 KiB
+ win! examples\luau-regexp-0.2.1-release.bin.zst (via Azalea) is smaller than examples\luau-regexp-0.2.1-release.rbxm (via Roblox) by 11.86 KiB
+ win! examples\matter-0.8.5-release.bin.zst (via Azalea) is smaller than examples\matter-0.8.5-release.rbxm (via Roblox) by 30.36 KiB
+ win! examples\matter-hooks-0.2.1-release.bin.zst (via Azalea) is smaller than examples\matter-hooks-0.2.1-release.rbxm (via Roblox) by 3.85 KiB
+ win! examples\plasma-0.4.4-release.bin.zst (via Azalea) is smaller than examples\plasma-0.4.4-release.rbxm (via Roblox) by 9.98 KiB
+ win! examples\react-lua-17-release.bin.zst (via Azalea) is smaller than examples\react-lua-17-release.rbxm (via Roblox) by 293.26 KiB
+ win! examples\test.bin.zst (via Azalea) is smaller than examples\test.rbxm (via Roblox) by 828 bytes

License

All code generated by tools, scripts, or code in this repository should be considered Apache 2.0 or MIT licensed (at your option).

Licensed under either of

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.