@el4cteo/rbx-studio-mcp 0.7.0 → 0.7.2

package/plugin/src/handlers/Anim.luau

@@ -130,22 +130,6 @@ local function flatten(node: Instance, prefix: string, into: { { [string]: any }
 	end
 end
 
---[[
-	Which rig an animation was made for, read off the joints it moves.
-
-	This matters more than it sounds. An R15 animation played on an R6 character
-	does nothing at all -- no error, no warning, no movement -- because the joint
-	names it addresses ("LeftUpperArm") do not exist on that rig ("Left Arm").
-	It is one of the quietest failures on the platform, and the asset id carries
-	no hint of which kind it is.
-
-	The two skeletons are told apart by naming rather than by counting. R6 uses
-	six limbs with spaces in their names, unchanged since 2007. R15 splits each
-	limb in two and writes them without spaces. Anything that matches neither is
-	a custom rig, and is reported as such rather than guessed at -- a wrong
-	confident answer here is worse than "unknown", because the whole point of
-	the field is to be trusted.
-]]
 --[[
 	Which joint hangs off which, for the two rigs Roblox ships.
 
@@ -207,6 +191,22 @@ local R15_PARTS = {
 	RightLowerArm = true,
 }
 
+--[[
+	Which rig an animation was made for, read off the joints it moves.
+
+	This matters more than it sounds. An R15 animation played on an R6 character
+	does nothing at all -- no error, no warning, no movement -- because the joint
+	names it addresses ("LeftUpperArm") do not exist on that rig ("Left Arm").
+	It is one of the quietest failures on the platform, and the asset id carries
+	no hint of which kind it is.
+
+	The two skeletons are told apart by naming rather than by counting. R6 uses
+	six limbs with spaces in their names, unchanged since 2007. R15 splits each
+	limb in two and writes them without spaces. Anything that matches neither is
+	a custom rig, and is reported as such rather than guessed at -- a wrong
+	confident answer here is worse than "unknown", because the whole point of
+	the field is to be trusted.
+]]
 local function rigOf(joints: { [string]: boolean }): (string, string?)
 	local r6, r15 = 0, 0
 	for joint in joints do
@@ -418,21 +418,6 @@ function Anim.read(params: { [string]: any }): { [string]: any }
 	}
 end
 
---[[
-	Builds a KeyframeSequence in memory and registers it for playback.
-
-	The registration is what makes this more than an instance tree: it returns a
-	content id that an Animation can use immediately, in this Studio, with no
-	upload and no moderation wait. That is the whole loop an agent needs to try
-	an idea -- build, set AnimationId, look -- and it is entirely reversible,
-	because nothing left the session.
-
-	Poses arrive flat, named by joint, and are nested under one root pose here.
-	Flat is what a caller can write and nesting is what the engine resolves, and
-	the rig's own hierarchy is not knowable from a list of joint names -- so a
-	single root is the honest structure: it animates the named joints and claims
-	nothing about how they connect.
-]]
 --[[
 	The joint tree to nest poses against.
 
@@ -477,6 +462,21 @@ local function parentMap(params: { [string]: any }, joints: { [string]: boolean
 	return R6_PARENT, "R6"
 end
 
+--[[
+	Builds a KeyframeSequence in memory and registers it for playback.
+
+	The registration is what makes this more than an instance tree: it returns a
+	content id that an Animation can use immediately, in this Studio, with no
+	upload and no moderation wait. That is the whole loop an agent needs to try
+	an idea -- build, set AnimationId, look -- and it is entirely reversible,
+	because nothing left the session.
+
+	Poses arrive flat, named by joint, and are nested under one root pose here.
+	Flat is what a caller can write and nesting is what the engine resolves, and
+	the rig's own hierarchy is not knowable from a list of joint names -- so a
+	single root is the honest structure: it animates the named joints and claims
+	nothing about how they connect.
+]]
 function Anim.build(params: { [string]: any }): { [string]: any }
 	local frames = params.keyframes
 	if typeof(frames) ~= "table" or #(frames :: { any }) == 0 then
@@ -636,25 +636,6 @@ function Anim.build(params: { [string]: any }): { [string]: any }
 	}
 end
 
---[[
-	Plays an animation on a real rig, in edit mode, so it can be looked at.
-
-	`read` says what an animation contains and `build` makes one; neither answers
-	"does it look right", which for a piece of motion is most of the question.
-	Measured: an `Animator` loads and plays a track in an ordinary edit session
-	-- `Length` comes back populated and `IsPlaying` is true -- so the rig in the
-	place can be posed without pressing Play.
-
-	The frame is the point. Playing an animation and returning immediately shows
-	whatever pose the rig happened to be in, so this seeks to a chosen moment and
-	holds it there: play, jump to `at`, pause. Then `screenshot` sees that exact
-	pose, and asking for three different moments gives three comparable frames.
-
-	Deliberately leaves the rig posed rather than restoring it. The whole purpose
-	is to leave something on screen to photograph, and a tool that tidied up
-	before returning would always photograph the idle pose. `op="stop"` puts it
-	back.
-]]
 --[[
 	Puts a rig back the way it was before anything was played on it.
 
@@ -722,6 +703,25 @@ local function restPose(model: Instance, animator: Animator)
 	animator:StepAnimations(1 / 60)
 end
 
+--[[
+	Plays an animation on a real rig, in edit mode, so it can be looked at.
+
+	`read` says what an animation contains and `build` makes one; neither answers
+	"does it look right", which for a piece of motion is most of the question.
+	Measured: an `Animator` loads and plays a track in an ordinary edit session
+	-- `Length` comes back populated and `IsPlaying` is true -- so the rig in the
+	place can be posed without pressing Play.
+
+	The frame is the point. Playing an animation and returning immediately shows
+	whatever pose the rig happened to be in, so this seeks to a chosen moment and
+	holds it there: play, jump to `at`, pause. Then `screenshot` sees that exact
+	pose, and asking for three different moments gives three comparable frames.
+
+	Deliberately leaves the rig posed rather than restoring it. The whole purpose
+	is to leave something on screen to photograph, and a tool that tidied up
+	before returning would always photograph the idle pose. `op="stop"` puts it
+	back.
+]]
 function Anim.preview(params: { [string]: any }): { [string]: any }
 	local rigPath = params.rig
 	if typeof(rigPath) ~= "string" or rigPath == "" then

package/plugin/src/handlers/Character.luau

@@ -178,14 +178,6 @@ local function takeControl(model: Model): boolean
 	return ok
 end
 
---[[
-	Walks to a point, following a computed path around obstacles.
-
-	Reports where it ended up rather than only whether the call returned, because
-	`MoveTo` succeeds at being asked and says nothing about arriving. A route
-	blocked by a wall the agent did not know about looks identical to a
-	successful walk unless the final distance is measured.
-]]
 --[[
 	Agent settings, shared by the route check and the walk.
 
@@ -336,6 +328,14 @@ function Character.path(params: { [string]: any }): { [string]: any }
 	}
 end
 
+--[[
+	Walks to a point, following a computed path around obstacles.
+
+	Reports where it ended up rather than only whether the call returned, because
+	`MoveTo` succeeds at being asked and says nothing about arriving. A route
+	blocked by a wall the agent did not know about looks identical to a
+	successful walk unless the final distance is measured.
+]]
 function Character.moveTo(params: { [string]: any }): { [string]: any }
 	local model, humanoid = humanoidOf(params)
 

package/plugin/src/handlers/Discover.luau

@@ -184,10 +184,6 @@ function Discover.tree(params: { [string]: any }): { [string]: any }
 	}
 end
 
---[[
-	Detailed read of specific instances. `properties` is chosen server-side from
-	the live API dump, so this handler never needs its own class table.
-]]
 --[[
 	The physical facts about a part, which no property panel shows.
 
@@ -323,6 +319,10 @@ local function physicsOf(target: Instance): { [string]: any }?
 	return facts
 end
 
+--[[
+	Detailed read of specific instances. `properties` is chosen server-side from
+	the live API dump, so this handler never needs its own class table.
+]]
 function Discover.inspect(params: { [string]: any }): { [string]: any }
 	local paths = params.paths
 	if typeof(paths) ~= "table" or #paths == 0 then
@@ -415,13 +415,6 @@ function Discover.inspect(params: { [string]: any }): { [string]: any }
 	return { items = results, failures = failures }
 end
 
---[[
-	One search over name, class, property value and tag.
-
-	Every filter supplied must match (AND), which is what lets a single tool
-	answer "every anchored Part under Workspace whose name contains 'door'"
-	without the agent chaining three calls and intersecting the results itself.
-]]
 --[[
 	Runs a selector through the engine's own matcher.
 
@@ -582,6 +575,13 @@ function Discover.tags(params: { [string]: any }): { [string]: any }
 	}
 end
 
+--[[
+	One search over name, class, property value and tag.
+
+	Every filter supplied must match (AND), which is what lets a single tool
+	answer "every anchored Part under Workspace whose name contains 'door'"
+	without the agent chaining three calls and intersecting the results itself.
+]]
 function Discover.find(params: { [string]: any }): { [string]: any }
 	local root = if params.path then Paths.resolve(params.path) else game
 	local limit = tonumber(params.limit) or 100

package/plugin/src/handlers/Input.luau

@@ -301,18 +301,42 @@ end
 
 makeCursor()
 
-for _, step in plan do
+--[[
+	Some keys cannot be sent at all. Roblox keeps them for its own menus --
+	Escape, Tab, F9, and in this place's case also One -- and `SendKey` THROWS
+	for them ("permanently bound to a CoreGUI core action"). Uncaught, that
+	killed this script mid-plan: the rest of the steps never ran, nothing was
+	reported, and the tool gave up with NO_ACK after its full timeout while the
+	error sat in Studio's Output. Which keys are reserved depends on the place
+	(One is the backpack hotbar), so it is caught here rather than listed.
+]]
+local function refusedKey(key, err)
+	local message = tostring(err)
+	if string.find(message, "CoreGUI", 1, true) then
+		return string.format(
+			"%s was not sent: Roblox reserves it for its own menus, so no script can press it. "
+				.. "Test what the game does on that key by calling its handler another way.",
+			key
+		)
+	end
+	return string.format("%s was not sent: %s", key, message)
+end
+
+local function runStep(step): boolean
 	local kind = step.kind
 	if kind == "key" then
 		local code = Enum.KeyCode[step.key]
-		if step.action == "release" then
+		local down = step.action ~= "release"
+		local sent, err = pcall(function()
+			virtual:SendKey(down, code, false)
+		end)
+		if not sent then
+			table.insert(notes, refusedKey(step.key, err))
+			return false
+		end
+		if down and step.action ~= "press" then
+			task.wait(step.hold or 0.08)
 			virtual:SendKey(false, code, false)
-		else
-			virtual:SendKey(true, code, false)
-			if step.action ~= "press" then
-				task.wait(step.hold or 0.08)
-				virtual:SendKey(false, code, false)
-			end
 		end
 	elseif kind == "move" then
 		moveCursor(step.x, step.y, 0.3)
@@ -364,7 +388,17 @@ for _, step in plan do
 			virtual:SendTextInput(step.text)
 		end
 	end
-	table.insert(performed, kind)
+	return true
+end
+
+for index, step in plan do
+	-- Guarded so one failing step can never stop the report going back.
+	local ok, done = pcall(runStep, step)
+	if not ok then
+		table.insert(notes, string.format("step %d (%s) failed: %s", index - 1, tostring(step.kind), tostring(done)))
+	elseif done then
+		table.insert(performed, step.kind)
+	end
 	if step.after ~= nil and step.after > 0 then
 		task.wait(step.after)
 	end

package/plugin/src/handlers/Instances.luau

@@ -109,6 +109,11 @@ local function applyTags(target: Instance, tags: { [string]: any })
 	end
 end
 
+--[[
+	One property that could not be applied yet, kept for a second attempt.
+]]
+type Deferred = { target: Instance, name: string, spec: PropertySpec, className: string }
+
 --[[
 	Builds one instance and its descendants.
 
@@ -116,11 +121,6 @@ end
 	model appears in the Explorer complete rather than assembling itself piece by
 	piece in front of the user.
 ]]
---[[
-	One property that could not be applied yet, kept for a second attempt.
-]]
-type Deferred = { target: Instance, name: string, spec: PropertySpec, className: string }
-
 local function build(
 	spec: { [string]: any },
 	parent: Instance,

package/plugin/src/handlers/Scripts.luau

@@ -56,11 +56,6 @@ local function resolveScript(path: string): LuaSourceContainer
 	return instance :: LuaSourceContainer
 end
 
---[[
-	Reads source, optionally a line window. `startLine`/`endLine` are 1-based and
-	inclusive, matching the numbers script_edit takes back, so a read and a write
-	need no off-by-one conversion between them.
-]]
 --[[
 	A short fingerprint of a script's source, for detecting that it moved.
 
@@ -136,6 +131,11 @@ local function syncedFile(target: Instance): string?
 	return name
 end
 
+--[[
+	Reads source, optionally a line window. `startLine`/`endLine` are 1-based and
+	inclusive, matching the numbers script_edit takes back, so a read and a write
+	need no off-by-one conversion between them.
+]]
 function Scripts.read(params: { [string]: any }): { [string]: any }
 	local paths = params.paths
 	if typeof(paths) ~= "table" or #paths == 0 then
@@ -381,12 +381,45 @@ function Scripts.grep(params: { [string]: any }): { [string]: any }
 		)
 	end
 
+	local function badPattern(reason: any): never
+		Dispatch.fail(
+			"BAD_PATTERN",
+			string.format("%s is not a valid Lua pattern: %s", pattern, tostring(reason)),
+			"Lua patterns escape with %, not backslash, and have no alternation. "
+				.. "Set `literal` to search for the text exactly as written."
+		)
+	end
+
+	--[[
+		One search over the whole file before splitting it into lines.
+
+		Most scripts in a place do not contain what is being looked for, and
+		splitting each into a line table only to find nothing was most of the cost
+		of a place-wide search. A pattern that matches no line cannot match the
+		whole file either -- except one anchored with `^` or `$`, which mean line
+		ends here but file ends there, so those skip this shortcut.
+	]]
+	-- Any trailing `$` counts, escaped or not: skipping the shortcut costs speed,
+	-- taking it wrongly would hide matches.
+	local anchored = not literal and (string.sub(needle, 1, 1) == "^" or string.sub(needle, -1) == "$")
+
 	local matches: { { [string]: any } } = {}
 	local total = 0
 	local memo: Paths.NameIndex = {}
 
 	for _, target in targets do
-		local lines = TextEdit.toLines(ScriptEdit.read(target))
+		local source = ScriptEdit.read(target)
+		if not anchored then
+			local ok, found = pcall(string.find, if ignoreCase then string.lower(source) else source, needle, 1, literal)
+			if not ok then
+				badPattern(found)
+			end
+			if not found then
+				continue
+			end
+		end
+
+		local lines = TextEdit.toLines(source)
 		local path: string? = nil
 
 		for number, line in lines do
@@ -395,12 +428,7 @@ function Scripts.grep(params: { [string]: any }): { [string]: any }
 			-- has to be caught and reported as a pattern problem, not a no-match.
 			local ok, from = pcall(string.find, haystack, needle, 1, literal)
 			if not ok then
-				Dispatch.fail(
-					"BAD_PATTERN",
-					string.format("%s is not a valid Lua pattern: %s", pattern, tostring(from)),
-					"Lua patterns escape with %, not backslash, and have no alternation. "
-						.. "Set `literal` to search for the text exactly as written."
-				)
+				badPattern(from)
 			end
 			if not from then
 				continue
@@ -440,12 +468,6 @@ function Scripts.grep(params: { [string]: any }): { [string]: any }
 	}
 end
 
---[[
-	Creates scripts. Source is assigned directly here rather than through
-	`UpdateSourceAsync`: the instance does not exist yet, so nothing can have it
-	open in the editor and there is no buffer to conflict with. Every later edit
-	goes through the editor path.
-]]
 --[[
 	Names the starter container a script was just parented into, or nil.
 
@@ -457,6 +479,14 @@ end
 	Client over LocalScript" advice writes a double-running script and is given
 	no way to find out.
 ]]
+--[[
+	Assigning `Source` fails at 200,000 characters or more ("Provided string
+	length ... is greater than or equal to max length (200000)"), while
+	`UpdateSourceAsync` takes far more -- measured writing 279,000. Sources at
+	the limit are written through the editor instead of refused.
+]]
+local SOURCE_PROPERTY_LIMIT = 200000
+
 local STARTER_CONTAINERS = {
 	"StarterGui",
 	"StarterPack",
@@ -473,6 +503,12 @@ local function starterContainer(instance: Instance): string?
 	return nil
 end
 
+--[[
+	Creates scripts. Source is assigned directly here rather than through
+	`UpdateSourceAsync`: the instance does not exist yet, so nothing can have it
+	open in the editor and there is no buffer to conflict with. Every later edit
+	goes through the editor path.
+]]
 function Scripts.create(params: { [string]: any }): { [string]: any }
 	local requests = params.scripts
 	if typeof(requests) ~= "table" or #requests == 0 then
@@ -503,6 +539,7 @@ function Scripts.create(params: { [string]: any }): { [string]: any }
 	-- No shared path memo here: each creation changes its parent's children, so a
 	-- cached sibling grouping would go stale mid-batch and mis-number the paths.
 	local warnings: { string } = {}
+	local oversized: { { target: LuaSourceContainer, source: string } } = {}
 
 	local created, recorded = Undo.record("StudioMCP.ScriptCreate", "MCP create script", function()
 		local created: { { [string]: any } } = {}
@@ -513,7 +550,11 @@ function Scripts.create(params: { [string]: any }): { [string]: any }
 
 			instance.Name = request.name
 			if typeof(request.source) == "string" then
-				(instance :: ScriptEdit.SourceContainer).Source = request.source
+				if #request.source < SOURCE_PROPERTY_LIMIT then
+					(instance :: ScriptEdit.SourceContainer).Source = request.source
+				else
+					table.insert(oversized, { target = instance, source = request.source })
+				end
 			end
 
 			if typeof(request.runContext) == "string" and instance:IsA("Script") then
@@ -605,6 +646,14 @@ function Scripts.create(params: { [string]: any }): { [string]: any }
 		return created
 	end)
 
+	-- After the recording, because the editor write yields. Undoing the create
+	-- still removes these scripts whole, source and all.
+	for _, entry in oversized do
+		ScriptEdit.write(entry.target, function()
+			return entry.source
+		end)
+	end
+
 	return {
 		items = created,
 		undoStep = if recorded then "MCP create script" else nil,