Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/brockmartin/roblox-game-skill/llms.txt

Use this file to discover all available pages before exploring further.

MCP orchestration is how the Roblox Game Skill drives Roblox Studio directly — creating instances, writing scripts, running playtests, reading console output, and fixing errors — without the developer ever leaving their editor. Rather than generating code for you to paste, Claude calls MCP tools in planned sequences: scaffolding the DataModel, generating server and client scripts, wiring RemoteEvents, inserting Creator Store assets, running a playtest, reading errors, and iterating until the build is clean. This document describes how that orchestration works: which server Claude detects, which tools it selects for each task, how autonomous build sequences are structured, and how errors are handled.
For a user-facing overview of MCP modes, see MCP Overview. For the full tool reference and connection instructions, see Full Mode.

Mode Detection

On every session start — or whenever Studio interaction is first requested — Claude probes the available tool names to determine which MCP server is connected and which operating mode to enter.
1

Probe for Community Server tools

Look for characteristic tool names from the community server (boshyxd/robloxstudio-mcp): execute_luau, get_file_tree, grep_scripts, create_build, search_objects, get_instance_properties, get_script_sourceIf any of these are present → enter Full Mode (39 tools available).
2

Probe for Official Server tools

If community tools are absent, look for tools from the official server (Roblox/studio-rust-mcp-server): run_code, insert_model, get_console_output, start_stop_play, run_script_in_play_mode, get_studio_modeIf these are present but community tools are not → enter Standard Mode (6 tools).
3

Fall back to Offline Mode

If neither server’s tools are detected → enter Offline Mode. Generate self-contained Luau code blocks with clear placement instructions for the developer to paste into Studio manually.

Detection Priority

If both servers are detected simultaneously, prefer the Community Server for its broader toolset (39 tools vs. 6). Fall back to individual Official Server tools only when a community equivalent is unavailable or failing.

Mode Capabilities at a Glance

Full Mode

Community Server — 39 toolsExploration, building, testing, asset management, bulk operations, history. Full autonomous build cycles without manual steps.

Standard Mode

Official Server — 6 toolsrun_code, insert_model, get_console_output, start_stop_play, run_script_in_play_mode, get_studio_mode. Capable but requires workarounds for exploration tasks.

Offline Mode

No MCP — 0 toolsClaude generates annotated copy-paste code blocks, directory structures, and setup checklists for manual execution.

Tool Selection Heuristics

Claude selects tools based on the task at hand, the current Studio mode, and which server is connected.

Full Mode Tool Selection

TaskPrimary ToolNotes
Understand project layoutget_file_treeget_project_structureAlways the first step in any project exploration
Find a specific instancesearch_objectsFilter by name or class
Read a script’s sourceget_script_sourceBefore editing; never overwrite blindly
Find all references to a symbolgrep_scriptsSearches across all scripts by pattern
Create or modify instancesexecute_luauPrimary workhorse — create folders, scripts, parts
Scaffold complex structurescreate_buildRooms, maps, hierarchical instance trees
Insert a Creator Store assetCreator Store searchinsertSearch first; confirm before inserting
Validate changes at runtimestart_playtestget_playtest_outputstop_playtestAlways in this order
Roll back a changeundoBefore and after bulk changes
Audit many instances at oncemass_get_propertyRead before bulk write

Standard Mode Adaptations

Standard Mode lacks all exploration tools. Compensate with run_code + get_console_output:
-- Mimic get_file_tree in Standard Mode
-- Run via run_code, then read with get_console_output
local function printTree(instance, indent)
    indent = indent or 0
    print(string.rep("  ", indent) .. instance.ClassName .. ": " .. instance.Name)
    for _, child in ipairs(instance:GetChildren()) do
        printTree(child, indent + 1)
    end
end
printTree(game)
-- Mimic search_objects — find all Scripts in the place
for _, v in game:GetDescendants() do
    if v:IsA("Script") or v:IsA("LocalScript") or v:IsA("ModuleScript") then
        print(v:GetFullName())
    end
