@el4cteo/rbx-studio-mcp 0.6.1 → 0.6.7

package/plugin/src/handlers/Session.luau

@@ -146,6 +146,9 @@ function Session.status(): { [string]: any }
 		scriptCount = totals.scripts,
 		studioVersion = studioVersion(),
 		emulatedDevice = Emulation.summary(),
+		-- Separate from the device: traffic can be shaped with no device set,
+		-- and that is the case most likely to be forgotten about.
+		emulatedNetwork = Emulation.networkSummary(),
 	}
 end
 

package/plugin/src/handlers/Spatial.luau

@@ -0,0 +1,334 @@
+--!strict
+--[[
+	Spatial queries: casts, and "what is in this box".
+
+	These answer the one question the Explorer cannot: what is actually THERE.
+	A path tells you an instance exists and where its own pivot sits; it does not
+	tell you that the door frame overlaps the wall, that the spawn is buried a
+	stud inside the floor, or that nothing at all stands between the turret and
+	the player. Every one of those is a query against the world, and before this
+	the only way to run one was `execute_luau`.
+
+	All of it goes through a WorldRoot rather than through `workspace` directly,
+	for the same reason collision groups do: a `WorldModel` inside a ViewportFrame
+	is its own world with its own parts and its own collision groups, and a query
+	hard-coded to the Workspace can only ever lie about it.
+
+	The `collisionGroup` field is the point of doing this now. Roblox moved
+	collision group management onto WorldRoot in September 2026, and spatial
+	queries inside a WorldModel now honour groups the way Workspace always has.
+	A cast run in the wrong group reports a clear path through a wall the player
+	cannot walk through -- a wrong answer that looks exactly like a right one.
+]]
+
+local Workspace = game:GetService("Workspace")
+
+local Dispatch = require(script.Parent.Parent.Dispatch)
+local Paths = require(script.Parent.Parent.Paths)
+local Serialize = require(script.Parent.Parent.Serialize)
+
+local Spatial = {}
+
+-- A query that returns every part in a large place is not an answer, it is a
+-- transcript. Callers narrow with `filter` or raise this deliberately.
+local DEFAULT_LIMIT = 50
+local MAX_LIMIT = 500
+
+--[[
+	Which world the query runs in. Same rule as collision groups: the Workspace
+	unless a WorldModel is named, and anything that is not a WorldRoot is refused
+	by name rather than left to fail inside the engine call.
+]]
+local function root(params: { [string]: any }): Instance
+	local path = params.worldModel
+	if typeof(path) ~= "string" or path == "" then
+		return Workspace
+	end
+
+	local instance = Paths.resolve(path)
+	if not instance:IsA("WorldRoot") then
+		Dispatch.fail(
+			"BAD_PARAMS",
+			string.format("%s is a %s, not a WorldModel.", path, instance.ClassName),
+			"Spatial queries run on a WorldRoot: the Workspace, or a WorldModel "
+				.. "inside a ViewportFrame. Omit `worldModel` for the Workspace."
+		)
+	end
+	return instance
+end
+
+local function vector(value: any, field: string): Vector3
+	if typeof(value) == "table" then
+		local list = value :: { any }
+		local x, y, z = tonumber(list[1]), tonumber(list[2]), tonumber(list[3])
+		if x and y and z then
+			return Vector3.new(x, y, z)
+		end
+	end
+	if typeof(value) == "string" then
+		local ok, parsed = Serialize.parse(value, "Vector3")
+		if ok and typeof(parsed) == "Vector3" then
+			return parsed
+		end
+	end
+	Dispatch.fail(
+		"BAD_PARAMS",
+		string.format("`%s` is not a position.", field),
+		'Write it the way the Properties panel does: "12, 0, 5".'
+	)
+	error("unreachable")
+end
+
+local function optionalVector(value: any, field: string): Vector3?
+	if value == nil or value == "" then
+		return nil
+	end
+	return vector(value, field)
+end
+
+--[[
+	Builds the filter every query shares.
+
+	`ignore` and `only` are the same engine field with the list flipped, because
+	"everything except the character" and "only the doors" are both common and
+	only one of them is expressible at a time. Naming a path that no longer
+	exists is a caller mistake worth reporting: silently querying against an
+	empty filter gives a plausible answer to the wrong question.
+]]
+local function buildParams(params: { [string]: any }): RaycastParams
+	local query = RaycastParams.new()
+
+	local list = params.only or params.ignore
+	if list ~= nil then
+		if typeof(list) ~= "table" then
+			Dispatch.fail("BAD_PARAMS", "`ignore` and `only` take a list of paths.")
+		end
+		local resolved, missing = Paths.resolveMany(list :: { string })
+		if #missing > 0 then
+			Dispatch.fail(
+				"NOT_FOUND",
+				string.format("Could not resolve: %s", table.concat(missing, ", "))
+			)
+		end
+		query.FilterDescendantsInstances = resolved
+		query.FilterType = if params.only ~= nil
+			then Enum.RaycastFilterType.Include
+			else Enum.RaycastFilterType.Exclude
+	end
+
+	if typeof(params.collisionGroup) == "string" and params.collisionGroup ~= "" then
+		query.CollisionGroup = params.collisionGroup
+	end
+	-- Off by default, matching the engine. A caller asking "can the player see
+	-- the exit" usually does want water ignored; one asking "what is here" does
+	-- not, and neither can be guessed.
+	query.RespectCanCollide = params.respectCanCollide == true
+	query.IgnoreWater = params.ignoreWater == true
+	query.BruteForceAllSlow = false
+	return query
+end
+
+local function describeHit(result: RaycastResult, origin: Vector3): { [string]: any }
+	return {
+		path = Paths.of(result.Instance),
+		class = result.Instance.ClassName,
+		position = Serialize.value(result.Position),
+		normal = Serialize.value(result.Normal),
+		material = tostring(result.Material):gsub("Enum%.Material%.", ""),
+		distance = math.round((result.Position - origin).Magnitude * 100) / 100,
+	}
+end
+
+local function describePart(part: BasePart): { [string]: any }
+	return {
+		path = Paths.of(part),
+		class = part.ClassName,
+		position = Serialize.value(part.Position),
+		size = Serialize.value(part.Size),
+		collisionGroup = part.CollisionGroup,
+		canCollide = part.CanCollide,
+	}
+end
+
+--[[
+	Casts a ray, a block or a sphere.
+
+	The three are one operation with one extra argument, and the engine treats
+	them that way too -- `Blockcast` and `Spherecast` take the same params and
+	return the same RaycastResult. Splitting them into three handlers would only
+	mean three copies of the filter code.
+
+	A miss is reported as `hit = false` with the distance travelled, not as an
+	error and not as an empty object. "Nothing is in the way" is a real answer
+	and usually the one being checked for.
+]]
+function Spatial.cast(params: { [string]: any }): { [string]: any }
+	local world = root(params) :: WorldRoot
+	local shape = tostring(params.shape or "ray")
+
+	local origin = vector(params.from, "from")
+
+	--[[
+		Direction is given either as a target point or as a vector, because both
+		are natural and they are not interchangeable. "Can the turret see the
+		player" is two positions; "is there ground below" is a direction and a
+		distance. Taking only one of them forces the caller to do vector maths
+		in the prompt, which is exactly where an off-by-one sign lives.
+	]]
+	local direction: Vector3
+	local to = optionalVector(params.to, "to")
+	if to then
+		direction = to - origin
+	else
+		local towards = optionalVector(params.direction, "direction")
+		if not towards then
+			Dispatch.fail(
+				"BAD_PARAMS",
+				"A cast needs somewhere to go.",
+				"Give `to` for a point to aim at, or `direction` plus `distance`."
+			)
+			error("unreachable")
+		end
+		local distance = tonumber(params.distance) or 100
+		direction = towards.Unit * distance
+	end
+
+	local query = buildParams(params)
+	local result: RaycastResult?
+
+	if shape == "ray" then
+		result = world:Raycast(origin, direction, query)
+	elseif shape == "block" then
+		local size = optionalVector(params.size, "size") or Vector3.new(1, 1, 1)
+		result = world:Blockcast(CFrame.new(origin), size, direction, query)
+	elseif shape == "sphere" then
+		local radius = tonumber(params.radius) or 1
+		result = world:Spherecast(origin, radius, direction, query)
+	else
+		Dispatch.fail(
+			"BAD_PARAMS",
+			string.format("unknown cast shape %q", shape),
+			'Use "ray", "block" or "sphere".'
+		)
+	end
+
+	if not result then
+		return {
+			hit = false,
+			shape = shape,
+			from = Serialize.value(origin),
+			travelled = math.round(direction.Magnitude * 100) / 100,
+			world = Paths.of(world),
+			note = "Nothing was in the way for the whole length of the cast.",
+		}
+	end
+
+	local hit = describeHit(result, origin)
+	hit.hit = true
+	hit.shape = shape
+	hit.from = Serialize.value(origin)
+	hit.world = Paths.of(world)
+	return hit
+end
+
+--[[
+	Everything inside a volume.
+
+	`part` is the one worth reaching for on a build: it takes an existing part
+	and reports what overlaps it, which answers "is this door clipping the wall"
+	directly rather than by reconstructing the door's bounds by hand.
+]]
+function Spatial.overlap(params: { [string]: any }): { [string]: any }
+	local world = root(params) :: WorldRoot
+	local region = tostring(params.region or "box")
+	local limit = math.clamp(tonumber(params.limit) or DEFAULT_LIMIT, 1, MAX_LIMIT)
+
+	local overlap = OverlapParams.new()
+	local query = buildParams(params)
+	overlap.FilterDescendantsInstances = query.FilterDescendantsInstances
+	overlap.FilterType = query.FilterType
+	overlap.CollisionGroup = query.CollisionGroup
+	overlap.RespectCanCollide = query.RespectCanCollide
+	-- Asked for one over the limit so the response can say whether the list was
+	-- cut, instead of a caller reading exactly 50 as "there are 50".
+	overlap.MaxParts = limit + 1
+
+	local found: { BasePart }
+	local about: { [string]: any } = {}
+
+	if region == "box" then
+		local centre = vector(params.at, "at")
+		local size = optionalVector(params.size, "size") or Vector3.new(4, 4, 4)
+		found = world:GetPartBoundsInBox(CFrame.new(centre), size, overlap)
+		about.at, about.size = Serialize.value(centre), Serialize.value(size)
+	elseif region == "radius" then
+		local centre = vector(params.at, "at")
+		local radius = tonumber(params.radius) or 4
+		found = world:GetPartBoundsInRadius(centre, radius, overlap)
+		about.at, about.radius = Serialize.value(centre), radius
+	elseif region == "part" then
+		local path = params.path
+		if typeof(path) ~= "string" or path == "" then
+			Dispatch.fail("BAD_PARAMS", 'region="part" needs `path`, the part to test.')
+		end
+		local instance = Paths.resolve(path)
+		if not instance:IsA("BasePart") then
+			Dispatch.fail(
+				"BAD_PARAMS",
+				string.format("%s is a %s, not a part.", path, instance.ClassName)
+			)
+		end
+		local subject = instance :: BasePart
+		--[[
+			The subject always overlaps itself, and a caller who asked what
+			touches a door does not mean the door. Added to the filter rather
+			than stripped from the results, so it does not eat one of the slots
+			the limit allows.
+		]]
+		if overlap.FilterType == Enum.RaycastFilterType.Exclude then
+			local excluded = overlap.FilterDescendantsInstances
+			table.insert(excluded, subject)
+			overlap.FilterDescendantsInstances = excluded
+		end
+		found = world:GetPartsInPart(subject, overlap)
+		about.path = Paths.of(subject)
+	else
+		Dispatch.fail(
+			"BAD_PARAMS",
+			string.format("unknown region %q", region),
+			'Use "box", "radius" or "part".'
+		)
+		error("unreachable")
+	end
+
+	local truncated = #found > limit
+	local items: { { [string]: any } } = {}
+	for index, part in found do
+		if index > limit then
+			break
+		end
+		table.insert(items, describePart(part))
+	end
+
+	about.region = region
+	about.items = items
+	about.count = #items
+	about.truncated = truncated
+	about.world = Paths.of(world)
+	if truncated then
+		about.note = string.format(
+			"More than %d parts are in this volume; raise `limit` or narrow with `only`.",
+			limit
+		)
+	end
+	return about
+end
+
+function Spatial.register()
+	Dispatch.registerAll("spatial", {
+		cast = Spatial.cast,
+		overlap = Spatial.overlap,
+	})
+end
+
+return Spatial

