Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Chrrxs/robloxstudio-mcp/llms.txt

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

The instance-editing tools give an AI agent full control over the DataModel hierarchy — creating new instances, deleting existing ones, cloning or duplicating instances with configurable offsets and variations, and reverting changes with undo/redo. These tools work on the edit DataModel, so every change is visible immediately in the Studio viewport and is recorded in ChangeHistoryService, making it reversible with a single undo call.

​
create_object

Create a new instance of any creatable Roblox class. Optionally assign a name and set initial properties in the same call, avoiding a follow-up set_properties round-trip.
​
className
string
required
The Roblox class name of the instance to create (e.g. "Part", "RemoteEvent", "Script", "Folder").
​
parent
string
required
Canonical DataModel path of the parent instance (e.g. "game.Workspace", "game.ServerScriptService").
​
name
string
Name for the new instance. If omitted, Roblox assigns the class default name.
​
properties
object
Map of property names to initial values. Applied immediately on creation. Follows the same type conventions as set_property (primitives or typed objects for Vector3/Color3/UDim2).
​
instance_id
string
Which connected Studio place to target. Required when multiple places are connected; omit when only one is open. Use get_connected_instances to list available IDs.
// Create an anchored red part at a specific position
{
  "className": "Part",
  "parent": "game.Workspace",
  "name": "SpawnPlatform",
  "properties": {
    "Anchored": true,
    "Size": { "x": 10, "y": 1, "z": 10 },
    "Position": { "x": 0, "y": 0.5, "z": 0 },
    "BrickColor": "Bright red"
  }
}

​
mass_create_objects

Create multiple instances in a single call. Each entry in the objects array has the same shape as a create_object call — class, parent, optional name, and optional properties. All instances are created atomically, minimising round-trips for large hierarchy builds.
​
objects
array
required
Array of object descriptors. Each entry must include:
  • className (string, required)
  • parent (string, required)
  • name (string, optional)
  • properties (object, optional)
​
instance_id
string
Which connected Studio place to target. Required when multiple places are connected.
// Create a folder structure with two RemoteEvents in one call
{
  "objects": [
    {
      "className": "Folder",
      "parent": "game.ReplicatedStorage",
      "name": "Events"
    },
    {
      "className": "RemoteEvent",
      "parent": "game.ReplicatedStorage.Events",
      "name": "RoundStart"
    },
    {
      "className": "RemoteEvent",
      "parent": "game.ReplicatedStorage.Events",
      "name": "RoundEnd"
    }
  ]
}

​
delete_object

Delete an instance and all its descendants from the DataModel. The deletion is recorded in ChangeHistoryService and can be reversed with undo.
​
instancePath
string
required
Canonical DataModel path of the instance to delete.
​
instance_id
string
Which connected Studio place to target. Required when multiple places are connected.
Deleting an instance also deletes all its descendants. Call get_descendants or get_instance_children first if you need to verify the subtree before committing to a deletion.

​
smart_duplicate

Duplicate an instance a specified number of times with full control over naming, spatial layout, and per-duplicate property variations. This is the primary tool for procedural scene population — spawning grids of NPCs, rows of street lights, sequences of platforms, and so on.
​
instancePath
string
required
Canonical DataModel path of the source instance to duplicate.
​
count
number
required
Number of duplicate copies to create.
​
options.namePattern
string
Name pattern for each duplicate. Use {n} as a placeholder for the 1-based duplicate index (e.g. "NPC_{n}" produces NPC_1, NPC_2, …).
​
options.positionOffset
number[]
[x, y, z] offset applied cumulatively to each successive duplicate. The first copy is offset by this amount once, the second copy by twice the amount, and so on.
​
options.rotationOffset
number[]
[x, y, z] rotation offset in degrees applied cumulatively per duplicate.
​
options.scaleOffset
number[]
[x, y, z] scale multiplier applied cumulatively per duplicate.
​
options.propertyVariations
object
A map of property name → array of values. Each duplicate picks the value at its index in the array (wrapping around if there are fewer values than duplicates). Use this to give each copy a different colour, size, or speed.
​
options.targetParents
string[]
Array of canonical DataModel paths — one per duplicate. When provided, each copy is placed under the corresponding parent instead of the source’s parent.
​
instance_id
string
Which connected Studio place to target. Required when multiple places are connected.

