@el4cteo/rbx-studio-mcp 0.7.8 → 0.8.2

package/plugin/src/handlers/Assets.luau

@@ -17,6 +17,7 @@ local InsertService = game:GetService("InsertService")
 
 local Dispatch = require(script.Parent.Parent.Dispatch)
 local Paths = require(script.Parent.Parent.Paths)
+local Serialize = require(script.Parent.Parent.Serialize)
 local Undo = require(script.Parent.Parent.Undo)
 
 local Assets = {}
@@ -53,6 +54,17 @@ function Assets.insert(params: { [string]: any }): { [string]: any }
 		then Paths.resolve(params.parent)
 		else workspace
 
+	-- Parsed before anything loads. A position that did not parse used to be
+	-- skipped in silence, and the model landed wherever it was saved.
+	local position: Vector3? = nil
+	if typeof(params.position) == "string" and params.position ~= "" then
+		local ok, value, why = Serialize.parse(params.position, "Vector3")
+		if not ok then
+			Dispatch.fail("BAD_PARAMS", string.format("`position` is not a Vector3: %s", tostring(why)), 'Write it as "x, y, z".')
+		end
+		position = value :: Vector3
+	end
+
 	--[[
 		`game:GetObjects`, not `InsertService:LoadAsset`.
 
@@ -135,10 +147,8 @@ function Assets.insert(params: { [string]: any }): { [string]: any }
 		-- nothing silently is worse than saying so.
 		local remaining: { Instance } = {}
 		for _, child in children do
-			if child.Parent ~= nil or child:IsDescendantOf(game) or child.Name ~= "" then
-				if not child:IsA("LuaSourceContainer") then
-					table.insert(remaining, child)
-				end
+			if not child:IsA("LuaSourceContainer") then
+				table.insert(remaining, child)
 			end
 		end
 		children = remaining
@@ -160,20 +170,19 @@ function Assets.insert(params: { [string]: any }): { [string]: any }
 			table.insert(inserted, Paths.of(child))
 		end
 
-		-- Position after parenting, so PrimaryPart and pivot are settled.
-		if typeof(params.position) == "string" and params.position ~= "" then
-			local x, y, z = string.match(params.position, "^%s*(-?[%d%.]+)%s*,%s*(-?[%d%.]+)%s*,%s*(-?[%d%.]+)%s*$")
-			if x then
-				local target = CFrame.new(tonumber(x) :: number, tonumber(y) :: number, tonumber(z) :: number)
-				for _, child in children do
-					pcall(function()
-						if child:IsA("Model") then
-							(child :: Model):PivotTo(target)
-						elseif child:IsA("BasePart") then
-							(child :: BasePart).CFrame = target
-						end
-					end)
-				end
+		-- Position after parenting, so PrimaryPart and pivot are settled. Only
+		-- the position moves: the asset keeps the rotation it was saved with.
+		if position then
+			for _, child in children do
+				pcall(function()
+					if child:IsA("Model") then
+						local model = child :: Model
+						model:PivotTo(model:GetPivot().Rotation + position)
+					elseif child:IsA("BasePart") then
+						local part = child :: BasePart
+						part.CFrame = part.CFrame.Rotation + position
+					end
+				end)
 			end
 		end
 	end)

package/plugin/src/handlers/Audio.luau

@@ -56,6 +56,11 @@ local function pinsOf(instance: Instance): ({ string }, { string })
 end
 
 local function isAudio(instance: Instance): boolean
+	-- Every pin-bearing audio class is named Audio*. Checked first so a walk of
+	-- the whole place does not throw and catch twice for every part in it.
+	if string.sub(instance.ClassName, 1, 5) ~= "Audio" then
+		return false
+	end
 	local inputs, outputs = pinsOf(instance)
 	return #inputs > 0 or #outputs > 0
 end
@@ -176,11 +181,11 @@ end
 	Builds a whole working chain in one step.
 
 	`world` is a sound at a place: AudioPlayer -> [effects] -> AudioEmitter,
-	parented to a part, heard from wherever it is. This is the common case and
-	the one people get wrong, because it also needs an `AudioListener` somewhere
-	-- without one on the camera or the character, a correctly wired emitter is
-	still silent. Reported rather than created: where the listener belongs is a
-	game design decision, not a default.
+	parented to a part, heard from wherever it is. It also needs something to
+	hear it: an `AudioListener`, which the engine adds on its own unless
+	`SoundService.DefaultListenerLocation` is None. In that case a missing
+	listener is reported rather than created: where it belongs is a game design
+	decision, not a default.
 
 	`ui` is a sound with no position: AudioPlayer -> [effects] ->
 	AudioDeviceOutput. Menu clicks, music.
@@ -258,9 +263,15 @@ function Audio.graph(params: { [string]: any }): { [string]: any }
 				player.AudioContent = Content.fromUri(asset :: string)
 			end)
 			if not okContent then
