# StudioSync

Real-time, **zero-config** sync between Roblox Studio and VS Code — with a
local REST API that AI agents (Claude Code, scripts, anything that can curl)
can use to read and edit your game.

- Folders map 1:1 to Roblox services. No `project.json` to write — the only
  config file, `.studiosync.json`, is machine-generated.
- Two-way live sync of scripts: type in Studio, the file updates; save in
  VS Code, the open Studio editor updates. Create/delete/rename/move sync in
  both directions too.
- Safe initial handshake: when the project and the place differ you choose
  **Pull / Push / Merge**, and anything overwritten is backed up to
  `.studiosync/backups/` first. Push is a single undo step in Studio.
- Auto-reconnect keyed by PlaceId. Open the project and the place — they find
  each other.

```
MyGame/
├── ReplicatedStorage/
│   └── Shared/
│       └── Hello.luau            → ModuleScript
├── ServerScriptService/
│   └── Main.server.luau          → Script
└── StarterPlayer/
    └── StarterPlayerScripts/
        └── Client.client.luau    → LocalScript
```

## Install

- **Roblox Studio plugin:** [Creator Store asset 86309040336609](https://create.roblox.com/store/asset/86309040336609) — install via Studio's Toolbox/Plugins.
- **VS Code extension:** download `StudioSync-<version>.vsix` from the GitHub
  Releases page, then in VS Code: Extensions sidebar → `···` menu →
  **Install from VSIX** (or `code --install-extension StudioSync-x.y.z.vsix`).

Both sides check versions on every connection: an outdated Studio plugin shows
an orange update banner in its widget, and an outdated extension gets a VS
Code notification. The pair always states which side to update.

## Install (development)

Requirements: Node.js ≥ 20, Roblox Studio, VS Code.

```sh
npm install
npm run dev        # builds + installs the Studio plugin, watches everything
```

Then:

1. Press **F5** in VS Code (opens the Extension Development Host).
2. In the dev host, open an empty folder and run
   **StudioSync: Create Project** from the command palette.
3. Open your place in Roblox Studio. The StudioSync plugin (installed into
   your local Plugins folder by `npm run dev`) starts looking for VS Code
   automatically.
4. First time only: Studio asks you to allow the plugin's HTTP requests —
   allow `127.0.0.1` in Plugins → Manage Plugins.
5. Approve the connection in VS Code, pick a sync direction if the two sides
   differ, and you're live.

## The AI-friendly API

While the extension runs, a local REST API is available (default
`http://127.0.0.1:34873` — the real port is in `.studiosync.json`):

```sh
curl localhost:34873/api/status
curl localhost:34873/api/explorer
curl "localhost:34873/api/script?path=ReplicatedStorage/Shared/Hello"
curl -X POST localhost:34873/api/script \
  -H 'Content-Type: application/json' \
  -d '{"path":"ReplicatedStorage/Shared/Hello","source":"return 42"}'
curl "localhost:34873/api/search?q=Hello"
```

Every mutation flows through the same sync pipeline, so it lands in the
project files **and** in Roblox Studio simultaneously. `GET /` serves the full
API reference (also in [docs/api.md](docs/api.md)).

**MCP:** the server also speaks Model Context Protocol at `/mcp` — register
it once and Claude Code (or any MCP client) gets 15 native StudioSync tools:

```sh
claude mcp add studiosync --transport http http://127.0.0.1:34873/mcp
```

## Packages (Wally)

```sh
# in VS Code: StudioSync: Add Package  →  sleitnick/signal@^2.0.0
```

Packages install from the public Wally registry into
`ReplicatedStorage/Packages` (standard Wally linker layout, transitive
dependencies included) and sync into Studio like any other files:
`require(ReplicatedStorage.Packages.Signal)`. Manifest: `packages.json`.

## Templates

**StudioSync: Create Project** is a setup wizard: pick a template (Empty,
Simulator, FPS, RPG, Tycoon, or Fusion — the last one auto-installs the
Fusion package), pick an instance-storage mode, done. Drop your own template
folders into `~/.studiosync/templates/` and they appear in the list.

## Explorer view

The **StudioSync** icon in the activity bar opens a live, Roblox-style
Explorer of your place: every synced instance with class-aware icons.
Right-click to create/rename/delete instances, edit attributes, or reveal in
Studio; drag-and-drop to move. It renders the exact same tree the AI reads
via `get_explorer` / `/api/explorer` — human and AI share one live view.

## Repository layout

| Path | What |
|---|---|
| `extension/` | VS Code extension (TypeScript): HTTP server, sync engine, file watcher, REST API |
| `plugin/` | Roblox Studio plugin (Luau): watchers, applier, long-poll client, UI |
| `tools/` | Plugin packer (Luau → `.rbxmx`), installer, dev loop |
| `docs/` | [protocol.md](docs/protocol.md) · [mapping.md](docs/mapping.md) · [api.md](docs/api.md) |

`plugin/src/Protocol.luau` is generated from
`extension/src/core/protocol.ts` at build time — one source of truth for the
wire protocol. The plugin source layout is Rojo-compatible
(`plugin/default.project.json`) if you prefer `rojo build`.

## Commands

- `npm run build` — build extension + plugin
- `npm run dev` — watch mode for both, auto-installs the plugin
- `npm test` — unit tests + an end-to-end protocol simulation
- `npm run package` — produce the `.vsix` and `.rbxmx` artifacts
- `npm run release` — build, test, and stage versioned release artifacts in
  `dist/` (with SHA256SUMS) ready to attach to a GitHub release; pushing a
  `v*` tag does the same automatically via GitHub Actions

## MVP scope

Syncs **Script / LocalScript / ModuleScript / Folder**. Properties,
attributes, tags, non-script instances, packages, and templates are planned
next phases (see `docs/`). Team Create is not supported yet. Windows and
macOS.