@el4cteo/rbx-studio-mcp 0.8.0 → 0.8.3

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/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")

package/plugin/src/handlers/Debug.luau

@@ -69,6 +69,8 @@ local Dispatch = require(script.Parent.Parent.Dispatch)
 local Paths = require(script.Parent.Parent.Paths)
 local ClientRelay = require(script.Parent.Parent.ClientRelay)
 local RemoteTrace = require(script.Parent.Parent.RemoteTrace)
+local ScriptEdit = require(script.Parent.Parent.ScriptEdit)
+local TextEdit = require(script.Parent.Parent.TextEdit)
 
 -- Snapshots are far heavier than log lines: each carries a stack and its
 -- variables. A tight cap keeps a breakpoint inside a loop from exhausting memory
@@ -288,6 +290,9 @@ function Debug.set(params: { [string]: any }): { [string]: any }
 
 	local added: { { [string]: any } } = {}
 	local failed: { { [string]: any } } = {}
+	-- How many of `failed` were lines the script does not have, as opposed to
+	-- refusals from the debugger itself. See below.
+	local outside = 0
 
 	for _, item in requested :: { { [string]: any } } do
 		local target = Paths.resolve(item.path)
@@ -298,6 +303,31 @@ function Debug.set(params: { [string]: any }): { [string]: any }
 			)
 		end
 
+		--[[
+			A line the script does not have is knowable here, so it is refused here.
+
+			It used to go to `AddBreakpoint` like any other, which refuses it with
+			nothing to say -- and the refusal below then blamed the "Debugger Luau
+			API" beta, so a mistyped line number sent people off to change a Studio
+			setting that was already on.
+		]]
+		local wanted = tonumber(item.line)
+		local lineCount = #TextEdit.toLines(ScriptEdit.read(target :: LuaSourceContainer))
+		if wanted == nil or wanted < 1 or wanted > lineCount then
+			outside += 1
+			table.insert(failed, {
+				path = item.path,
+				line = wanted,
+				error = string.format(
+					"the script has %d line%s, so line %s does not exist",
+					lineCount,
+					if lineCount == 1 then "" else "s",
+					tostring(item.line)
+				),
+			})
+			continue
+		end
+
 		--[[
 			Capitalised keys, from Roblox's example -- `Line`, `Condition`,
 			`LogMessage`, `ContinueExecution`. Lowercase `line` was rejected.
@@ -372,6 +402,18 @@ function Debug.set(params: { [string]: any }): { [string]: any }
 		a user's script just to answer a status question. So the hint says what
 		to check first and what else it could be, and does not claim to know.
 	]]
+	if #added == 0 and outside > 0 and outside == #failed then
+		local reasons: { string } = {}
+		for _, entry in failed do
+			table.insert(reasons, string.format("%s: %s", tostring(entry.path), tostring(entry.error)))
+		end
+		Dispatch.fail(
+			"BAD_LINE",
+			string.format("No breakpoint was set: %s.", table.concat(reasons, "; ")),
+			"Read the script with `script_read` for its line numbers -- they shift after every edit."
+		)
+	end
+
 	if #added == 0 and #failed > 0 then
 		Dispatch.fail(
 			"NO_BREAKPOINTS_SET",

package/plugin/src/handlers/Device.luau

@@ -130,29 +130,21 @@ end
 	`poor` is deliberately harsh -- crowded stadium wifi, a phone on one bar --
 	because the failures worth finding only appear at the far end.
 
-	Loss is the percentage of packets thrown away, and it is the field that finds
-	the interesting bugs: latency makes a game feel slow, loss makes it behave
-	wrongly.
+	Loss is the percentage of packets thrown away. Roblox caps it at 0.5%, so
+	the presets climb to that ceiling rather than to real-world figures the
+	engine would clamp anyway.
 ]]
 local PRESETS: { [string]: { latency: number, jitter: number, loss: number } } = {
 	clear = { latency = 0, jitter = 0, loss = 0 },
 	wifi = { latency = 15, jitter = 5, loss = 0 },
-	["4g"] = { latency = 60, jitter = 15, loss = 0.5 },
-	["3g"] = { latency = 150, jitter = 40, loss = 2 },
-	poor = { latency = 400, jitter = 120, loss = 8 },
+	["4g"] = { latency = 60, jitter = 15, loss = 0.1 },
+	["3g"] = { latency = 150, jitter = 40, loss = 0.3 },
+	poor = { latency = 400, jitter = 120, loss = 0.5 },
 }
 