-				pcall(function()
+				local okAsset = pcall(function()
 					(player :: any).Asset = asset
 				end)
+				if not okAsset then
+					table.insert(
+						warnings,
+						string.format("The AudioPlayer took neither AudioContent nor Asset for %q; it has no sound yet.", asset :: string)
+					)
+				end
 			end
 		end
 		player.Parent = parent
@@ -296,16 +307,26 @@ function Audio.graph(params: { [string]: any }): { [string]: any }
 				way a correct graph stays silent, and it is invisible from the
 				emitter's own properties. Checked and said plainly.
 			]]
-			local listeners = 0
-			for _, descendant in game:GetDescendants() do
-				if descendant:IsA("AudioListener") then
-					listeners += 1
+			--[[
+				Only when the engine will not supply one. SoundService's
+				DefaultListenerLocation (Camera in a new place) makes Roblox add a
+				listener itself at runtime, and warning then was a false alarm.
+			]]
+			local okLocation, location = pcall(function()
+				return (game:GetService("SoundService") :: any).DefaultListenerLocation
+			end)
+			if okLocation and location == Enum.ListenerLocation.None then
+				local listeners = 0
+				for _, descendant in game:GetDescendants() do
+					if descendant:IsA("AudioListener") then
+						listeners += 1
+					end
+				end
+				if listeners == 0 then
+					note = "SoundService.DefaultListenerLocation is None and nothing in this "
+						.. "place has an AudioListener, so no emitter can be heard. Put one on "
+						.. "the camera or the character, or set DefaultListenerLocation."
 				end
-			end
-			if listeners == 0 then
-				note = "Nothing in this place has an AudioListener, so no emitter can "
-					.. "be heard. Put one on the camera or the character -- where it "
-					.. "goes decides what the player hears, so it is not created here."
 			end
 		end
 

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()

package/plugin/src/handlers/Character.luau

@@ -35,6 +35,7 @@ local RunService = game:GetService("RunService")
 
 local Dispatch = require(script.Parent.Parent.Dispatch)
 local Paths = require(script.Parent.Parent.Paths)
+local Serialize = require(script.Parent.Parent.Serialize)
 
 local Character = {}
 
@@ -89,11 +90,11 @@ local function parseVector(value: any, what: string): Vector3
 	if typeof(value) ~= "string" then
 		Dispatch.fail("BAD_PARAMS", string.format("%s must be a string like \"10, 5, 0\".", what))
 	end
-	local x, y, z = string.match(value, "^%s*(-?[%d%.]+)%s*,%s*(-?[%d%.]+)%s*,%s*(-?[%d%.]+)%s*$")
-	if x == nil then
+	local ok, parsed = Serialize.parse(value, "Vector3")
+	if not ok then
 		Dispatch.fail("BAD_PARAMS", string.format("%s must look like \"10, 5, 0\", got %q.", what, value))
 	end
-	return Vector3.new(tonumber(x) :: number, tonumber(y) :: number, tonumber(z) :: number)
+	return parsed :: Vector3
 end
 
 --[[
@@ -249,7 +250,21 @@ end
 	which is usually the finding rather than the failure.
 ]]
 function Character.path(params: { [string]: any }): { [string]: any }
-	local start = endpointOf(params, "fromPath", "from", "`from`")
+	-- No start given means "from the character", as the tool documents. That
+	-- only exists in a running game; in edit mode the start must be named.
+	local start: Vector3
+	local hasStart = params.from ~= nil or (typeof(params.fromPath) == "string" and params.fromPath ~= "")
+	if hasStart then
+		start = endpointOf(params, "fromPath", "from", "`from`")
+	elseif RunService:IsRunning() then
+		start = positionOf((humanoidOf(params)))
+	else
+		Dispatch.fail(
+			"BAD_PARAMS",
+			"path needs `from` or `fromPath` in edit mode.",
+			"Only a running playtest has a character to start from."
+		)
+	end
 	local goal = endpointOf(params, "toPath", "to", "`to`")
 
 	local path = PathfindingService:CreatePath(agentOf(params))
