SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsroblox-rojo

roblox-rojo

Coding & development

View repository

Updated 10-16 02:32

About this skill

roblox-rojo

Official sources:

Rojo maps a filesystem project to Roblox instances so you can edit with external tools (VS Code, Git, linters, formatters) and live-sync or build into Studio/place files. This skill covers Rojo 7 as documented at rojo.space and implemented in the current rojo-rbx/rojo release line.

Mental model

Piece Role
Rojo CLI Reads the project file + filesystem; serves live sync, builds place/model files, uploads, sourcemaps, syncback.
Studio plugin Connects to the local serve session and applies patches into the open place.
Project file *.project.json / *.project.jsonc describing the instance tree and options.
Filesystem tree Scripts, models, JSON/TOML/YAML/CSV/text under $path nodes become Instances.

Rojo is filesystem → Studio for live sync (one primary direction). Optional two-way sync in the plugin is experimental and incomplete. Do not design production workflows around it. For place → files, use rojo syncback (Rojo 7.7+) or external porting tools.

Quick start

  1. Install the CLI (Rokit recommended for projects; GitHub binaries or cargo install rojo --version ^7 also supported).
  2. Install the Studio plugin with rojo plugin install (or GitHub rbxm / Roblox.com plugin for the matching major).
  3. rojo init my-game (or open folder + VS Code "Rojo: Open Menu").
  4. rojo serve in the project folder.
  5. In Studio: open the Rojo plugin panel → Connect.
  6. Edit files on disk; watch them sync. Use rojo build -o build.rbxlx for a one-shot place file.

Full install matrix and CLI flags: references/installation-and-cli.md.

Script file → Instance mapping (defaults)

Both .lua and .luau are supported. Default rules (from Rojo source / sync docs):

File pattern Instance (when emitLegacyScripts is true, the default) Instance (when emitLegacyScripts is false)
*.server.lua(u) Script (legacy RunContext) Script with RunContext = Server
*.client.lua(u) LocalScript Script with RunContext = Client
*.plugin.lua(u) Script with RunContext = Plugin same
other *.lua(u) ModuleScript same

Init usurpers (replace the parent folder with a script): init.server.lua(u), init.client.lua(u), init.plugin.lua(u), init.lua(u). Only one init script type per folder. A directory with default.project.json / default.project.jsonc is treated as a nested project instead of a plain folder.

Other defaults: .rbxm/.rbxmx models, .model.json(c), plain .json(c) → ModuleScript returning a table, .toml / .yml/.yaml similarly, .csv → LocalizationTable, .txt → StringValue.

Details, meta files, limitations: references/sync-details.md.

Project file essentials

Minimal place-shaped tree (services inferred without $className for known services):

{
  "name": "MyGame",
  "tree": {
    "$className": "DataModel",
    "ReplicatedStorage": {
      "$path": "src/ReplicatedStorage"
    },
    "ServerScriptService": {
      "$path": "src/ServerScriptService"
    },
    "StarterPlayer": {
      "StarterPlayerScripts": {
        "$path": "src/StarterPlayerScripts"
      }
    }
  }
}

Important top-level fields (docs + current CLI):

Field Purpose
name Project/instance name (optional for default.project.json; folder name used).
tree Root instance description (required).
servePort Default port for rojo serve (default 34872).
serveAddress Default bind address when CLI --address omitted.
servePlaceIds / blockedPlaceIds Allow/deny live-sync targets by place ID.
placeId / gameId Set Studio place/universe IDs on connect.
serveAllowedHosts Extra Host/Origin values for serve (hostname access); CLI --allowed-hosts overrides.
globIgnorePaths Globs to ignore (gitignore-style negation supported in recent releases).
emitLegacyScripts Default true = Script/LocalScript; false = RunContext Scripts for server/client files.
syncRules Custom file→middleware patterns.
syncbackRules Controls rojo syncback behavior.

Instance nodes use $className, $path, $properties, $attributes, $ignoreUnknownInstances, plus child keys. Prefer implicit property syntax. Full format: references/project-format.md.

