rojo/README.md

 

---

Atlas bridges Roblox Studio with Cursor/Claude, so large teams can collaborate on complex games with full project context.

Features

• Live Sync — Work on scripts and models from the filesystem with real-time sync to Roblox Studio
• Two-Way Sync — Push changes from the filesystem to Studio, or pull changes from Studio back to the filesystem
• Build & Upload — Package and deploy .rbxl, .rbxm, .rbxlx, and .rbxmx files from the command line
• Syncback — Pull an entire Roblox place into a local project with one command
• Clone — Create a full local project from any existing Roblox place: atlas clone PLACEID
• Cursor / VS Code Extension — JSON5 schema support, automatic CLI installation, bundled Luau tooling

Installation

The fastest way to get started is to install the Cursor or VS Code extension, which handles CLI installation automatically.

1. Install the Extension

• Cursor / Other: Open VSX Registry
• VS Code: VS Code Marketplace

The extension will prompt to install the Atlas CLI via Rokit and the Roblox Studio plugin if they aren't already on your system.

2. Alternative: Manual CLI Install

If you prefer not to use the extension, install the CLI directly:

Via Rokit (recommended):

rokit add --global UserGeneratedLLC/rojo atlas

Build from source:

git clone --recursive https://github.com/UserGeneratedLLC/rojo
cd rojo
cargo build --release

The binary is output to target/release/atlas (or atlas.exe on Windows).

Getting Started

Clone an Existing PlaceId

atlas clone 123456789              # Download and set up the project locally
atlas serve                        # Start live sync server for Roblox Studio

Then just:

atlas studio                         # Open the project in Roblox Studio
atlas cursor                         # Open the project in Cursor IDE

New Project

atlas init --kind place
atlas serve

Then in Roblox Studio, open the Atlas plugin widget and click Connect.

CLI Commands

Core

atlas serve [project]                # Start live sync server (default port: 34873)
atlas serve --port 8080              # Use a custom port
atlas build [project] -o out.rbxl    # Build to .rbxl, .rbxm, .rbxlx, or .rbxmx
atlas build --watch -o out.rbxl      # Rebuild automatically on file changes
atlas build --plugin Plugin.rbxm     # Build directly to Studio's plugins folder
atlas upload [project] --asset_id ID # Upload to Roblox (cookie or API key auth)

Project Management

atlas init                           # Initialize a new place project
atlas init --kind model              # Initialize a model project
atlas init --kind plugin             # Initialize a plugin project
atlas clone PLACEID                  # Clone a Roblox place into a new local project
atlas fmt-project [project]          # Reformat project file with sorted keys

Syncback

atlas syncback [project]             # Sync from a local .rbxl to the filesystem
atlas syncback -d PLACEID            # Download the place from Roblox first
atlas syncback --incremental         # Preserve existing file structure
atlas syncback --list                # Preview what will change (no writes)
atlas syncback --dry-run             # Simulate without writing files
atlas syncback --sourcemap           # Generate sourcemap.json after sync

atlas pull is an alias for atlas syncback.

Tooling

atlas sourcemap [project]            # Generate sourcemap.json for Luau LSP
atlas sourcemap --watch              # Regenerate on file changes
atlas plugin install                 # Install the Studio plugin
atlas plugin uninstall               # Remove the Studio plugin
atlas studio [project]               # Open the project in Roblox Studio
atlas cursor [path]                  # Open the project in Cursor IDE
atlas doc                            # Open documentation in the browser

Global Options

atlas --verbose                      # Enable debug logging (-v, -vv, -vvv)
atlas --color never                  # Disable colored output (auto | always | never)

Workflows

Cloning from an Existing Place

atlas clone 123456789

What happens:

1. Fetches the experience name from the Roblox API
2. Creates a project folder with a sanitized name
3. Initializes the project with atlas init
4. Downloads the place and runs syncback to write all instances to the filesystem
5. Commits the result if git was initialized

Updating from Roblox

If the place has been edited in Studio and you want to pull those changes back:

atlas syncback -d PLACEID

Or if you already have a local .rbxl file:

atlas syncback

Use --incremental to preserve your existing file layout, or omit it for a clean rebuild. Use --list or --dry-run to preview before committing to changes.

Shortcuts

Command	What it does
atlas studio	Opens the project's place in Roblox Studio (reads servePlaceIds from the project file)
atlas cursor	Opens the project directory in Cursor IDE

One-Shot Mode

One-Shot Sync is a plugin setting (enabled by default) that performs a single sync and then disconnects. When enabled:

• The project tree syncs once, then the plugin automatically disconnects
• All automatic outgoing writes are blocked — only changes you explicitly confirm are applied
• The sync lock is skipped, so any number of people can connect and work together simultaneously
• A 30-second safety timeout ensures the connection is cleaned up

To use persistent (continuous) sync instead, disable "One-Shot Sync" in the plugin settings.

Working with Teams

Atlas includes a sync lock to prevent conflicts when multiple people work on the same place in Team Create.

• A session lock (__Atlas_SessionLock in ServerStorage) is acquired when someone connects in persistent mode
• Only one user can actively sync at a time — others see a message indicating who holds the lock
• One-shot mode bypasses the lock, letting the whole team preview the synced state without conflicts

Recommended team workflow: One designated person syncs in persistent mode (one-shot disabled). Everyone else uses one-shot mode for quick, conflict-free previews.

MCP Integration (AI Agents)

atlas serve automatically hosts an MCP (Model Context Protocol) server on the same port as the API. This lets AI agents like Cursor and Claude Code trigger syncs to Roblox Studio programmatically.

Available Tools

Tool	Description
atlas_sync	Sync filesystem changes to Studio. Auto-accepts if all changes are pre-selected by git. Blocks until the user accepts or rejects if there are unresolved changes.

Adding to Cursor

Create or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "atlas": {
      "url": "http://localhost:34873/mcp"
    }
  }
}

If your project uses a custom port (via servePort in the project file), update the URL accordingly.

Adding to Claude Code

claude mcp add atlas --transport http http://localhost:34873/mcp

Or add it to your project-level config at .claude/settings.json:

{
  "mcpServers": {
    "atlas": {
      "type": "url",
      "url": "http://localhost:34873/mcp"
    }
  }
}

How It Works

1. Start atlas serve — the MCP server is available immediately
2. The Studio plugin connects to the MCP stream in the background (retries every 5s)
3. When an agent calls atlas_sync:
   • If all changes are pre-selected by the git system, they are auto-accepted (fast-forward)
   • If there are unresolved changes, the Confirming page appears in Studio for the user to review
   • The agent blocks until the sync completes and receives a list of synced file paths with directions (push/pull)
4. If the plugin is already connected in live sync mode, the tool returns immediately with a notice that sync is automatic

Requirements

• atlas serve must be running
• Roblox Studio must be open with the Atlas plugin installed
• The plugin does not need to be manually connected — the MCP stream connects automatically

File Formats

Scripts

Extension	Result	RunContext
*.luau	ModuleScript	—
*.server.luau	Script	Server
*.client.luau	Script	Client
*.plugin.luau	Script	Plugin
*.local.luau	LocalScript	—
*.legacy.luau	Script	Legacy

Data & Models

Extension	Result
*.json5	ModuleScript (Lua table)
*.toml	ModuleScript (Lua table)
*.yaml / *.yml	ModuleScript (Lua table)
*.csv	LocalizationTable
*.txt	StringValue
*.rbxm	Binary model
*.rbxmx	XML model
*.model.json5	JSON model

Metadata & Projects

Extension	Purpose
*.meta.json5	Add properties/attributes to a sibling instance
*.project.json5	Project file (or nested project)

Legacy .lua, .json, .meta.json, .model.json, and .project.json extensions are still supported.

Project Structure

A typical Atlas place project:

MyGame/
├── default.project.json5    # Project configuration
├── src/                     # Instance tree (synced to DataModel)
│   ├── ReplicatedStorage/
│   ├── ServerScriptService/
│   ├── ServerStorage/
│   ├── StarterGui/
│   ├── StarterPlayer/
│   └── Workspace/
├── rokit.toml               # Pins Atlas version for the project
└── .luaurc                  # Luau LSP configuration

Example default.project.json5:

{
  name: "MyGame",
  servePlaceIds: [123456789],
  tree: {
    $className: "DataModel",
    $path: "src"
  }
}

Troubleshooting

Plugin not connecting

• Ensure atlas serve is running
• Check that the port matches (default: 34873, or whatever servePort is set to in your project file)
• Verify the Atlas CLI version matches the plugin version (major.minor must agree)

Syncback produces unexpected results

• Use --list or --dry-run to preview changes before writing
• Try --incremental to preserve your existing file structure
• Check syncbackRules in your project file for ignored paths or classes

Build errors

• Run atlas fmt-project to fix JSON formatting issues
• Ensure all $path entries in the project file point to existing files/directories

Plugin shows "another user is syncing"

• Someone else holds the sync lock in Team Create
• Wait for them to disconnect, or use one-shot mode to preview without locking