@@ -271,8 +286,8 @@ function Character.path(params: { [string]: any }): { [string]: any }
 		return {
 			reachable = false,
 			status = status,
-			from = tostring(start),
-			to = tostring(goal),
+			from = Serialize.value(start),
+			to = Serialize.value(goal),
 			straightLineDistance = math.round(straightLine * 10) / 10,
 			hint = "Nothing walkable connects these points for an agent this size. "
 				.. "A wall, a gap wider than a jump, or a drop too far. Try a smaller "
@@ -303,7 +318,7 @@ function Character.path(params: { [string]: any }): { [string]: any }
 			table.insert(rows, {
 				index = index,
 				action = action,
-				position = tostring(waypoint.Position),
+				position = Serialize.value(waypoint.Position),
 				label = if waypoint.Label ~= "" then waypoint.Label else nil,
 			})
 		end
@@ -312,8 +327,8 @@ function Character.path(params: { [string]: any }): { [string]: any }
 	return {
 		reachable = true,
 		status = status,
-		from = tostring(start),
-		to = tostring(goal),
+		from = Serialize.value(start),
+		to = Serialize.value(goal),
 		waypointCount = #waypoints,
 		pathDistance = math.round(travelled * 10) / 10,
 		straightLineDistance = math.round(straightLine * 10) / 10,
@@ -404,8 +419,8 @@ function Character.moveTo(params: { [string]: any }): { [string]: any }
 			return {
 				arrived = false,
 				pathStatus = pathStatus,
-				from = tostring(start),
-				goal = tostring(goal),
+				from = Serialize.value(start),
+				goal = Serialize.value(goal),
 				note = "No route exists. Pass direct=true to walk straight at it regardless.",
 			}
 		end
@@ -606,13 +621,13 @@ function Character.moveTo(params: { [string]: any }): { [string]: any }
 		-- the character had to be rescued along.
 		repaths = repaths,
 		pathStatus = pathStatus,
-		from = tostring(start),
-		to = tostring(final),
-		goal = tostring(goal),
+		from = Serialize.value(start),
+		to = Serialize.value(final),
+		goal = Serialize.value(goal),
 	}
 
 	if not arrived then
-		report.stuckAt = if stuckAt ~= nil then tostring(stuckAt) else nil
+		report.stuckAt = if stuckAt ~= nil then Serialize.value(stuckAt) else nil
 		report.blockedBy = blockedBy
 		--[[
 			Said plainly, because the numbers alone read as success to anything
@@ -654,10 +669,10 @@ function Character.act(params: { [string]: any }): { [string]: any }
 
 	if action == "jump" then
 		humanoid.Jump = true
-		return { action = action, at = tostring(positionOf(model)) }
+		return { action = action, at = Serialize.value(positionOf(model)) }
 	elseif action == "stop" then
 		humanoid:MoveTo(positionOf(model))
-		return { action = action, at = tostring(positionOf(model)) }
+		return { action = action, at = Serialize.value(positionOf(model)) }
 	elseif action == "sit" then
 		humanoid.Sit = true
 		return { action = action, sitting = humanoid.Sit }
@@ -783,7 +798,7 @@ function Character.act(params: { [string]: any }): { [string]: any }
 	elseif action == "teleport" then
 		local target = parseVector(params.to, "`to`")
 		model:PivotTo(CFrame.new(target))
-		return { action = action, at = tostring(positionOf(model)), note = "Moved without walking -- collisions and triggers along the way did not fire." }
+		return { action = action, at = Serialize.value(positionOf(model)), note = "Moved without walking -- collisions and triggers along the way did not fire." }
 	end
 
 	Dispatch.fail("BAD_PARAMS", string.format("unknown character action %q", action))
@@ -798,11 +813,11 @@ function Character.state(params: { [string]: any }): { [string]: any }
 	local model, humanoid, player = humanoidOf(params)
 	return {
 		player = player.Name,
-		position = tostring(positionOf(model)),
-		health = humanoid.Health,
-		maxHealth = humanoid.MaxHealth,
-		walkSpeed = humanoid.WalkSpeed,
-		jumpPower = humanoid.JumpPower,
+		position = Serialize.value(positionOf(model)),
+		health = Serialize.value(humanoid.Health),
+		maxHealth = Serialize.value(humanoid.MaxHealth),
+		walkSpeed = Serialize.value(humanoid.WalkSpeed),
+		jumpPower = Serialize.value(humanoid.JumpPower),
 		state = tostring(humanoid:GetState()),
 		sitting = humanoid.Sit,
 		floor = if humanoid.FloorMaterial ~= Enum.Material.Air

package/plugin/src/handlers/Data.luau

@@ -457,8 +457,19 @@ function Data.set(params: { [string]: any }): { [string]: any }
 	end
 
 	local store = storeOf(params)
+	--[[
+		UpdateAsync, not SetAsync. SetAsync replaces the key's UserIds and
+		metadata along with its value, so a plain write stripped the GDPR user
+		tags and whatever metadata the game keeps there (session locks
+		included). Handing the old ones back keeps everything but the value.
+	]]
 	local ok, err = pcall(function()
-		store:SetAsync(key, value)
+		store:UpdateAsync(key, function(_, keyInfo: any)
+			if keyInfo == nil then
+				return value
+			end
+			return value, keyInfo:GetUserIds(), keyInfo:GetMetadata()
+		end)
 	end)
 	if not ok then
 		gate(err, "writing the key")