---[[
-	Percent in, fraction out.
-
-	`InboundNetworkLossPercent` does not take a percentage: it takes a fraction
-	and clamps at 0.5. Writing 2 for "2% loss" succeeds, lands at 0.5, and
-	degrades half the traffic -- a hundred times what was asked for, with no
-	error anywhere. Every caller of this file speaks percent, so the conversion
-	is here and only here.
-]]
-local function lossFraction(percent: number): number
-	return math.clamp(percent, 0, Emulation.LOSS_LIMIT_PERCENT) / 100
+-- Percent in, percent out: the property takes a percentage, capped at 0.5.
+local function lossPercent(percent: number): number
+	return math.clamp(percent, 0, Emulation.LOSS_LIMIT_PERCENT)
 end
 
 local function presetNames(): string
@@ -180,6 +172,19 @@ local function apply(service: any, property: string, value: number, refused: { s
 	end
 end
 
+--[[
+	Takes the memory cap off by writing the machine's real memory back. 0 is
+	not "no cap" to the engine -- it is a device with no memory -- so nothing
+	here writes it.
+]]
+local function uncapMemory(service: any, refused: { string })
+	local real = Emulation.machineMemory()
+	if real ~= nil then
+		apply(service, "EmulatedTotalMemoryInMB", real, refused)
+	end
+	Emulation.setMemoryCap(nil)
+end
+
 --[[
 	Degrades the connection on purpose.
 
@@ -224,9 +229,8 @@ function Device.network(params: { [string]: any }): { [string]: any }
 		latency, jitter, loss = preset.latency, preset.jitter, preset.loss
 		-- "clear" is a whole-connection word, so it takes the memory cap with
 		-- it. Any other preset says nothing about memory and leaves it alone.
-		if name == "clear" then
-			apply(service, "EmulatedTotalMemoryInMB", 0, {})
-			Emulation.setMemoryCap(nil)
+		if name == "clear" and Emulation.memoryCap() ~= nil then
+			uncapMemory(service, {})
 		end
 	end
 
@@ -311,17 +315,21 @@ function Device.network(params: { [string]: any }): { [string]: any }
 		end
 	end
 	if loss ~= nil then
-		local fraction = lossFraction(loss)
+		local percent = lossPercent(loss)
 		if inbound then
-			apply(service, "InboundNetworkLossPercent", fraction, refused)
+			apply(service, "InboundNetworkLossPercent", percent, refused)
 		end
 		if outbound then
-			apply(service, "OutboundNetworkLossPercent", fraction, refused)
+			apply(service, "OutboundNetworkLossPercent", percent, refused)
 		end
 	end
 	if memory ~= nil then
-		apply(service, "EmulatedTotalMemoryInMB", memory, refused)
-		Emulation.setMemoryCap(memory)
+		if memory > 0 then
+			apply(service, "EmulatedTotalMemoryInMB", memory, refused)
+			Emulation.setMemoryCap(memory)
+		else
+			uncapMemory(service, refused)
+		end
 	end
 
 	local state = Emulation.network()
@@ -358,8 +366,11 @@ function Device.stop(_params: { [string]: any }): { [string]: any }
 		apply(service, "OutboundNetworkMinDelayMs", 0, ignored)
 		apply(service, "OutboundNetworkJitterMs", 0, ignored)
 		apply(service, "OutboundNetworkLossPercent", 0, ignored)
-		apply(service, "EmulatedTotalMemoryInMB", 0, ignored)
-		Emulation.setMemoryCap(nil)
+		-- Only a cap this plugin set is undone. Studio's own simulator restores
+		-- its value when it stops, and writing over that is what left 0 behind.
+		if Emulation.memoryCap() ~= nil then
+			uncapMemory(service, ignored)
+		end
 	end
 
 	--[[

package/plugin/src/handlers/Exec.luau

@@ -160,7 +160,11 @@ end)
 report:FireServer(if ok then result else { ok = false, error = tostring(result), output = {}, milliseconds = 0 })
 ]==], { Timeout = timeout }, timeout + 5, function(relay)
 			-- These modules are required ONLY by the LocalScript, sharing the game's client VM.
-			for _, name in { "ExecRuntime", "Serialize", "Paths", "Dispatch" } do
+			-- Everything ExecRuntime requires has to be listed too: the plugin's own module
+			-- tree does not exist in the client, so `script.Parent.LogBuffer` finds only
+			-- what is cloned beside it. Leaving LogBuffer out made every client run fail
+			-- with "Requested module experienced an error while loading".
+			for _, name in { "ExecRuntime", "LogBuffer", "Serialize", "Paths", "Dispatch" } do
 				local copy = script.Parent.Parent[name]:Clone()
 				copy.Parent = relay
 			end

package/plugin/src/handlers/Generate.luau

@@ -25,6 +25,7 @@
 ]]
 
 local Dispatch = require(script.Parent.Parent.Dispatch)
+local Serialize = require(script.Parent.Parent.Serialize)
 local Paths = require(script.Parent.Parent.Paths)
 local Undo = require(script.Parent.Parent.Undo)
 
@@ -89,15 +90,17 @@ local function carryLook(source: MeshPart, model: Model)
 	end
 end
 
+-- Absent is nil; present but malformed fails, rather than being taken as absent
+-- and quietly replaced by a default the caller never asked for.
 local function parseVector(text: any): Vector3?
-	if typeof(text) ~= "string" or text == "" then
+	if text == nil or text == "" then
 		return nil
 	end
-	local x, y, z = string.match(text, "^%s*(-?[%d%.]+)%s*,%s*(-?[%d%.]+)%s*,%s*(-?[%d%.]+)%s*$")
-	if x == nil then
-		return nil
+	local ok, value = Serialize.parse(text, "Vector3")
+	if not ok then
+		Dispatch.fail("BAD_PARAMS", string.format("%q is not an \"x, y, z\" vector.", tostring(text)))
 	end
-	return Vector3.new(tonumber(x) :: number, tonumber(y) :: number, tonumber(z) :: number)
+	return value :: Vector3
 end
 
 local function service(): any

package/plugin/src/handlers/Geometry.luau

@@ -56,15 +56,17 @@ local function carryAppearance(source: BasePart, target: BasePart)
 	end
 end
 
+-- Absent is nil; present but malformed fails, rather than being taken as absent
+-- and quietly replaced by a default the caller never asked for.
 local function parseVector(text: any): Vector3?
-	if typeof(text) ~= "string" or text == "" then
+	if text == nil or text == "" then
 		return nil
 	end
-	local x, y, z = string.match(text, "^%s*(-?[%d%.]+)%s*,%s*(-?[%d%.]+)%s*,%s*(-?[%d%.]+)%s*$")
-	if x == nil then
-		return nil
+	local ok, value = Serialize.parse(text, "Vector3")
+	if not ok then
+		Dispatch.fail("BAD_PARAMS", string.format("%q is not an \"x, y, z\" vector.", tostring(text)))
 	end
-	return Vector3.new(tonumber(x) :: number, tonumber(y) :: number, tonumber(z) :: number)
+	return value :: Vector3
 end
 
 local function resolveParts(paths: any, what: string): { BasePart }

package/plugin/src/handlers/Perf.luau

@@ -150,6 +150,7 @@ function Perf.console(params: { [string]: any }): { [string]: any }
 			timestamp = item.timestamp,
 			stack = item.stack,
 			source = item.source,
+			context = item.context,
 		})
 	end
 

