Roblox AI Agents

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.

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

Install for agents

Claude Code:

/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:

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:

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:

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:

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:

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

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

Example config.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:

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

V4 balcony detail	V4 window detail

Latest playtest frame	Latest station detail

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:

Development

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

More detail:

• Contributing
• Protocol
• SceneSpec schema
• Safety
• Troubleshooting