mirror of
https://github.com/rojo-rbx/rojo.git
synced 2026-10-23 22:11:38 +00:00
c47e568cd4
- Changed project name from Rojo to Atlas in the README, reflecting the new branding. - Expanded the README with detailed installation instructions, features, and CLI commands for Atlas. - Added functionality in the CLI clone command to change the current working directory to the specified path after cloning. These updates aim to improve documentation clarity and enhance user experience with the Atlas tool.
278 lines
9.6 KiB
Markdown
278 lines
9.6 KiB
Markdown
<div align="center">
|
|
<a href="https://github.com/UserGeneratedLLC/rojo"><img src="assets/brand_images/logo-512.png" alt="Atlas" height="217" /></a>
|
|
</div>
|
|
|
|
<div> </div>
|
|
|
|
<div align="center">
|
|
<a href="https://github.com/UserGeneratedLLC/rojo/actions"><img src="https://github.com/UserGeneratedLLC/rojo/workflows/CI/badge.svg" alt="CI status" /></a>
|
|
<a href="https://marketplace.visualstudio.com/items?itemName=UserGeneratedLLC.vscode-roblox-atlas"><img src="https://img.shields.io/badge/VS%20Code-Marketplace-blue" alt="VS Code Marketplace" /></a>
|
|
<a href="https://open-vsx.org/extension/UserGeneratedLLC/vscode-roblox-atlas"><img src="https://img.shields.io/badge/Open%20VSX-Registry-purple" alt="Open VSX Registry" /></a>
|
|
</div>
|
|
|
|
<hr />
|
|
|
|
**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.
|
|
|
|
## 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
|