azalea

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

azalea is freely available to you, the consumer under the Apache 2.0 license.

Please note --minify may not retain behaviour due to: seaofvoices/darklua#250

legal note: all code generated by tools, scripts, or code in this repo are to be considered as files under the Apache 2.0 license

Running it + command guide

# pull the repo first obviously
git clone https://github.com/techs-sus/azalea
cd azalea

# Applys to all commands:
# -m [--minify] is optional: you can specify if you want to minify the luau result via darklua
# -f [--format] is optional: you can specify if you want to format the luau result via stylua
# using -m and -f together lead to a panic! you can only use one

# -s is optional: you can specify a location for a specialized decoder to be generated
cargo run -- encode -i input.rbxm -o output.bin -s specializedDecoder.luau -m

# generates a full decoder
cargo run -- generate-full-decoder -o output.luau -f
# generates a full script: input.rbxm must be a MainModule or have a root ModuleScript
cargo run -- generate-full-script -i input.rbxm -o output.luau -m
# generates an embeddable script, useful for embedding assets
cargo run -- generate-embeddable-script -i input.rbxm -o output.luau -m

Development notes

flake 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

bun is used for:

• generating required files for tests via bun run generate
• running tests via bun run tests; you need either run-in-roblox (preferred) or run-in-cloud
• comparing format efficency via bun run compareExamples

azalea supplies a base123 (base122 + legal ampersands) encoder in Rust and a decoder in Luau

Base123 is used in the generation step in place of Base64. Please make sure your IDE can handle ASCII control characters, as Base123 uses them.

format details:

• roblox compresses chunks using lz4 and zstd, azalea's format is chunkless and does not include compression (compression is often done with zstd after the encoding step)
• currently OpenSB and Roblox Studio are offically supported
• ULEB128 used for referents, eventually will be used for varstrings and other variable width Variants

current output of bun run compareExamples (format efficency):

win! examples/test.bin.zst (via Azalea) is smaller than examples/test.rbxm (via Roblox) by 823 bytes
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.34 KiB
win! examples/attributes-and-tags.bin.zst (via Azalea) is smaller than examples/attributes-and-tags.rbxm (via Roblox) by 6.9 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/graphql-3.10.0-release.bin.zst (via Azalea) is smaller than examples/graphql-3.10.0-release.rbxm (via Roblox) by 169.99 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.84 KiB
win! examples/fusion-0.3-release.bin.zst (via Azalea) is smaller than examples/fusion-0.3-release.rbxm (via Roblox) by 21.18 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.84 KiB
win! examples/react-lua-17-release.bin.zst (via Azalea) is smaller than examples/react-lua-17-release.rbxm (via Roblox) by 293.33 KiB