Daily commands

# New project (place | model | plugin)
rojo init my-game
rojo init --kind model
rojo init --kind plugin --skip-git

# Live sync (default localhost:34872)
rojo serve
rojo serve --port 34872 --address 127.0.0.1

# Build place/model
rojo build -o build.rbxlx
rojo build -o build.rbxl
rojo build --plugin MyPlugin.rbxm
rojo build -o out.rbxlx --watch

# Sourcemap for editor tooling
rojo sourcemap --output sourcemap.json
rojo sourcemap --watch --absolute

# Upload (prefer dedicated deploy account; never commit cookies/keys)
rojo upload --asset_id PLACE_ID --cookie "..."
rojo upload --asset_id PLACE_ID --api_key "..." --universe_id UNIVERSE_ID

# Place file → filesystem into an existing project tree
rojo syncback . --input place.rbxl
rojo syncback . --input place.rbxlx --dry-run --list

# Plugin management / docs / format
rojo plugin install
rojo plugin uninstall
rojo doc
rojo fmt-project

Live-sync limitations

Not all property types apply in real time (Studio plugin API limits). Common cases that may need a full build + open instead of live sync:

  • Binary data (Terrain, CSG)
  • MeshPart.MeshId
  • HttpService.HttpEnabled

Property type coverage for build vs live sync is documented on the Properties page and rbx-dom's coverage chart. When live sync fails for a class/property, rebuild with rojo build and open the place.

rojo serve binds to loopback by default. Binding to a network-reachable address exposes the session: recent Rojo versions validate Host/Origin, gate some APIs to local clients, and warn on non-local binds. Prefer localhost; if you must expose, use serveAllowedHosts / --allowed-hosts deliberately.

Porting existing games

  1. Refactor Studio code into fewer service-rooted locations (ReplicatedStorage, ServerScriptService, StarterPlayer, tags via CollectionService) before porting.
  2. Prefer rojo syncback with a project that already lists the services/paths you want filled (rojo syncback path/to/project --input place.rbxl). Only descendants of nodes present in the project tree are written.
  3. Alternatives called out in official docs: rbxlx-to-rojo, Lune for custom pipelines.
  4. Leaving Rojo is always possible: Rojo builds normal place/model files; you can stop using the filesystem tree and edit in Studio only.

Workflows and syncback rules: references/workflows-and-syncback.md.

Agent checklist

  • Do pin CLI + plugin to the same major (Rojo 7 plugin with Rojo 7 CLI).
  • Do run rojo plugin install after upgrading the CLI.
  • Do put shared modules under ReplicatedStorage paths and server authority under ServerScriptService.
  • Do use .luau (Rojo's init templates use .luau since 7.4).
  • Do set emitLegacyScripts: false only when the team understands modern RunContext scripts (and that client files become Script+Client, not LocalScript).
  • Do not invent CLI flags or project keys. If unsure, run rojo --help / rojo <cmd> --help or re-check docs/changelog.
  • Do not commit .ROBLOSECURITY cookies or Open Cloud API keys used with rojo upload.
  • Do not treat experimental two-way sync as reliable source control.
  • Do not confuse Rojo with Roblox Script Sync or Studio MCP. Different tools; they can coexist (see roblox-mcp).

Verification

  • rojo --version reports a 7.x release matching the intended pin.
  • Studio shows the Rojo 7 plugin; connect succeeds against rojo serve.
  • Editing a .server.luau under a mapped $path updates the correct service in Studio.
  • rojo build -o build.rbxlx opens cleanly in Studio.
  • sourcemap.json is gitignored if generated (Rojo's default gitignore template includes it in recent releases).

How to proceed

  1. Confirm install path: references/installation-and-cli.md.
  2. Shape the tree: references/project-format.md.
  3. Name files correctly: references/sync-details.md.
  4. For teams / porting / deploy: references/workflows-and-syncback.md.

Reference index