end

Offline Mode Output Format

When no MCP server is connected, every script block gets a placement header:
-- ==============================================
-- SCRIPT: WeaponSystem
-- PLACE IN: ServerScriptService
-- TYPE: Script (server-side)
-- ==============================================

local WeaponSystem = {}
-- ... implementation ...
return WeaponSystem
For Rojo users, output a directory structure with default.project.json mapping included.

Pre-Operation Checks

Before any build or modification sequence, Claude verifies Studio state:
1

Check Studio mode

Call get_studio_mode (Standard Mode) or infer from context (Full Mode). Never execute build code while a playtest is active — changes to the DataModel during play mode are discarded when the session ends.
2

Create an undo waypoint

Before any bulk or destructive operation:
game:GetService("ChangeHistoryService"):SetWaypoint("Before: <description>")
3

Read before write

Always inspect a script’s current source with get_script_source before overwriting. Log the previous content or at least its key function names.
4

Verify instance existence

Before modifying, confirm the target path resolves to a real instance using search_objects or get_instance_properties.

Autonomous Build Sequence

A complete build cycle from a feature specification to a working, error-free game system. This sequence is what Claude executes in Full Mode when asked to scaffold a new game or add a major system.
1

Scaffold — Understand and Plan

get_file_tree → get_project_structure
Understand the current DataModel. Identify where new folders and scripts should go. Plan the instance hierarchy before writing anything.Then create the folder structure:
-- execute_luau: scaffold folders
local SSS = game:GetService("ServerScriptService")
local RS  = game:GetService("ReplicatedStorage")

local serverFolder = Instance.new("Folder")
serverFolder.Name  = "CombatSystem"
serverFolder.Parent = SSS

local sharedFolder = Instance.new("Folder")
sharedFolder.Name  = "CombatShared"
sharedFolder.Parent = RS
2

Generate Core Systems

For each system (combat, inventory, UI, etc.):
  • Generate the server scriptexecute_luau to create and populate a Script instance
  • Generate the client scriptexecute_luau to create and populate a LocalScript
  • Generate shared modulesexecute_luau to create and populate ModuleScript instances
Wire up RemoteEvent and RemoteFunction instances between client and server:
-- execute_luau: create remotes
local RS = game:GetService("ReplicatedStorage")
local remotes = Instance.new("Folder")
remotes.Name   = "Remotes"
remotes.Parent = RS

local damageEvent = Instance.new("RemoteEvent")
damageEvent.Name   = "DamageEvent"
damageEvent.Parent = remotes
3

Insert Assets

Search the Creator Store for needed models, audio, or meshes:
Creator Store search → details → thumbnail → insert
Position and configure inserted assets via execute_luau after insertion.
4

Test

start_playtest → (wait 5–10 seconds) → get_playtest_output → stop_playtest
Scan output for errors. If the output is clean, the build is complete.
5

Fix and Iterate

If errors are found:
grep_scripts (error keyword) → get_script_source → execute_luau (fix) → back to step 4
Cap at 5 iterations. If errors persist after 5 attempts, report findings and suggest manual investigation.

Debug Loop Pattern

Systematic error resolution used during testing and when fixing issues reported by the user.
1. DETECT
   ├── get_console_output / get_playtest_output  →  capture errors
   └── Parse: script name, line number, error type

2. LOCATE
   ├── grep_scripts with error-related keywords
   ├── get_script_source for the identified script
   └── Analyze surrounding code for root cause

3. FIX
   ├── Generate corrected code
   ├── execute_luau: SetWaypoint("Before fix: <error description>")
   └── execute_luau: replace the script source

4. VERIFY
   ├── start_playtest
   ├── get_playtest_output  →  check if error persists
   └── stop_playtest

5. ITERATE OR REPORT
   ├── If error persists and attempts < 5  →  return to step 2
   ├── If error resolved  →  report success
   └── If attempts >= 5   →  report findings, surface manual steps

Error Pattern Recognition