package/plugin/src/handlers/Viewport.luau

@@ -15,10 +15,12 @@
 
 local RunService = game:GetService("RunService")
 local Selection = game:GetService("Selection")
+local StarterGui = game:GetService("StarterGui")
 local TextService = game:GetService("TextService")
 local Workspace = game:GetService("Workspace")
 
 local Dispatch = require(script.Parent.Parent.Dispatch)
+local Emulation = require(script.Parent.Parent.Emulation)
 local Paths = require(script.Parent.Parent.Paths)
 local Serialize = require(script.Parent.Parent.Serialize)
 
@@ -403,8 +405,274 @@ function Viewport.textbounds(params: { [string]: any }): { [string]: any }
 	return report
 end
 
+--[[
+	Every interface fault that is invisible in the data model.
+
+	`textbounds` already answers "does this text fit its label". This is the same
+	question asked of the whole screen, and it exists because the data model
+	cannot answer it at all: a button positioned off the side of a phone has a
+	perfectly correct `Position`, a `Size` that is not zero, and a parent that is
+	visible. Nothing about the instance is wrong. It is simply not where anyone
+	can reach it, and the only ways to find that out today are to play the game
+	or to look at a picture.
+
+	Studio lays StarterGui out for real in edit mode -- measured:
+	`AbsolutePosition` and `AbsoluteSize` carry live values with nothing running,
+	and they move when a device is emulated. So the audit runs against whatever
+	`device` is currently emulating, which is what makes it worth running twice:
+	once on desktop, once on a phone.
+
+	It reports rather than judges. Every finding names the element and the
+	number, so a caller can decide whether a label four pixels off the edge is a
+	bug or a deliberate bleed.
+]]
+
+--[[
+	Text below this many pixels tall is not readable on a phone.
+
+	Roblox's own UI guidance and every accessibility standard land in the same
+	place: somewhere around 12 device-independent pixels is the floor for body
+	text. 10 is used here because it is the point past which there is no
+	argument -- a label under it is unreadable on any display, not merely small.
+]]
+local MIN_TEXT_PIXELS = 10
+
+--[[
+	Pairs compared for overlap before the check gives up.
+
+	Overlap is quadratic in the number of siblings, and a scrolling list of two
+	hundred rows is both a legitimate design and forty thousand comparisons of
+	rectangles that are supposed to sit next to each other. Past this the check
+	reports that it stopped rather than continuing to spend the user's frame on
+	an answer nobody asked for.
+]]
+local MAX_OVERLAP_PAIRS = 2000
+
+local function rectOf(element: GuiObject): (number, number, number, number)
+	local position = element.AbsolutePosition
+	local size = element.AbsoluteSize
+	return position.X, position.Y, position.X + size.X, position.Y + size.Y
+end
+
+local function overlaps(a: GuiObject, b: GuiObject): boolean
+	local ax1, ay1, ax2, ay2 = rectOf(a)
+	local bx1, by1, bx2, by2 = rectOf(b)
+	return ax1 < bx2 and bx1 < ax2 and ay1 < by2 and by1 < ay2
+end
+
+--[[
+	Whether this element is actually on screen at all.
+
+	Walks up rather than trusting `Visible`: an element with Visible true inside
+	a frame with Visible false is not on screen, and reporting it as a fault
+	would bury the real findings under every hidden menu in the place.
+]]
+local function shown(element: Instance): boolean
+	local node: Instance? = element
+	while node ~= nil and not node:IsA("LayerCollector") do
+		if node:IsA("GuiObject") and not (node :: GuiObject).Visible then
+			return false
+		end
+		node = node.Parent
+	end
+	if node ~= nil and node:IsA("ScreenGui") then
+		return (node :: ScreenGui).Enabled
+	end
+	return node ~= nil
+end
+
+function Viewport.ui(params: { [string]: any }): { [string]: any }
+	local root: Instance = if typeof(params.path) == "string" and params.path ~= ""
+		then Paths.resolve(params.path)
+		else StarterGui
+
+	local camera = Workspace.CurrentCamera
+	if camera == nil then
+		Dispatch.fail("NO_CAMERA", "This session has no camera, so there is no screen to measure against.")
+	end
+	local screen = (camera :: Camera).ViewportSize
+	local screenWidth, screenHeight = math.floor(screen.X), math.floor(screen.Y)
+
+	local elements: { GuiObject } = {}
+	for _, descendant in root:GetDescendants() do
+		if descendant:IsA("GuiObject") then
+			table.insert(elements, descendant :: GuiObject)
+		end
+	end
+
+	local findings: { { [string]: any } } = {}
+	local checked = 0
+	local hidden = 0
+
+	local function report(element: GuiObject, issue: string, detail: string)
+		if #findings >= 100 then
+			return
+		end
+		table.insert(findings, {
+			path = Paths.of(element),
+			name = element.Name,
+			className = element.ClassName,
+			issue = issue,
+			detail = detail,
+		})
+	end
+
+	local visible: { GuiObject } = {}
+
+	for _, element in elements do
+		if not shown(element) then
+			hidden += 1
+			continue
+		end
+		checked += 1
+		table.insert(visible, element)
+
+		local size = element.AbsoluteSize
+		local position = element.AbsolutePosition
+
+		if size.X <= 0 or size.Y <= 0 then
+			report(element, "zero size", string.format("%.0f x %.0f -- nothing is drawn", size.X, size.Y))
+			continue
+		end
+
+		--[[
+			Off screen, and by how much.
+
+			Reported as a measurement rather than a yes/no, because the two cases
+			it covers are different bugs: an element wholly outside the screen was
+			positioned for a display that is not this one, and one clipped at an
+			edge is usually a layout that does not fit. The numbers tell them
+			apart; a boolean would not.
+		]]
+		local right = position.X + size.X
+		local bottom = position.Y + size.Y
+		if right <= 0 or bottom <= 0 or position.X >= screenWidth or position.Y >= screenHeight then
+			report(
+				element,
+				"off screen",
+				string.format(
+					"at %.0f,%.0f on a %dx%d screen -- entirely outside it",
+					position.X,
+					position.Y,
+					screenWidth,
+					screenHeight
+				)
+			)
+		elseif position.X < 0 or position.Y < 0 or right > screenWidth or bottom > screenHeight then
+			report(
+				element,
+				"clipped",
+				string.format(
+					"%.0f,%.0f to %.0f,%.0f runs past the %dx%d screen",
+					position.X,
+					position.Y,
+					right,
+					bottom,
+					screenWidth,
+					screenHeight
+				)
+			)
+		end
+
+		if element:IsA("TextLabel") or element:IsA("TextButton") or element:IsA("TextBox") then
+			local text = element :: any
+			--[[
+				The size the text is actually drawn at, which is not TextSize when
+				TextScaled is on: the engine then fits the string to the box and
+				`TextBounds` is the only honest report of the result.
+			]]
+			local drawn = if text.TextScaled then text.TextBounds.Y else text.TextSize
+			if drawn > 0 and drawn < MIN_TEXT_PIXELS and text.Text ~= "" then
+				report(
+					element,
+					"text too small",
+					string.format("%.0fpx -- under %dpx is unreadable on a phone", drawn, MIN_TEXT_PIXELS)
+				)
+			end
+			if text.TextTruncate == Enum.TextTruncate.None and not text.TextScaled and not text.TextWrapped then
+				if text.TextBounds.X > size.X + 1 then
+					report(
+						element,
+						"text overflows",
+						string.format("needs %.0fpx, has %.0fpx", text.TextBounds.X, size.X)
+					)
+				end
+			end
+		end
+	end
+
+	--[[
+		Overlap between siblings only.
+
+		A child sitting on top of its parent is the normal way UI is built, and
+		reporting it would make the check useless. Two buttons in the same frame
+		covering each other is the fault worth naming.
+	]]
+	--[[
+		Whether an element is something a user reads or presses.
+
+		Overlap between decoration is not a fault, it is how UI is built: a drop
+		shadow sits under a panel, a bevel sits under a label, a playhead sits
+		over a timeline. Measured on a real HUD, the first version of this check
+		reported four overlaps and all four were of that kind -- a Frame named
+		Shadow behind the three things it was drawn to sit behind.
+
+		Two pieces of TEXT on top of each other, or two images, is the fault
+		worth naming. So a plain coloured Frame is not counted; something
+		carrying text or an image is.
+	]]
+	local function carriesContent(element: GuiObject): boolean
+		if element:IsA("TextLabel") or element:IsA("TextButton") or element:IsA("TextBox") then
+			return (element :: any).Text ~= ""
+		end
+		if element:IsA("ImageLabel") or element:IsA("ImageButton") then
+			return (element :: any).Image ~= ""
+		end
+		return false
+	end
+
+	local pairs = 0
+	local stopped = false
+	for index = 1, #visible do
+		for other = index + 1, #visible do
+			if pairs >= MAX_OVERLAP_PAIRS then
+				stopped = true
+				break
+			end
+			local a, b = visible[index], visible[other]
+			if a.Parent == b.Parent then
+				pairs += 1
+				if
+					overlaps(a, b)
+					and a.AbsoluteSize.X > 0
+					and b.AbsoluteSize.X > 0
+					and carriesContent(a)
+					and carriesContent(b)
+				then
+					report(a, "overlaps", string.format("covers or is covered by %s", b.Name))
+				end
+			end
+		end
+		if stopped then
+			break
+		end
+	end
+
+	return {
+		screen = string.format("%dx%d", screenWidth, screenHeight),
+		device = Emulation.deviceId(),
+		root = Paths.of(root),
+		checked = checked,
+		hidden = hidden,
+		findings = findings,
+		findingCount = #findings,
+		overlapStopped = stopped,
+	}
+end
+
 function Viewport.register()
 	Dispatch.registerAll("viewport", {
+		ui = Viewport.ui,
 		textbounds = Viewport.textbounds,
 		raycast = Viewport.raycast,
 		select = Viewport.select,