@el4cteo/rbx-studio-mcp 0.7.7 → 0.8.0

package/plugin/src/Paths.luau

@@ -147,13 +147,19 @@ local function childBySegment(
 
 	if ordinal then
 		local list = childrenByName(parent, nil)[name]
-		if list == nil then
-			return nil, nil
-		end
-		local child = list[ordinal]
+		local child = if list then list[ordinal] else nil
 		if child then
 			return child, nil
 		end
+		-- Not an index after all: a child literally named "x[1]". Typed by hand,
+		-- or from a path emitted before `Paths.of` began marking such names.
+		local literal = parent:FindFirstChild(segment)
+		if literal then
+			return literal, nil
+		end
+		if list == nil then
+			return nil, nil
+		end
 		return nil,
 			string.format(
 				'"%s" has %d child%s named "%s", so [%d] is past the end. Indexes are '
@@ -343,6 +349,11 @@ function Paths.of(instance: Instance, memo: NameIndex?): string
 	while current ~= nil and current ~= game do
 		local node = current :: Instance
 		local ordinal = siblingIndex(node, memo)
+		-- A name that itself ends in "[n]" would read back as an index into a
+		-- shorter name. An explicit index keeps it literal: "x[1][1]".
+		if ordinal == nil and string.match(node.Name, "%[%d+%]$") then
+			ordinal = 1
+		end
 		table.insert(
 			segments,
 			1,

package/plugin/src/Phrase.luau

@@ -566,29 +566,11 @@ local DESCRIBERS: { [string]: Describer } = {
 
 	--[[
 		Everything below was added after the first pass over this table, and each
-		one spent time showing as the fallback -- "Anim preview", "Data set",
+		one spent time showing as the fallback -- "Data set",
 		"Terrain fill". That form is honest but says nothing about the subject,
 		which is the whole point of this module: the panel is watched to see WHAT
 		an agent is touching, and 26 of 72 operations were declining to say.
 	]]
-	["anim.read"] = function(params)
-		local name = leaf(params.assetId)
-		return if name ~= nil then "Read the animation " .. name else "Read an animation"
-	end,
-	["anim.build"] = function(params)
-		local frames = count(params.keyframes)
-		return string.format("Build an animation from %s", plural(frames, "keyframe"))
-	end,
-	["anim.preview"] = function(params)
-		local rig = leaf(params.rig) or "a rig"
-		if params.op == "stop" then
-			return "Clear the pose on " .. rig
-		end
-		local at = tonumber(params.at)
-		return if at ~= nil
-			then string.format("Pose %s at %.2fs", rig, at)
-			else "Pose " .. rig
-	end,
 
 	["data.list"] = function(params)
 		local store = params.store
@@ -771,7 +753,6 @@ local KINDS: { [string]: string } = {
 	]]
 	terrain = "write",
 	generate = "write",
-	anim = "write",
 	data = "write",
 }
 

package/plugin/src/ScriptEdit.luau

@@ -67,6 +67,20 @@ local function confirm(target: LuaSourceContainer, produced: string?)
 		return
 	end
 
+	--[[
+		No document, no race. The overwrite comes from an editor tab that was
+		loading while we wrote; a tab opened afterwards loads the new source. So
+		a script nobody has open is confirmed by one read, instead of paying the
+		settle -- which cost every written script 200ms, one after another, on
+		every script_edit and script_create.
+	]]
+	local found, document = pcall(function()
+		return ScriptEditorService:FindScriptDocument(target)
+	end)
+	if found and document == nil and ScriptEdit.read(target) == produced then
+		return
+	end
+
 	-- Three rounds: the race is with one load, so a single rewrite settles it,
 	-- and a script that discards three identical writes is failing for a reason
 	-- repeating will not fix.

package/plugin/src/Serialize.luau

@@ -403,6 +403,11 @@ function Serialize.parse(text: any, valueType: string): (boolean, any, string?)
 		return true, Vector2.new(numbers[1], numbers[2]), nil
 	end
 	if valueType == "Color3" then
+		-- "#FF8800", the way colours are usually written everywhere else.
+		local hex = if kind == "string" then string.match(text, "^%s*#(%x%x%x%x%x%x)%s*$") else nil
+		if hex then
+			return true, Color3.fromHex(hex), nil
+		end
 		if #numbers < 3 then
 			return false, nil, 'expected three 0-1 components, e.g. "1, 0.5, 0"'
 		end
@@ -435,6 +440,18 @@ function Serialize.parse(text: any, valueType: string): (boolean, any, string?)
 		return true, UDim.new(numbers[1], numbers[2]), nil
 	end
 	if valueType == "CFrame" then
+		-- Twelve numbers are a full matrix -- what `tostring(cframe)` prints. Read
+		-- as "position | rotation" they gave a silently wrong orientation.
+		if #numbers == 12 then
+			return true,
+				CFrame.new(
+					numbers[1], numbers[2], numbers[3],
+					numbers[4], numbers[5], numbers[6],
+					numbers[7], numbers[8], numbers[9],
+					numbers[10], numbers[11], numbers[12]
+				),
+				nil
+		end
 		if #numbers >= 6 then
 			return true,
 				CFrame.new(numbers[1], numbers[2], numbers[3])

package/plugin/src/TextEdit.luau

@@ -263,6 +263,12 @@ function TextEdit.apply(path: string, source: string, edits: { Edit }): string
 	end
 
 	local text = table.concat(lines, "\n")
+	-- `toLines` drops the final newline, so it is put back here. Without this
+	-- every edit -- even a find/replace in the middle -- stripped it silently,
+	-- and a `find` that included it could never match.
+	if string.sub(source, -1) == "\n" and #lines > 0 then
+		text ..= "\n"
+	end
 
 	for _, edit in findEdits do
 		local needle = edit.find :: string

package/plugin/src/handlers/Api.luau

@@ -122,6 +122,14 @@ local function collect(entries: { any }, className: string, wantInherited: boole
 			deprecated += 1
 			continue
 		end
+		-- No permits at all means no script can touch it: Part's old `shap` and
+		-- `shape` aliases, or engine-only calls like GetPhysicsCost. The engine
+		-- does not flag those as deprecated, so they are held back here too.
+		local permits = if typeof(entry) == "table" then (entry :: any).Permits else nil
+		if typeof(permits) == "table" and next(permits) == nil then
+			deprecated += 1
+			continue
+		end
 		local own = typeof(entry) ~= "table" or tostring((entry :: any).Owner) == className
 		if not own then
 			inherited += 1

package/plugin/src/handlers/Capture.luau

@@ -21,6 +21,7 @@ local RunService = game:GetService("RunService")
 
 local Dispatch = require(script.Parent.Parent.Dispatch)
 local Emulation = require(script.Parent.Parent.Emulation)
+local Paths = require(script.Parent.Parent.Paths)
 local Png = require(script.Parent.Parent.Png)
 
 -- Wide enough to read a GUI label, small enough that the encode stays quick and
@@ -445,7 +446,98 @@ end
 	and read in another: the id is all that travels, and this is the reading
 	half, which needs plugin identity and therefore an editor session.
 ]]
-local function encode(contentId: string, width: number, context: string): { [string]: any }
+-- In capture pixels, or in viewport pixels when `viewportWidth` says so.
+export type Region = { x: number, y: number, width: number, height: number, viewportWidth: number? }
+
+--[[
+	The full-resolution path: the captured pixels themselves, cropped to `region`
+	when one is given, compressed for the wire and scaled down in Node.
+
+	The engine resample below is bilinear, which only averages the pixels it
+	merges at exactly 2x -- beyond that it skips source pixels, and a 1661-wide
+	viewport scaled to 800 lost thin edges and broke small GUI text apart. Node
+	scales with a box filter instead, where every source pixel counts. Measured
+	cost of sending the full frame: ~60ms of a ~550ms call, most of which is the
+	engine's own capture.
+
+	Returns nil when this Studio cannot do it (no EncodingService), so the caller
+	falls back to the engine resample.
+]]
+local function encodeFull(
+	image: any,
+	sourceWidth: number,
+	sourceHeight: number,
+	width: number,
+	context: string,
+	region: Region?
+): { [string]: any }?
+	local x, y, w, h = 0, 0, sourceWidth, sourceHeight
+	if region then
+		-- Viewport and capture pixels differ under display scaling.
+		local ratio = if region.viewportWidth then sourceWidth / region.viewportWidth else 1
+		region = {
+			x = region.x * ratio,
+			y = region.y * ratio,
+			width = region.width * ratio,
+			height = region.height * ratio,
+		}
+		x = math.clamp(math.floor(region.x), 0, sourceWidth)
+		y = math.clamp(math.floor(region.y), 0, sourceHeight)
+		w = math.min(math.ceil(region.width), sourceWidth - x)
+		h = math.min(math.ceil(region.height), sourceHeight - y)
+		if w < 1 or h < 1 then
+			Dispatch.fail(
+				"REGION_OFFSCREEN",
+				string.format(
+					"The region (%d, %d, %d x %d) is outside the %d x %d viewport.",
+					region.x,
+					region.y,
+					region.width,
+					region.height,
+					sourceWidth,
+					sourceHeight
+				),
+				"Aim the camera at it first with `viewport op=\"focus\"`, then take the screenshot."
+			)
+		end
+	end
+
+	local ok, result = pcall(function()
+		local rgba = image:ReadPixelsBuffer(Vector2.new(x, y), Vector2.new(w, h))
+		local rgb = stripAlpha(rgba, w, h)
+		local compressed = (EncodingService :: any):CompressBuffer(
+			rgb,
+			(Enum :: any).CompressionAlgorithm.Zstd,
+			COMPRESSION_LEVEL
+		)
+		return {
+			rgb = rgb,
+			packed = buffer.tostring((EncodingService :: any):Base64Encode(compressed)),
+		}
+	end)
+	if not ok then
+		return nil
+	end
+
+	return {
+		encoding = "zstd-rgb",
+		data = result.packed,
+		width = w,
+		height = h,
+		-- Node scales to this with a box filter; see above.
+		scaleTo = width,
+		sourceWidth = sourceWidth,
+		sourceHeight = sourceHeight,
+		region = if region then { x = x, y = y, width = w, height = h } else nil,
+		rawBytes = buffer.len(result.rgb),
+		bytes = #result.packed,
+		context = context,
+		black = isFlat(result.rgb),
+		device = Emulation.deviceId(),
+	}
+end
+
+local function encode(contentId: string, width: number, context: string, region: Region?): { [string]: any }
 	local okImage, image = pcall(function()
 		return AssetService:CreateEditableImageAsync(Content.fromUri(contentId))
 	end)
@@ -460,6 +552,21 @@ local function encode(contentId: string, width: number, context: string): { [str
 	local sourceWidth = math.floor(size.X)
 	local sourceHeight = math.floor(size.Y)
 
+	local full = encodeFull(image, sourceWidth, sourceHeight, width, context, region)
+	if full then
+		pcall(function()
+			(image :: any):Destroy()
+		end)
+		return full
+	end
+	if region then
+		Dispatch.fail(
+			"REGION_UNSUPPORTED",
+			"This Studio build cannot crop a screenshot (EncodingService is missing).",
+			"Take the full screenshot instead, or update Studio."
+		)
+	end
+
 	local rgb, outWidth, outHeight = resample(image, sourceWidth, sourceHeight, width)
 
 	if rgb == nil then
@@ -544,6 +651,111 @@ local function encode(contentId: string, width: number, context: string): { [str
 	}
 end
 
+-- Room left around a zoomed subject, as a share of its size, so its edges are
+-- visible rather than cut exactly at the frame.
+local REGION_PADDING = 0.08
+
+--[[
+	Where on screen a GUI element or a piece of the world is, in viewport pixels.
+
+	GUI positions leave out the top inset, so it is added back; a 3D subject is
+	the screen box around its bounding box's eight corners. A subject partly
+	behind the camera has no honest box, so that is refused with the fix.
+]]
+local function boundsOf(target: Instance): (Vector2, Vector2)
+	if target:IsA("GuiObject") then
+		local inset = game:GetService("GuiService"):GetGuiInset()
+		return target.AbsolutePosition + inset, target.AbsolutePosition + target.AbsoluteSize + inset
+	end
+
+	local cframe: CFrame, size: Vector3
+	if target:IsA("BasePart") then
+		cframe, size = target.CFrame, target.Size
+	elseif target:IsA("Model") then
+		cframe, size = target:GetBoundingBox()
+	else
+		local low, high = Vector3.one * math.huge, -Vector3.one * math.huge
+		local counted = 0
+		for _, descendant in target:GetDescendants() do
+			if descendant:IsA("BasePart") then
+				local half = descendant.Size / 2
+				for _, corner in { Vector3.new(-1, -1, -1), Vector3.new(1, 1, 1), Vector3.new(-1, 1, -1), Vector3.new(1, -1, 1) } do
+					local point = descendant.CFrame:PointToWorldSpace(half * corner)
+					low, high = low:Min(point), high:Max(point)
+				end
+				counted += 1
+				if counted >= 2000 then
+					break
+				end
+			end
+		end
+		if counted == 0 then
+			Dispatch.fail(
+				"NOT_VISUAL",
+				string.format("%s has no GUI or parts to zoom to.", target:GetFullName()),
+				"Zoom to a GuiObject, a BasePart, a Model, or a folder containing parts."
+			)
+		end
+		cframe, size = CFrame.new((low + high) / 2), high - low
+	end
+
+	local camera = workspace.CurrentCamera
+	local low, high = Vector2.one * math.huge, -Vector2.one * math.huge
+	for _, sx in { -1, 1 } do
+		for _, sy in { -1, 1 } do
+			for _, sz in { -1, 1 } do
+				local point, _ = camera:WorldToViewportPoint(cframe:PointToWorldSpace(size / 2 * Vector3.new(sx, sy, sz)))
+				if point.Z <= 0 then
+					Dispatch.fail(
+						"REGION_OFFSCREEN",
+						string.format("%s is partly behind the camera.", target:GetFullName()),
+						"Aim the camera at it first with `viewport op=\"focus\"`, then take the screenshot."
+					)
+				end
+				local flat = Vector2.new(point.X, point.Y)
+				low, high = low:Min(flat), high:Max(flat)
+			end
+		end
+	end
+	return low, high
+end
+
+--[[
+	The part of the capture to keep, in capture pixels.
+
+	`path` zooms to an instance; `rect` is "x, y, width, height" in the pixels of
+	the full-resolution capture, which every screenshot caption states. A path
+	is resolved before the capture, so a bad one fails without taking it.
+]]
+local function regionFor(params: { [string]: any }): Region?
+	if typeof(params.rect) == "string" and params.rect ~= "" then
+		local numbers = {}
+		for token in string.gmatch(params.rect, "-?[%d%.]+") do
+			table.insert(numbers, tonumber(token))
+		end
+		if #numbers ~= 4 or numbers[3] <= 0 or numbers[4] <= 0 then
+			Dispatch.fail("BAD_PARAMS", 'rect must be "x, y, width, height", e.g. "400, 200, 320, 180".')
+		end
+		return { x = numbers[1], y = numbers[2], width = numbers[3], height = numbers[4] }
+	end
+
+	if typeof(params.path) ~= "string" or params.path == "" then
+		return nil
+	end
+	local target = Paths.resolve(params.path)
+	local low, high = boundsOf(target)
+	local extent = high - low
+	local pad = Vector2.new(math.max(8, extent.X * REGION_PADDING), math.max(8, extent.Y * REGION_PADDING))
+	low, high = low - pad, high + pad
+	return {
+		x = low.X,
+		y = low.Y,
+		width = high.X - low.X,
+		height = high.Y - low.Y,
+		viewportWidth = workspace.CurrentCamera.ViewportSize.X,
+	}
+end
+
 function Capture.screenshot(params: { [string]: any }): { [string]: any }
 	--[[
 		Refused rather than half-done. A playtest screenshot needs two sessions
@@ -562,7 +774,9 @@ function Capture.screenshot(params: { [string]: any }): { [string]: any }
 	end
 
 	local width = math.clamp(tonumber(params.width) or DEFAULT_WIDTH, MIN_WIDTH, MAX_WIDTH)
-	return encode(takeScreenshot(), width, if RunService:IsEdit() then "edit" else "playtest")
+	-- Before the capture, so a path that does not resolve costs no screenshot.
+	local region = regionFor(params)
+	return encode(takeScreenshot(), width, if RunService:IsEdit() then "edit" else "playtest", region)
 end
 
 --[[
@@ -579,7 +793,9 @@ function Capture.decode(params: { [string]: any }): { [string]: any }
 
 	local width = math.clamp(tonumber(params.width) or DEFAULT_WIDTH, MIN_WIDTH, MAX_WIDTH)
 	local context = if typeof(params.context) == "string" then params.context else "playtest client"
-	return encode(contentId :: string, width, context)
+	-- Only `rect` here: a path would have to be resolved in the client's view.
+	local region = if typeof(params.rect) == "string" then regionFor({ rect = params.rect }) else nil
+	return encode(contentId :: string, width, context, region)
 end
 
 function Capture.register()