​
Example: spawn 50 NPCs in a 10×5 grid

The source NPC is at game.Workspace.NPCs.NPC_Template. Each row is 5 NPCs wide with 8 studs between columns, and 5 rows deep with 8 studs between rows. Use positionOffset along the X axis for columns and a propertyVariations trick for rows, or simply precalculate row offsets in batches of 10 with mass_duplicate. 
// Step 1 — duplicate the template 10 times along X (one row of 10)
{
  "instancePath": "game.Workspace.NPCs.NPC_Template",
  "count": 49,
  "options": {
    "namePattern": "NPC_{n}",
    "positionOffset": [8, 0, 0]
  }
}
For a true 10×5 grid (50 NPCs), call mass_duplicate with two separate operations — one for each row offset — or compute targetParents to place each NPC into a row folder. Here is the mass_duplicate approach covering all 50 NPCs across 5 rows: 
{
  "duplications": [
    { "instancePath": "game.Workspace.NPCs.NPC_Template", "count": 10, "options": { "namePattern": "Row1_NPC_{n}", "positionOffset": [8, 0, 0] } },
    { "instancePath": "game.Workspace.NPCs.NPC_Template", "count": 10, "options": { "namePattern": "Row2_NPC_{n}", "positionOffset": [8, 0, 0], "targetParents": ["game.Workspace.NPCs", "game.Workspace.NPCs", "game.Workspace.NPCs", "game.Workspace.NPCs", "game.Workspace.NPCs", "game.Workspace.NPCs", "game.Workspace.NPCs", "game.Workspace.NPCs", "game.Workspace.NPCs", "game.Workspace.NPCs"] } }
  ]
}
For grid layouts, combine positionOffset along one axis with mass_duplicate rows staggered along the other axis. Each row is a separate smart_duplicate entry inside duplications.

​
mass_duplicate

Batch multiple smart_duplicate operations into a single tool call. Use when you need to populate different areas of the map in one round-trip, or when a 2D grid requires separate row operations with different Z offsets.
​
duplications
array
required
Array of duplication descriptors. Each entry has the same shape as a smart_duplicate call (instancePath, count, optional options).
​
instance_id
string
Which connected Studio place to target. Required when multiple places are connected.

​
clone_object

Create a deep copy of an instance — including all its descendants — and parent the clone under a new location. Unlike smart_duplicate, clone_object creates exactly one copy and lets you choose any parent in the DataModel.
​
instancePath
string
required
Canonical path of the instance to clone.
​
targetParentPath
string
required
Canonical path of the parent to place the cloned copy under.
​
instance_id
string
Which connected Studio place to target. Required when multiple places are connected.
// Clone a template NPC from ServerStorage into the Workspace
{
  "instancePath": "game.ServerStorage.Templates.NPC_Goblin",
  "targetParentPath": "game.Workspace.NPCs"
}

​
undo

Undo the last change recorded by ChangeHistoryService in the target Studio place. Equivalent to pressing Ctrl+Z in Studio.
​
instance_id
string
Which connected Studio place to target. Required when multiple places are connected.

​
redo

Reapply the most recently undone change recorded by ChangeHistoryService. Equivalent to pressing Ctrl+Y / Ctrl+Shift+Z in Studio.
​
instance_id
string
Which connected Studio place to target. Required when multiple places are connected.
undo and redo operate on the Studio ChangeHistoryService stack, which records tool-level operations. A single mass_create_objects or smart_duplicate call is recorded as one operation, so one undo reverses the entire batch.

Build docs developers (and LLMs) love

Get started for freeTalk to us