**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](https://open-vsx.org/extension/UserGeneratedLLC/vscode-roblox-atlas)
- **VS Code**: [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=UserGeneratedLLC.vscode-roblox-atlas)
The extension will prompt to install the Atlas CLI via [Rokit](https://github.com/rojo-rbx/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):**
```bash
rokit add --global UserGeneratedLLC/rojo atlas
```
**Build from source:**
```bash
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
```bash
atlas clone 123456789 # Download and set up the project locally
atlas serve # Start live sync server for Roblox Studio
```
Then just:
```bash
atlas studio # Open the project in Roblox Studio
atlas cursor # Open the project in Cursor IDE
```
## New Project
```bash
atlas init --kind place
atlas serve
```
Then in Roblox Studio, open the Atlas plugin widget and click **Connect**.
## CLI Commands
### Core
```bash
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
```bash
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
```bash
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
```bash
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
```bash
atlas --verbose # Enable debug logging (-v, -vv, -vvv)
atlas --color never # Disable colored output (auto | always | never)
```
## Workflows
### Cloning from an Existing Place
```bash
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:
```bash
atlas syncback -d PLACEID
```
Or if you already have a local `.rbxl` file:
```bash
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:
```json
{
"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
```bash
claude mcp add atlas --transport http http://localhost:34873/mcp
```
Or add it to your project-level config at `.claude/settings.json`:
```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`:
```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
