Models in packages

A Roblox package can ship model files (.rbxm) next to its code: UI templates, rigs, effects, and other prebuilt instance trees. A model supports the code of its package. A package that holds only models fails the publish check.

The publish rules#

The registry checks every model file when you publish, and rejects the publish when a model breaks one of these rules. embr publish itself stops on an .rbxmx file before it uploads. The other checks run on the registry, so --dry-run and --local do not catch them.

• No scripts. A model holds no Script, LocalScript, or ModuleScript instance. Code goes in .luau or .lua files, where everyone can read it on the package page. The error names the script classes it found.
• One root. A file holds exactly one root instance. Save one model to each file. Save to File on a selection of several instances writes a file with several roots.
• Binary only. The file is a binary .rbxm. An XML .rbxmx fails the check. Save it again as binary, which is the Studio default.
• Code first. The package also ships at least 10 lines of code. A line counts when it is not blank and not only a comment, in a .luau, .lua, .aly, .alx, .loom, or .luwu file. A one-line loader beside a model is not enough.
• Size. A package holds at most 64 model files, each at most 2 MB, with at most 100,000 instances across all of them.

The file name is the instance name#

Rojo makes an instance from each model file and gives it the name of the file. The name inside the file has no effect. A folder becomes a Folder instance:

src/
  init.luau            -- the module
  Models/
    Rock.rbxm          -- script.Models.Rock
    Tree.rbxm          -- script.Models.Tree
  UI/
    HealthBar.rbxm     -- script.UI.HealthBar

Your code finds a model at that path, and a project that installs the package gets the same tree. Keep the file name the same in each version: a new name changes the path for every dependent.

See inside a model#

On a package page, the Source tab shows each model as its instance tree: the name and class of each instance, and the full hierarchy. You can see what a model holds before you install the package. A model that holds scripts gets a red warning. An older version can hold scripts, because it was published before the check.

Edit a model#

A model is binary, so you edit it in Studio:

1. Open the model in Studio and make the change.
2. Write it back to disk with rojo syncback (Rojo 7.7 or later), or use Save to File over the old .rbxm.
3. Publish a new version with embr publish.