Why RoFlux

There are a few good ways to work on a Roblox game from real files. This page helps you pick one. The short answer: choose RoFlux when you want your build to do more than copy files, like running your own code or turning other languages and formats into instances.

The short version

These tools do not have to compete. The right one depends on where you like to work and how much control you want over the build.

Your build runs your code

Most sync tools follow a fixed set of rules: this file becomes that instance. RoFlux has those rules too, but it also runs Luau scripts from your project's scripts/ folder during every build. They work like plugins for the sync itself.

A script can:

• change source on its way to Studio, like adding a version line or stripping debug code
• build modules from data files, so a folder of JSON becomes one tidy ModuleScript
• edit the finished tree before it syncs, to tag, add, rename or remove instances
• run tools you already use, like a formatter, when you allow it
• talk to your game while you playtest, saving the console to a file or sending messages in and out

Each of those is a few lines. Here is a version line added to every script in the game:

-- scripts/version.luau
roflux.onTransfer(function(file)
	return `-- {roflux.project().name} built {os.date("%Y-%m-%d")}\n` .. file.source
end)

Your scripts get a full toolkit: reading and writing project files, JSON and TOML, building instances, value helpers, a cache, and require for splitting them up. Your editor type checks all of it. See the Script system and the Script API.

Any file, any language

A script can claim a file extension and say what those files become. That makes RoFlux a place to plug in other languages and formats, with no extra build step and no second tool watching your files.

• .csv or .yaml data turned into ModuleScripts
• a small markup file turned into a whole UI tree
• notes or dialogue turned into StringValues
• a simple language compiled into Luau, like a small part of Python

This turns every .csv file into a ModuleScript that returns its rows:

-- scripts/csv.luau
roflux.transpile("csv", function(file)
	local rows = {}

	for _, line in roflux.text.lines(file.text) do
		table.insert(rows, roflux.text.split(line, ","))
	end

	return roflux.luau.module(rows)
end)

Returning text makes a ModuleScript with that source. Return a declaration instead and one file can build any number of instances. Either way:

• it happens live while you work, and also in roflux build
• editing the file only updates what changed in Studio
• deleting the file removes everything it made
• the result is in the sourcemap, so your editor knows about it
• one call to roflux.meta gives the result real types, so requiring it autocompletes like a normal module

Your Luau is never touched unless you ask. RoFlux sends it to Studio exactly as written, and only a script you wrote can change it.

Other things you get

• The plugin is built in. roflux plugin installs the Studio plugin from the server itself, so the two always match.
• A small project file. Folders say where they go with a tiny init.meta.json, instead of one big file describing the whole game.
• It only touches what you declared. It cleans up inside the trees you own and leaves the rest of the place alone. It even remembers what it made, so a folder you moved while offline is cleaned up on the next connect.
• A review before big changes. On connect you see everything that will be created, edited or deleted, and can say no.
• Types everywhere. sourcemap.json is rewritten on every change for luau-lsp.
• Real place files. roflux build writes .rbxl and .rbxm files for publishing or CI.

When to pick something else

RoFlux is not the right tool for everyone. Pick something else when:

• You build mostly in Studio and want changes you make there saved back to your files. RoFlux never reads anything from Studio, on purpose. A two way tool like Azul or Carbon fits that better.
• You want the Explorer and Properties inside your editor. Pesto and Verde are made for that.
• You need the most proven option. Rojo has years of use, a large community, and many tools and templates built around its project format. RoFlux is young, and its project format is different.

Coming from Rojo

The ideas are close, so moving over is mostly renaming.

One thing to know: loose files at the top of a RoFlux project are ignored. Only meta.inst.json and folders with an init.meta.json are compiled there. See the project root rules.