After reading get_playtest_output, scan for these high-priority patterns:
PatternMeaning
"attempt to index nil"A variable is nil where an object was expected — missing require or WaitForChild
"Infinite yield possible"WaitForChild didn’t find its target — wrong path or load-order issue
"is not a valid member"Property or child name is wrong — typo or renamed API
"HTTP 429"DataStore throttling — too many requests
"Script timeout"Infinite loop or blocking operation on the main thread
"attempt to call a nil value"Calling a function that doesn’t exist — bad require or wrong method name

Bulk Modification Pattern

Safe large-scale changes across many instances.
1

Search and audit

search_objects / search_by_property → identify all targets
mass_get_property → read current values for audit
2

Plan and checkpoint

Review the affected instance count and sample values. Then create an undo waypoint:
game:GetService("ChangeHistoryService"):SetWaypoint("Before bulk edit")
3

Execute in batches

-- execute_luau: apply changes in a loop
for _, part in workspace:GetDescendants() do
    if part:IsA("Part") and part.Name == "Floor" then
        part.Material = Enum.Material.SmoothPlastic
        part.BrickColor = BrickColor.new("Medium stone grey")
    end
end
Apply changes in batches if the instance count exceeds 100.
4

Verify

mass_get_property → confirm new values
get_instance_properties → spot-check a few instances

Project Exploration Pattern

Understanding an unfamiliar place file before making any changes.
1. STRUCTURE
   ├── get_file_tree          →  full instance hierarchy
   └── get_project_structure  →  high-level service layout

2. SCRIPTS
   ├── search_objects (ClassName = "Script" / "LocalScript" / "ModuleScript")
   ├── get_script_source for key scripts (entry points, main services)
   └── grep_scripts for "require", "RemoteEvent", "BindableEvent"

3. ARCHITECTURE
   ├── Map module dependencies (who requires whom)
   ├── Map client-server communication (RemoteEvents, RemoteFunctions)
   └── Identify data flow (DataStores, player data, state management)

4. REPORT
   └── Summarize: services used, script count, system architecture, potential issues

Safety Guidelines

Never call :ClearAllChildren() on services (Workspace, ServerScriptService, etc.) without explicit user confirmation. Deleting anonymous/temporary instances is fine; deleting named or significant ones requires confirmation.
ScenarioRule
Studio is in Play modeStop the playtest before modifying the DataModel
Bulk deleteCreate undo waypoint first; confirm with user for named/significant instances
Script overwriteRead current source with get_script_source before replacing
Experimental changeCreate undo waypoint; use undo if the result is wrong
Running code in play modeUse run_script_in_play_mode (Official); use get_playtest_output for results

Common Anti-Patterns

Wrong:
execute_luau("workspace.Part.Position = Vector3.new(0, 10, 0)")
-- Might fail silently if Studio is in Play mode
Right:
1. get_studio_mode  →  confirm Edit mode
2. execute_luau(...)
Wrong:
-- No recovery possible
for _, v in workspace:GetDescendants() do
    if v:IsA("Part") then v:Destroy() end
end
Right:
1. execute_luau: ChangeHistoryService:SetWaypoint("Before cleanup")
2. execute_luau: perform the bulk delete
3. Verify results; call undo if wrong
Wrong:
-- Calling grep_scripts when only the Official server is connected
-- Tool will not be found; operation silently fails
Right:
1. Detect which server is available (see Mode Detection above)
2. Use only tools confirmed to exist for that mode
3. Fall back to run_code + get_console_output workarounds in Standard Mode
Wrong:
execute_luau: set script.Source to entirely new code without reading the original
-- Loses existing work, custom modifications, and comments
Right:
1. get_script_source  →  read current implementation
2. Understand what exists
3. Merge new logic with existing code, or confirm full replacement with the user
Wrong:
1. execute_luau(code)
2. Assume success and move on
Right:
1. execute_luau(code)
2. Check the return value and console output for errors
3. If error detected: enter the Debug Loop pattern

Build docs developers (and LLMs) love