Refab

Refab is a Roblox place-content manager for syncing Studio Instances with local files.

Refab is built for teams that keep Roblox code in Rojo, but still need a clean way to manage scene objects, UI, models, and other Studio-built content outside the place file.

Table Of Contents

• Workflow
• Sync To Roblox
• Sync To Local
• Refab CLI
• Multi-Place Projects
• Content Scope
• Install
• For Developers

Workflow

Refab uses a simple per-place folder convention:

places/
  lobby/
    Workspace/
      World/
        Boat.rbxm
        Boat.refab.json
    StarterGui/
      Inventory.rbxm
    ReplicatedStorage/
      Items/
        Sword.rbxm

Those files map directly back into Roblox:

places/lobby/Workspace/World/Boat.rbxm          -> Workspace.World.Boat
places/lobby/StarterGui/Inventory.rbxm          -> StarterGui.Inventory
places/lobby/ReplicatedStorage/Items/Sword.rbxm -> ReplicatedStorage.Items.Sword

The path maps to the Roblox destination. Refab keeps a small .refab.json sidecar next to each content file, while Studio Instances store one compact Refab JSON attribute. That keeps identity, class, path, and hash metadata lightweight on both sides. There is no global manifest file to merge or maintain.

Rojo remains the owner of project source code under folders like src/client, src/server, and src/shared. Refab manages serialized Studio content files; if a Roblox content package contains scripts as part of that package, they stay inside the serialized .rbxm/.rbxmx.

Sync To Roblox

Use this when local content files should update the open place.

1. Run refab run in your project folder.
2. Open Roblox Studio.
3. Open the Refab plugin.
4. Use To Roblox.
5. Review new, changed, and moved assets in the tree.
6. Select the assets or folders you want.
7. Click Apply.

Changed content replaces the matching Instance. New content is inserted into the matching Roblox service. Moved content keeps the same Refab id when metadata can be matched safely.

Sync To Local

Use this when selected Studio Instances should become local content files.

1. Select Instances in Explorer.
2. Open the Refab plugin.
3. Use To Local.
4. Review the selected asset tree.
5. Select the assets or folders you want.
6. Click SAVE TO LOCAL.

Refab writes the selected Instance tree into the active place folder and updates its local .refab.json metadata.

Refab CLI

Run it from your Roblox project root:

refab run

Short aliases are available:

refab r

During development, you can also run it with Cargo:

cargo run --manifest-path cli/Cargo.toml -- run

The CLI lets the Studio plugin scan, compare, read, and write local content files:

• scan configured place folders
• compare local files with open Studio Instances
• write selected Studio content back to the active place folder
• create missing .refab.json metadata files
• repair safe sidecar issues after local file moves

If a project has .rbxm files without sidecar metadata, run:

refab repair --check
refab repair

refab run also checks metadata when it starts. While it is running, Refab watches configured place folders and repairs safe metadata cases when the plugin refreshes or checks status. If a moved or renamed .rbxm has one matching orphan sidecar with the same hash, Refab moves the sidecar too so the asset id is preserved.

Multi-Place Projects

Refab can read place configuration from refab.toml:

[places.lobby]
root = "places/lobby"
place_id = 123456789

[places.gameplay]
root = "places/gameplay"

Keep Rojo project files at the repository root so normal Rojo commands stay simple:

rojo serve lobby.project.json
rojo serve gameplay.project.json

Run Refab once for the project:

refab run
refab r

Useful commands:

refab places
refab status
refab scan
refab repair --check
refab run --port 34875

In a multi-place project, each place keeps serialized Studio content under its configured place folder. Raw files like textures, images, and audio are managed by your project, not by Refab.

If refab.toml is missing, refab run scans the project and writes one before starting. It looks for root *.project.json files and matching places/<place> folders.

place_id is optional. When the Studio plugin connects, it uses place_id to pick the matching place. If a place has no place_id yet, Refab may select it for the current session, but it does not edit refab.toml. If the open Studio place has a different id than the selected config entry, Refab shows a mismatch warning.

Content Scope

Refab is organized around serializable place content, not game logic or raw project assets.

Asset/content type	Export	Import	Git	Destination	Preserved references
Workspace/world assets	Yes	Yes	Yes	Workspace	attributes, tags, instance refs, asset ids
Models, props, items, vehicles, characters	Yes	Yes	Yes	Any supported root	hierarchy, pivots, constraints, meshes, textures
ReplicatedStorage assets	Yes	Yes	Yes	ReplicatedStorage	attributes, tags, instance refs, asset ids
ServerStorage assets	Yes	Yes	Yes	ServerStorage	attributes, tags, private server-side asset refs
StarterGui UI	Yes	Yes	Yes	StarterGui	images, fonts, attributes, tags
StarterPack assets	Yes	Yes	Yes	StarterPack	tools, meshes, textures, sounds, animations
StarterPlayer content	Yes	Yes	Yes	StarterPlayer	character content, humanoid descriptions, visual refs
MeshParts and model hierarchies	Yes	Yes	Yes	Any supported root	mesh ids, texture ids, hierarchy, attributes
VFX, ParticleEmitters, Beams	Yes	Yes	Yes	Any supported root	texture ids, attachments, sequences
Audio, images, decals, textures	Yes	Yes	Yes	Any supported root	SoundId, Texture, Image, content ids
Animation references	Yes	Yes	Yes	Any supported root	AnimationId, rig/model references
Materials and visual assets	Yes	Yes	Yes	MaterialService or supported root	material variants, texture ids
Lighting visual content	Yes	Yes	Yes	Lighting	sky, atmosphere, post effects
Packages where applicable	Yes	Yes	Yes	Any supported root	package links and package ids
RBXM / RBXMX files	Yes	Yes	Yes	Path-derived Roblox target	serialized instance data

Supported root folders:

• Workspace
• ReplicatedStorage
• ServerStorage
• StarterGui
• StarterPack
• StarterPlayer
• Lighting
• SoundService
• MaterialService

Files under unsupported roots, such as places/lobby/Scene/..., are shown as errors because Roblox has no matching top-level Scene service.

Keep controllers, services, and source modules in Rojo-managed code folders. Refab is for serialized Studio content under place folders, not raw asset folders or source folders.

Install

Install the Roblox Studio plugin and the Refab CLI.

Rokit

Add Refab to rokit.toml:

[tools]
refab = "stupeak/refab@1.2.0"

Then install it:

rokit install

Install or update the local Roblox Studio plugin:

refab install-plugin

Restart Roblox Studio after installing or updating the plugin.

Manual

You can also download release files directly:

• Refab.rbxm
• the Refab CLI archive for your platform

Copy Refab.rbxm into your local Roblox plugins folder, then put the CLI binary somewhere on your PATH.

Start Refab from your Roblox project root:

refab run

For Developers

Development notes live outside this user README:

• AGENTS.md
• plugin/README.md
• cli/README.md