package/plugin/src/handlers/Playtest.luau

@@ -68,8 +68,12 @@ end
 
 local function state(): { [string]: any }
 	local players = {}
-	for _, player in game:GetService("Players"):GetPlayers() do
-		table.insert(players, { name = player.Name, userId = player.UserId })
+	-- Only while a test runs: straight after `stop` the editor still lists the
+	-- departing player for a moment, and the reply said one was present.
+	if RunService:IsRunning() then
+		for _, player in game:GetService("Players"):GetPlayers() do
+			table.insert(players, { name = player.Name, userId = player.UserId })
+		end
 	end
 	return {
 		playtestsAllowed = Playtest.isAllowed(),
@@ -121,13 +125,46 @@ end
 
 function Playtest.control(params: { [string]: any }): { [string]: any }
 	local op = params.op
-	if op == "play" or op == "run" or op == "multiplayer" then requireAllowed() end
+	if op == "play" or op == "run" or op == "multiplayer" or op == "addPlayers" then requireAllowed() end
 	local before = state()
 
 	if op == "state" then
 		return { changed = false, state = before }
 	end
 
+	--[[
+		More players joining a test already running: staggered joins, lobby
+		fill-up, the race a second player hits that the first never does.
+
+		Served by the playtest's server session, the only place AddPlayers may be
+		called from; the MCP server routes it there. Returns straight away --
+		new clients take seconds to load, and the caller polls `state` for them.
+	]]
+	if op == "addPlayers" then
+		if RunService:IsEdit() or not RunService:IsServer() then
+			Dispatch.fail(
+				"NOT_RUNNING",
+				"Players can only be added from the server of a running test.",
+				"Start one with `playtest op=\"multiplayer\"` first."
+			)
+		end
+		local count = tonumber(params.players) or 1
+		if count < 1 or count > 8 then
+			Dispatch.fail("BAD_PARAMS", "players must be between 1 and 8.")
+		end
+		local ok, err = pcall(function()
+			service():AddPlayers(count)
+		end)
+		if not ok then
+			Dispatch.fail(
+				"ADD_PLAYERS_FAILED",
+				string.format("Studio refused to add players: %s", tostring(err)),
+				"AddPlayers works in a multiplayer test only, not in Play or Run."
+			)
+		end
+		return { changed = true, state = before }
+	end
+
 	--[[
 		Ending a test has to happen inside it.
 

package/plugin/src/handlers/Spatial.luau

@@ -191,6 +191,24 @@ function Spatial.cast(params: { [string]: any }): { [string]: any }
 		end
 		local distance = tonumber(params.distance) or 100
 		direction = towards.Unit * distance
+		--[[
+			Checked below, once `direction` is settled: a zero `direction` has a NaN
+			`Unit`, so it only shows up as a NaN length by the time it gets there.
+		]]
+	end
+
+	--[[
+		A cast with no length is not a cast. `to` equal to `from`, a zero `direction`
+		(whose `Unit` is NaN) or a zero `distance` all end up here, and every shape
+		then "misses" -- reported as a clear line of sight, which is the opposite of
+		"nothing was checked".
+	]]
+	if direction.Magnitude == 0 or direction.Magnitude ~= direction.Magnitude then
+		Dispatch.fail(
+			"BAD_PARAMS",
+			"The cast has no length, so nothing was checked.",
+			"`to` is the same point as `from`, or `direction` or `distance` is zero. Give it somewhere to go."
+		)
 	end
 
 	local query = buildParams(params)
@@ -259,11 +277,27 @@ function Spatial.overlap(params: { [string]: any }): { [string]: any }
 	if region == "box" then
 		local centre = vector(params.at, "at")
 		local size = optionalVector(params.size, "size") or Vector3.new(4, 4, 4)
+		-- A box with no volume overlaps nothing by construction, which then reads
+		-- as "that space is clear" -- an answer to a question nobody asked.
+		if size.X <= 0 or size.Y <= 0 or size.Z <= 0 then
+			Dispatch.fail(
+				"BAD_PARAMS",
+				string.format("`size` is %s, which has no volume.", tostring(size)),
+				"Every side has to be greater than zero."
+			)
+		end
 		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
+		if radius <= 0 then
+			Dispatch.fail(
+				"BAD_PARAMS",
+				string.format("`radius` is %s, which has no volume.", tostring(radius)),
+				"Give a radius greater than zero."
+			)
+		end
 		found = world:GetPartBoundsInRadius(centre, radius, overlap)
 		about.at, about.radius = Serialize.value(centre), radius
 	elseif region == "part" then