# Roblox AI Agents

Give Claude, Codex, Cursor, Gemini CLI, and other coding agents a real bridge into Roblox Studio.

Roblox AI Agents is a local MCP server plus a Roblox Studio plugin. Your agent can inspect the open place, draft a SceneSpec, generate terrain, create map geometry, write safe Luau, mirror code into Rojo, validate the result, and iterate inside Studio instead of pretending a `.rbxl` file is enough.

```text
Prompt -> SceneSpec -> dry run -> apply in Studio -> validate -> playtest
```

## Install for agents

Claude Code:

```sh
/plugin marketplace add ShiroKSH/roblox-ai-agents
/plugin install roblox-ai-agents@roblox-ai-agents
```

Codex, Cursor, Copilot, Gemini CLI, and other Agent Skills hosts:

```sh
npx skills add ShiroKSH/roblox-ai-agents -g
```

`-g` installs the skill globally for your user. Drop it to install into the current project.

The skill teaches agents the Roblox build workflow. The local bridge still needs to run from this repo:

```sh
git clone https://github.com/ShiroKSH/roblox-ai-agents.git
cd roblox-ai-agents
npm install
npm run build
```

## Install the Studio plugin

Requirements:

- Node.js 20+
- Roblox Studio
- Rojo, for plugin builds

Build the plugin:

```sh
npm run build:plugin
```

Copy `dist/RobloxAIAgents.rbxm` into your Roblox local plugins folder:

- Windows: `%LOCALAPPDATA%\Roblox\Plugins`
- macOS: `~/Documents/Roblox/Plugins`

Manual fallback: create a local Studio plugin from `plugin/src/init.lua` and add the files in `plugin/src/Bridge` as child ModuleScripts under a `Bridge` folder.

## Start the bridge

Create a local token:

```sh
cp .env.example .env
```

Edit `.env` and set `ROBLOX_AI_AGENTS_TOKEN` to a random local value. Do not use Roblox credentials.

Start the MCP server:

```sh
npm run build
node packages/mcp-server/dist/index.js
```

If no token is set, the server prints a one-time token to stderr. Paste it into the Studio plugin.

## Connect Codex

```sh
codex mcp add roblox-studio -- node packages/mcp-server/dist/index.js
```

Example `config.toml`:

```toml
[mcp_servers.roblox-studio]
command = "node"
args = ["packages/mcp-server/dist/index.js"]
startup_timeout_sec = 15
tool_timeout_sec = 120
default_tools_approval_mode = "prompt"
```

## Connect Studio

1. Open Roblox Studio.
2. Enable HTTP requests for the place.
3. Open the `Roblox AI Agents` plugin panel.
4. Use host `127.0.0.1`, port `3765`, and the same token as the MCP server.
5. Click `Connect`.

Verify from your agent:

```text
studio_ping
```

The response should include plugin version, place name, place id, and `Connected`.

## What it can build

- Blockouts, obbies, arenas, cabins, streets, training maps, and playable grayboxes.
- Terrain and pathing through Studio APIs.
- Doors, buttons, lifts, teleporters, checkpoints, and scoped runtime scripts.
- Batched Studio edits with Undo support.
- Rojo artifacts under `generated/rojo/<mapName>` when `codegen.target` is `rojo` or `both`.
- Validation passes for safe roots, spawn points, anchoring, terrain penetration, stair clearance, doorways, and common map-readiness issues.

## Evolution sample

These are cropped Roblox viewport shots from the local build process, with desktop UI, downloads, chats, tokens, and personal data removed.

| V1 first pass | V4 roof pass |
| --- | --- |
| ![V1 night cabin first pass](assets/evolution/v1-night-pass.png) | ![V4 cabin roof pass](assets/evolution/v4-exterior-pass.png) |

| V4 balcony detail | V4 window detail |
| --- | --- |
| ![V4 balcony detail](assets/evolution/v4-balcony-detail.png) | ![V4 window detail](assets/evolution/v4-window-detail.png) |

| Latest playtest frame | Latest station detail |
| --- | --- |
| ![Latest Roblox playtest frame](assets/evolution/latest-playtest.png) | ![Latest Roblox station detail](assets/evolution/latest-station-detail.png) |

## Build workflow

1. Convert the request into a SceneSpec. Set `rootPath` to `Workspace/MapDrafts`.
2. Use named levels, areas, folders, and models. Keep instance names unique.
3. Use `functionalObjects` for doors, buttons, lifts, teleporters, and checkpoints.
4. Set `codegen.target` to `both` when Luau should be written into Studio and mirrored into Rojo.
5. Run `map_apply_scene_spec` with `dryRun=true`.
6. Review target root, object count, touched services, and risks.
7. Run `map_apply_scene_spec` with `dryRun=false`.
8. Run `map_validate` with `strictGeometry=true`.
9. Run `map_readiness_check` with the matching profile when the map is meant to be playable.
10. Playtest in Studio and check plugin output before calling the map ready.

Use `examples/simple-obby.scene.json` for a minimal SceneSpec. The map root will be `Workspace/MapDrafts/<mapName>_<timestamp>`. A filesystem manifest is written under `logs/manifests/.../map_manifest.json`, and a `SceneManifest` StringValue is placed under the map root.

For in-place repair, use `studio_patch_instances` instead of one-off apply scripts. For inspection, move the Studio viewport with `studio_focus_instance` or `studio_set_camera`, then use `studio_visual_probe` to raycast what the camera sees.

## Safety defaults

- Localhost only.
- Shared token required.
- Dangerous Luau disabled by default.
- Deletes require `confirmToken`.
- New build writes stay under `Workspace/MapDrafts`.
- Legacy `Workspace/AI_Generated` paths are for migration only.
- Command logs redact tokens, source, and code.
- Roblox credentials and `.ROBLOSECURITY` are never needed.

## Final result

The point is not a text-only plan. The agent can keep pushing real Studio geometry until the place looks like an actual Roblox build:

![Final AI-built Roblox playtest frame](assets/evolution/latest-playtest.png)

## Development

```sh
npm install
npm run build
npm test
npm run validate:skill
```

More detail:

- [Contributing](CONTRIBUTING.md)
- [Protocol](docs/protocol.md)
- [SceneSpec schema](docs/scene-spec.schema.json)
- [Safety](docs/safety.md)
- [Troubleshooting](docs/troubleshooting.md)