Bzul

Bzul is an improved fork of Azul: a two-way synchronization tool between Roblox Studio and your local filesystem with full Luau-LSP support, code completion, and type checking.

Bzul keeps Azul's Studio-first workflow while adding improvements maintained in this fork, including local plugin installation with bzul plugin and expanded Remote/Bindable marker support.

Bzul is a fork and improved continuation of Azul. Azul means "blue" in Spanish, as a counterpart to Rojo ("red").

Quick Start — Why Bzul — Upstream Documentation — Upstream Discord

Philosophy

Bzul treats Studio as the source of truth. The local filesystem mirrors what's in Studio, not the other way around.

It avoids the complexity and ambiguity that can come with tools like Rojo: for example, deciding a new Script's parent class, properties, or attributes. Rather than trying to encode Studio state in extra files (i.e. model.json, meta.json...), Bzul lets Studio determine state. This leads to a much simpler and more intuitive workflow.

While Bzul follows this philosophy, it doesn't cut you off from the filesystem. Build from local files using bzul build, or selectively push files using bzul push.

Features

• • [x] 🔄 Bi-directional sync: Changes in Studio update files, and file edits update Studio
• • [x] 🌳 DataModel mirroring: Instance hierarchy 1:1 mapped to folder structure
• • [x] 🎯 No manual config / required structure: Works out of the box with new and existing Roblox Studio projects, regardless of structure
• • [x] 🏗️ Build command: Sync your local files into Studio with bzul build.
• • [x] 📦 Push command: Selectively push local files into Studio using bzul push. Useful when importing external libraries or using package managers (i.e Wally)
• • [x] 🏛️ Fully hermetic builds: Fully serialize Instance properties using bzul pack, allowing for clean, reproducible builds when building or pushing.
• • [x] 🔴 Rojo compatibility mode: Supports importing from Rojo projects with the --rojo flag.
• • [x] 🗺️ Automatic sourcemap generation: Generates a Rojo-compatible sourcemap.json so tools like Luau-lsp work out of the box.

Why Bzul?

Bzul is the improved Azul workflow: install the CLI, run bzul in your project folder, connect the companion plugin in Studio, and start coding.

Compatible with projects both old and new, no more extra worrying about how to “Rojo-ify” your project. Your code is literally 1:1 mapped to what’s in Studio.

Why not use Rojo?

Rojo is the industry standard for a reason, but it's built on a specific premise: the filesystem must be the source of truth. While this works for traditional software, it creates a massive "philosophy gap" when applied to a visual, instance-based engine like Roblox.

Whether you use Rojo fully or partially, you run into the same fundamental problems:

• Fully Managed: To keep everything on the filesystem, you have to define your entire game hierarchy in JSON or manage opaque .rbxm files. This turns a visual engine into a text-config chore.
• Partially Managed: Most settle for a hybrid approach to avoid the pitfalls of fully managed, but this also introduces new problems. Your local files are no longer a true reflection of your Studio project, since they are missing literal chunks of your project. This leads to confusion & a fractured workflow where you constantly switch contexts between Studio and your IDE.

Instead of fighting Studio, Bzul embraces it as the source of truth and mirrors it to your filesystem in real-time. You get the best of both worlds: the power of external tooling & the seamless, visual workflow of Studio.

Why not use Roblox Script Sync?

Bzul keeps Azul's advantages over the upcoming Script Sync feature:

• Bzul mirrors everything: Script Sync can only sync specified folders and scripts, not entire projects. Bzul directly mirrors the entire DataModel, meaning you don't have to worry about manually syncing specific parts of your project.

• Building from filesystem: Script Sync is a "live-only" link with no manual override. Bzul gives you the bzul build command, allowing you to forcefully push your local state into Studio. This is essential for maintaining a clean state or recovering from accidental Studio changes.

• First-class Package Support: Syncing external libraries or using package managers (Wally, pesde) is seamless with bzul push. You don't have to manually set up sync roots for every new package you install; Bzul just handles it.

• Rojo compatibility: Bzul can import existing Rojo projects using the --rojo & --rojo-project <file> flags, making this fork compatible with many existing open source projects.

  • Generates a Rojo-compatible sourcemap.json: This allows any tooling that require Rojo-style sourcemaps (like luau-lsp, the language server) to work seamlessly.

• Zero commitment: Bzul requires no commitment to a specific project structure. If you want to try out Script Sync (or any other tool) in the future, Bzul won't get in your way.

Quick Start

Auto-Install (Recommended)

1. Install Node.js from nodejs.org.
2. Run the following command in your terminal:

   npm install -g @okitomassa/bzul

3. Install the Bzul Companion Plugin to Roblox Studio.
   • Guide: Bzul Plugin: Install Instructions
4. Create a new Folder to house your Bzul project and open it in your IDE.
5. With the terminal in your project folder, run:

   bzul

6. In Roblox Studio, click on the "Connect" button in the Bzul plugin.
7. Start coding!
8. (Optional) For the best experience, check out the Recommended Tools & Extensions.

Manual Install

1. Open a local checkout of this Bzul fork.
2. Install Node.js from nodejs.org or by using your system's package manager:

   # Windows (using winget)
   winget install OpenJS.NodeJS.LTS
   # macOS (using Homebrew)
   brew install node
   # Linux (using apt)
   sudo apt install nodejs npm

3. Install dependencies by running

   npm install

4. Build the project

   npm run build

5. Install the project globally

   npm install -g .

6. Install the Bzul Companion Plugin to Roblox Studio.
   • Guide: Bzul Plugin: Install Instructions
7. Create a new Folder to house your Bzul project and open it in your IDE.
8. With the terminal in your project folder, run:

   bzul

9. In Roblox Studio, click on the "Connect" button in the Bzul plugin.

Recommended Tools & Extensions

VSCode with Luau-LSP

To get the best experience, use Visual Studio Code with the Luau Language Server extension.

To get IntelliSense working, open your User Settings (JSON) from the command palette (Ctrl+Shift+P or Cmd+Shift+P) and make sure to set up luau-lsp like this:

  "luau-lsp.plugin.enabled": true,
  "luau-lsp.sourcemap.enabled": true,
  "luau-lsp.sourcemap.autogenerate": false,
  "luau-lsp.sourcemap.sourcemapFile": "sourcemap.json",
  "luau-lsp.sourcemap.includeNonScripts": true,

This is my recommended setup for Bzul projects. Bzul remains compatible with Azul projects and any IDE or text editor that can edit .luau files. Luau-LSP is also available for other editors like Neovim.

VSCode with Verde

Verde is a VSCode extension that mimics the Roblox Studio Explorer and Properties windows. It works great alongside Bzul to provide a seamless development experience.

Contributing

Contributions are welcome! Please open issues or pull requests on GitHub. This fork aims to make Bzul a faster, improved Azul experience for anyone who wants to use it.