@el4cteo/rbx-studio-mcp 0.6.5 → 0.6.7

package/plugin/src/handlers/Instances.luau

@@ -116,7 +116,17 @@ end
 	model appears in the Explorer complete rather than assembling itself piece by
 	piece in front of the user.
 ]]
-local function build(spec: { [string]: any }, parent: Instance, created: { Instance })
+--[[
+	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,
+	created: { Instance },
+	deferred: { Deferred }
+)
 	local ok, instance = pcall(Instance.new, spec.className)
 	if not ok or typeof(instance) ~= "Instance" then
 		Dispatch.fail(
@@ -132,11 +142,37 @@ local function build(spec: { [string]: any }, parent: Instance, created: { Insta
 		target.Name = spec.name
 	end
 
+	--[[
+		A property naming an instance that does not exist YET is set aside, not
+		failed.
+
+		The whole subtree is assembled detached and attached at the very end --
+		see the last line of this function -- so while a batch is being built,
+		nothing in it is reachable by path. That made a one-call rig impossible:
+		a HingeConstraint could not point at the Attachment created two lines
+		above it, a Motor6D could not find its Part0, and the tool's own promise
+		of "build a whole model in a single call" stopped exactly where joints
+		began. Each of those needed a second `create` call, which is also a
+		second undo step.
+
+		So these are retried once the batch is attached. Anything else -- a
+		misspelled enum, a malformed Vector3 -- still fails immediately, because
+		waiting cannot make it right.
+	]]
 	local failures: { string } = {}
 	for name, property in (spec.properties or {}) :: { [string]: PropertySpec } do
 		local failure = applyProperty(target, name, property)
 		if failure then
-			table.insert(failures, failure)
+			if string.find(failure, Serialize.UNRESOLVED_PREFIX, 1, true) then
+				table.insert(deferred, {
+					target = target,
+					name = name,
+					spec = property,
+					className = tostring(spec.className),
+				})
+			else
+				table.insert(failures, failure)
+			end
 		end
 	end
 	for _, failure in applyAttributes(target, (spec.attributes or {}) :: { [string]: any }) do
@@ -158,7 +194,7 @@ local function build(spec: { [string]: any }, parent: Instance, created: { Insta
 	-- Recorded parent-first, so the response reads top-down like the Explorer.
 	table.insert(created, target)
 	for _, child in (spec.children or {}) :: { { [string]: any } } do
-		build(child, target, created)
+		build(child, target, created, deferred)
 	end
 
 	target.Parent = parent
@@ -183,8 +219,52 @@ function Instances.create(params: { [string]: any }): { [string]: any }
 
 	local created, recorded = Undo.record("StudioMCP.Create", "MCP create", function()
 		local built: { Instance } = {}
+		local deferred: { Deferred } = {}
 		for _, spec in specs do
-			build(spec, Paths.resolve(spec.parent), built)
+			build(spec, Paths.resolve(spec.parent), built, deferred)
+		end
+
+		--[[
+			Second pass, after everything is attached.
+
+			Now every instance in the batch is reachable by path, so a reference
+			to a sibling resolves. A failure here is real -- the path names
+			something that was never going to exist -- and it fails the batch,
+			which cancels the recording and leaves the place untouched.
+		]]
+		local failures: { string } = {}
+		for _, entry in deferred do
+			local failure = applyProperty(entry.target, entry.name, entry.spec)
+			if failure then
+				--[[
+					Stripped with find+sub, NOT gsub.
+
+					`string.gsub` takes a Lua PATTERN, and the marker is
+					"[unresolved] " -- which as a pattern is a character class
+					matching any one of u, n, r, e, s, o, l, v, d. It quietly
+					ate those letters out of the whole message, turning "this
+					property holds a BasePart" into "thiproperty holda
+					BasePart". Caught in QA; the message is the only thing a
+					reader gets here, so a mangled one is the whole failure.
+
+					The property name is already inside `failure`, so it is not
+					prepended a second time -- that read as "Part1: Part1: ...".
+				]]
+				local clean = failure
+				local at = string.find(clean, Serialize.UNRESOLVED_PREFIX, 1, true)
+				if at then
+					clean = string.sub(clean, 1, at - 1)
+						.. string.sub(clean, at + #Serialize.UNRESOLVED_PREFIX)
+				end
+				table.insert(failures, string.format("%s.%s", entry.className, clean))
+			end
+		end
+		if #failures > 0 then
+			Dispatch.fail(
+				"BAD_PROPERTY",
+				string.format("Could not set %d reference(s) after the batch was built.", #failures),
+				table.concat(failures, "; ")
+			)
 		end
 		return built
 	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