@el4cteo/rbx-studio-mcp 0.7.1 → 0.7.5

package/plugin/src/ExecRuntime.luau

@@ -0,0 +1,161 @@
+--!strict
+-- Shared bounded execution results in the VM that calls run.
+local LogService = game:GetService("LogService")
+local Serialize = require(script.Parent.Serialize)
+-- A chunk that prints in a loop would otherwise return a response no context
+-- window can hold.
+local MAX_OUTPUT_LINES = 200
+local MAX_RETURN_VALUES = 10
+
+-- Returned tables are walked rather than counted, but not without limit: a
+-- chunk that returns a whole config tree, or one with a cycle in it, must not be
+-- able to produce a response nothing can read.
+local MAX_TABLE_ENTRIES = 50
+local MAX_TABLE_DEPTH = 4
+
+local function describe(value: any, depth: number?, seen: { [any]: boolean }?): any
+	local level = depth or 0
+	local visited = seen or {}
+	local kind = typeof(value)
+
+	if kind == "function" or kind == "thread" then
+		return string.format("<%s>", kind)
+	end
+	if kind ~= "table" then
+		return Serialize.value(value)
+	end
+
+	local source = value :: { [any]: any }
+	-- Named separately from the depth cap, because they mean opposite things to
+	-- a reader. The depth cap says "there is more below this"; a cycle says
+	-- "this is the table you are already inside". Reporting the second as the
+	-- first printed `t.self.self.self` as three distinct nested tables, which
+	-- reads as real structure that does not exist.
+	if visited[source] then
+		return "<circular reference>"
+	end
+	if level >= MAX_TABLE_DEPTH then
+		return "<nested table>"
+	end
+	visited[source] = true
+
+	local count = 0
+	for _ in source do
+		count += 1
+	end
+
+	-- Arrays keep their shape so they read as lists on the other side; anything
+	-- with non-sequential keys becomes a map with stringified keys.
+	if count == #source then
+		local list: { any } = {}
+		for index, item in ipairs(source) do
+			if index > MAX_TABLE_ENTRIES then
+				table.insert(list, string.format("<%d more>", count - MAX_TABLE_ENTRIES))
+				break
+			end
+			table.insert(list, describe(item, level + 1, visited))
+		end
+		-- Cleared on the way out so the same table appearing twice side by side
+		-- still renders twice; only a table containing itself is a cycle.
+		visited[source] = nil
+		return list
+	end
+
+	local map: { [string]: any } = {}
+	local shown = 0
+	for key, item in source do
+		shown += 1
+		if shown > MAX_TABLE_ENTRIES then
+			map["..."] = string.format("<%d more>", count - MAX_TABLE_ENTRIES)
+			break
+		end
+		map[tostring(key)] = describe(item, level + 1, visited)
+	end
+	visited[source] = nil
+	return map
+end
+
+local Runtime = {}
+Runtime.describe = describe
+function Runtime.run(chunk: () -> ...any, timeout: number?): { [string]: any }
+	-- Captured rather than inferred: a chunk's prints are usually the point, and
+	-- reading them back from the log afterwards would also pick up whatever else
+	-- the place logged in the meantime.
+	local output: { { [string]: any } } = {}
+	local connection = LogService.MessageOut:Connect(function(message, messageType)
+		if #output < MAX_OUTPUT_LINES then
+			table.insert(output, {
+				message = message,
+				level = if messageType == Enum.MessageType.MessageError
+					then "error"
+					elseif messageType == Enum.MessageType.MessageWarning then "warning"
+					else "print",
+			})
+		end
+	end)
+
+	local started = os.clock()
+	local results: any = nil
+	if timeout then
+		local worker = task.spawn(function() results = table.pack(pcall(chunk :: any)) end)
+		local deadline = started + timeout
+		while results == nil and os.clock() < deadline do task.wait() end
+		if results == nil then
+			task.cancel(worker)
+			results = table.pack(false, "CLIENT_TIMEOUT: execution exceeded " .. tostring(timeout) .. "s")
+		end
+	else
+		results = table.pack(pcall(chunk :: () -> ...any))
+	end
+	local elapsed = os.clock() - started
+
+	--[[
+		MessageOut is deferred: `print` returns before the event fires, so
+		disconnecting straight after the chunk finished captured nothing at all.
+		A short settle picks the lines up.
+
+		It is bounded and stops as soon as the flow stops, rather than waiting a
+		fixed period, so a chunk that logged nothing costs almost no time and one
+		that logged plenty is not truncated.
+	]]
+	local settleDeadline = os.clock() + 0.5
+	local seen = #output
+	local quietFrames = 0
+	while os.clock() < settleDeadline and quietFrames < 3 do
+		task.wait()
+		if #output == seen then
+			quietFrames += 1
+		else
+			seen = #output
+			quietFrames = 0
+		end
+	end
+
+	connection:Disconnect()
+
+	if not results[1] then
+		return {
+			ok = false,
+			error = tostring(results[2]),
+			output = output,
+			milliseconds = math.floor(elapsed * 1000 + 0.5),
+		}
+	end
+
+	local returned: { any } = {}
+	for index = 2, math.min(results.n, MAX_RETURN_VALUES + 1) do
+		-- A nil return is written out rather than dropped. `table.insert` of nil
+		-- does nothing, so `return a, nil, b` came back as two values and every
+		-- one after the nil shifted into the wrong position.
+		local value = results[index]
+		table.insert(returned, if value == nil then "nil" else describe(value))
+	end
+
+	return {
+		ok = true,
+		returned = returned,
+		output = output,
+		milliseconds = math.floor(elapsed * 1000 + 0.5),
+	}
+end
+return Runtime

package/plugin/src/Phrase.luau

@@ -288,6 +288,9 @@ local DESCRIBERS: { [string]: Describer } = {
 		local name = leaf(params.path)
 		return if name ~= nil then "Clear breakpoints in " .. name else "Clear all breakpoints"
 	end,
+	["debug.remotes"] = function()
+		return "Observe playtest RemoteEvent traffic"
+	end,
 	["debug.snapshots"] = function()
 		return "Read what the breakpoints caught"
 	end,

package/plugin/src/RemoteTrace.luau

@@ -0,0 +1,143 @@
+--!strict
+-- Passive, bounded RemoteEvent observations shared by the server and client.
+local Paths = require(script.Parent.Paths)
+local Trace = {}
+local MAX_EVENTS = 1000 -- per direction; disconnect at the cap, never keep raw payloads
+local MAX_REMOTES = 128
+local MAX_ROWS = 20
+local MAX_VISITS = 10000
+
+local function brief(value: string, limit: number): string
+	local clipped = string.sub(value, 1, limit)
+	-- ASCII keeps invalid UTF-8, controls and JSON escaping from expanding output.
+	clipped = string.gsub(clipped, "[^ -~]", "?")
+	return clipped .. (if #value > limit then "..." else "")
+end
+
+local function pathOf(remote: Instance): string
+	local path = Paths.of(remote)
+	if #path <= 256 then return path end
+	-- Keep Unicode instance names valid at the byte boundary.
+	local ok, boundary = pcall(utf8.offset, path, 0, 257)
+	return string.sub(path, 1, if ok and boundary then boundary - 1 else 256) .. "..."
+end
+
+local function shape(value: any, depth: number): string
+	local kind = typeof(value)
+	if kind == "string" then return "string:" .. string.format("%q", brief(value, 32)) end
+	if kind == "number" or kind == "boolean" or kind == "nil" then return kind .. ":" .. tostring(value) end
+	if kind == "Instance" then return "Instance<" .. value.ClassName .. ">" end
+	if kind ~= "table" then return kind end
+	if depth >= 2 then return "table{...}" end
+	local parts = {}
+	local key, item = next(value)
+	for _ = 1, 4 do
+		if key == nil then break end
+		local label = if typeof(key) == "string" then brief(key, 20) else typeof(key)
+		table.insert(parts, label .. "=" .. shape(item, depth + 1))
+		key, item = next(value, key)
+	end
+	if key ~= nil then table.insert(parts, "...") end
+	return brief("table{" .. table.concat(parts, ",") .. "}", 160)
+end
+
+function Trace.arguments(...: any): string
+	local parts = {}
+	local count = select("#", ...)
+	for index = 1, math.min(count, 6) do
+		table.insert(parts, shape(select(index, ...), 0))
+	end
+	if count > 6 then table.insert(parts, "...") end
+	return brief("(" .. table.concat(parts, ", ") .. ")", 192)
+end
+
+-- Returns an idempotent stop function; its deadline also cleans up if the caller fails.
+function Trace.start(root: Instance, player: Player, client: boolean, seconds: number, excluded: Instance?): () -> { [string]: any }
+	local connections: { RBXScriptConnection } = {}
+	local watched: { [Instance]: boolean } = {}
+	local rows: { any } = {}
+	local byRemote: { [Instance]: any } = {}
+	local events, remotes, visits = 0, 0, 0
+	local omitted, scanLimited, eventLimited = false, false, false
+	local skipped = 0
+	local active = true
+	local started = os.clock()
+	local elapsed = 0
+	local timer: thread? = nil
+	local function stop(): { [string]: any }
+		if active then
+			active = false
+			elapsed = math.max(os.clock() - started, 0.001)
+			for _, connection in connections do connection:Disconnect() end
+			if timer then task.cancel(timer); timer = nil end
+			for _, row in rows do row.callsPerSecond = math.round(row.count / elapsed * 100) / 100 end
+		end
+		return { items = rows, events = events, seconds = elapsed, watched = remotes,
+			eventLimitReached = eventLimited, scanLimitReached = scanLimited, rowsOmitted = omitted, skipped = skipped }
+	end
+	local function record(remote: Instance, ...: any)
+		if not active or (remote ~= root and not remote:IsDescendantOf(root)) then return end
+		events += 1
+		local row = byRemote[remote]
+		if row == nil and #rows < MAX_ROWS then
+			row = { path = pathOf(remote), direction = if client then "server -> client" else "client -> server",
+				player = brief(player.Name, 64), count = 0, samples = {} }
+			byRemote[remote] = row
+			table.insert(rows, row)
+		end
+		if row then
+			row.count += 1
+			if #row.samples < 2 then
+				local sample = Trace.arguments(...)
+				if row.samples[1] ~= sample then table.insert(row.samples, sample) end
+			end
+		else omitted = true end
+		if events >= MAX_EVENTS then eventLimited = true; stop() end
+	end
+	local function attach(remote: Instance)
+		if not active or watched[remote] or not remote:IsA("RemoteEvent") then return end
+		if excluded and (remote == excluded or remote:IsDescendantOf(excluded)) then return end
+		-- Ignore all temporary bridge traffic, including overlapping MCP calls.
+		local ancestor: Instance? = remote.Parent
+		while ancestor and ancestor ~= game do
+			if ancestor:GetAttribute("MCPClientRelay") == true then return end
+			ancestor = ancestor.Parent
+		end
+		if remotes >= MAX_REMOTES then scanLimited = true; return end
+		watched[remote] = true
+		remotes += 1
+		if client then
+			table.insert(connections, (remote :: RemoteEvent).OnClientEvent:Connect(function(...) record(remote, ...) end))
+		else
+			table.insert(connections, (remote :: RemoteEvent).OnServerEvent:Connect(function(from, ...)
+				if from == player then record(remote, ...) end
+			end))
+		end
+	end
+	local ok, failure = pcall(function()
+		-- Subscribe first, then scan so remotes created during discovery are not missed.
+		table.insert(connections, root.DescendantAdded:Connect(function(object)
+			if visits >= MAX_VISITS then scanLimited = true; return end
+			visits += 1
+			local attached = pcall(attach, object)
+			if not attached then skipped += 1 end
+		end))
+		local pending = { root }
+		while #pending > 0 and visits < MAX_VISITS do
+			local object = table.remove(pending) :: Instance
+			visits += 1
+			attach(object)
+			local readable, children = pcall(object.GetChildren, object)
+			if not readable then skipped += 1; continue end
+			for _, child in children do
+				if visits + #pending >= MAX_VISITS then scanLimited = true; break end
+				table.insert(pending, child)
+			end
+		end
+		if #pending > 0 then scanLimited = true end
+		timer = task.delay(seconds, function() timer = nil; stop() end)
+	end)
+	if not ok then stop(); error(failure, 0) end
+	return stop
+end
+return Trace

package/plugin/src/ScriptEdit.luau

@@ -38,20 +38,6 @@ function ScriptEdit.read(target: LuaSourceContainer): string
 	return (target :: SourceContainer).Source
 end
 
---[[
-	Replaces source through the editor. `transform` receives the current text and
-	returns the replacement; returning the input unchanged is a no-op.
-
-	`transform` is allowed to raise a structured Dispatch failure -- a bad line
-	range is only discoverable once the authoritative source is in hand. Such a
-	failure is stashed rather than thrown from inside the callback: throwing
-	there would surface as an opaque engine error and lose the code and hint the
-	agent needs. The callback instead returns the text untouched, making that one
-	script a no-op, and the original failure is re-raised afterwards.
-
-	Raises SCRIPT_LOCKED when the write is refused, which normally means the
-	script is a package member or is owned by another Team Create session.
-]]
 --[[
 	Makes sure a write that reported success actually stuck.
 
@@ -97,6 +83,20 @@ local function confirm(target: LuaSourceContainer, produced: string?)
 	end
 end
 
+--[[
+	Replaces source through the editor. `transform` receives the current text and
+	returns the replacement; returning the input unchanged is a no-op.
+
+	`transform` is allowed to raise a structured Dispatch failure -- a bad line
+	range is only discoverable once the authoritative source is in hand. Such a
+	failure is stashed rather than thrown from inside the callback: throwing
+	there would surface as an opaque engine error and lose the code and hint the
+	agent needs. The callback instead returns the text untouched, making that one
+	script a no-op, and the original failure is re-raised afterwards.
+
+	Raises SCRIPT_LOCKED when the write is refused, which normally means the
+	script is a package member or is owned by another Team Create session.
+]]
 function ScriptEdit.write(target: LuaSourceContainer, transform: (string) -> string)
 	local pending: any = nil
 

package/plugin/src/Secret.luau

@@ -22,15 +22,6 @@
 
 local Secret = {}
 
---[[
-	Commands whose arguments are secret, and from which word onwards.
-
-	Keyed by "command subcommand" so `cloud key <secret>` is covered and `cloud
-	test` -- which carries nothing -- is not masked into uselessness. The user id
-	is masked too. It is not a credential and it is on a public profile URL, but
-	it names the account the key belongs to, and a screenshot showing both is
-	worth more to somebody than a screenshot showing either.
-]]
 --[[
 	Commands whose arguments are secret, and from which word onwards.
 

package/plugin/src/Transport.luau

@@ -150,6 +150,61 @@ local function parseFrames(message: string): { { [string]: any } }
 	return frames
 end
 
+--[[
+	Most bytes one stream may hold while waiting for the end of an event. Far
+	above any real command -- the bridge caps bodies at 32MB -- and only there so
+	a stream that never sends a blank line cannot grow this without limit.
+]]
+local MAX_PENDING = 48 * 1024 * 1024
+
+--[[
+	Joins stream deliveries back into whole events before parsing them.
+
+	`MessageReceived` hands over whatever the socket read, not one event: two
+	small frames can share a delivery, and one big frame is split over several.
+	Parsing each delivery alone dropped every split frame, because half a JSON
+	document does not decode -- a `script_create` carrying a 16KB script vanished
+	and the call timed out with nothing logged on either side, while a 32KB one
+	that happened to land in one read worked.
+
+	So everything up to the last blank line is parsed and the rest is held for
+	the next delivery. A tail that already decodes on its own is taken at once,
+	which keeps this correct if Studio ever delivers events without their
+	trailing blank line.
+]]
+local function frameReader(): (chunk: string) -> { { [string]: any } }
+	local pending = ""
+
+	return function(chunk: string): { { [string]: any } }
+		-- Normalised after joining, so a CRLF split across two reads still folds.
+		pending = (string.gsub(pending .. chunk, "\r\n", "\n"))
+
+		local frames: { { [string]: any } } = {}
+		local lastBreak = string.match(pending, "^.*()\n\n")
+		if lastBreak ~= nil then
+			frames = parseFrames(string.sub(pending, 1, lastBreak - 1))
+			pending = string.sub(pending, lastBreak + 2)
+		end
+
+		-- A partial JSON document never ends in "}", so the decode is only
+		-- attempted when it could succeed rather than on every read of a big one.
+		if pending ~= "" and string.match(pending, "}%s*$") then
+			local tail = parseFrames(pending)
+			if #tail > 0 then
+				for _, frame in tail do
+					table.insert(frames, frame)
+				end
+				pending = ""
+			end
+		end
+
+		if #pending > MAX_PENDING then
+			pending = ""
+		end
+		return frames
+	end
+end
+
 local function handleFrame(callbacks: Callbacks, frame: { [string]: any })
 	local id = frame.id
 	local op = frame.op
@@ -196,10 +251,12 @@ local function runStream(callbacks: Callbacks): boolean
 		end)
 	)
 
+	-- One per stream: a partial event must never be glued onto the next stream.
+	local readFrames = frameReader()
 	table.insert(
 		connections,
 		client.MessageReceived:Connect(function(message: string)
-			for _, frame in parseFrames(message) do
+			for _, frame in readFrames(message) do
 				handleFrame(callbacks, frame)
 			end
 		end)

package/plugin/src/Visuals.luau

@@ -624,14 +624,6 @@ function Visuals.celebrate()
 	runtime.waveHold = 0
 end
 
---[[
-	Re-places every bar and hands each to the active preset to draw.
-
-	Laid out right to left so the newest bar is always at the same edge and the
-	trace reads as scrolling rather than reshuffling. The horizontal position is
-	set here and the preset is expected to keep it -- everything else about the
-	bar is the preset's to decide.
-]]
 --[[
 	Where slot `number` sits, counting 1 at the right edge and rising leftwards.
 
@@ -657,6 +649,14 @@ end
 	it. Absent, every bar is drawn from its own recorded timing, which is what
 	restores the true trace the moment a wave ends.
 ]]
+--[[
+	Re-places every bar and hands each to the active preset to draw.
+
+	Laid out right to left so the newest bar is always at the same edge and the
+	trace reads as scrolling rather than reshuffling. The horizontal position is
+	set here and the preset is expected to keep it -- everything else about the
+	bar is the preset's to decide.
+]]
 local function relayout(modulate: ((number, number, number) -> (number, number))?)
 	local ctx = context()
 	local painter = Themes.active().paintSlot or defaultSlot

package/plugin/src/handlers/Anim.luau

@@ -130,22 +130,6 @@ local function flatten(node: Instance, prefix: string, into: { { [string]: any }
 	end
 end
 
---[[
-	Which rig an animation was made for, read off the joints it moves.
-
-	This matters more than it sounds. An R15 animation played on an R6 character
-	does nothing at all -- no error, no warning, no movement -- because the joint
-	names it addresses ("LeftUpperArm") do not exist on that rig ("Left Arm").
-	It is one of the quietest failures on the platform, and the asset id carries
-	no hint of which kind it is.
-
-	The two skeletons are told apart by naming rather than by counting. R6 uses
-	six limbs with spaces in their names, unchanged since 2007. R15 splits each
-	limb in two and writes them without spaces. Anything that matches neither is
-	a custom rig, and is reported as such rather than guessed at -- a wrong
-	confident answer here is worse than "unknown", because the whole point of
-	the field is to be trusted.
-]]
 --[[
 	Which joint hangs off which, for the two rigs Roblox ships.
 
@@ -207,6 +191,22 @@ local R15_PARTS = {
 	RightLowerArm = true,
 }
 
+--[[
+	Which rig an animation was made for, read off the joints it moves.
+
+	This matters more than it sounds. An R15 animation played on an R6 character
+	does nothing at all -- no error, no warning, no movement -- because the joint
+	names it addresses ("LeftUpperArm") do not exist on that rig ("Left Arm").
+	It is one of the quietest failures on the platform, and the asset id carries
+	no hint of which kind it is.
+
+	The two skeletons are told apart by naming rather than by counting. R6 uses
+	six limbs with spaces in their names, unchanged since 2007. R15 splits each
+	limb in two and writes them without spaces. Anything that matches neither is
+	a custom rig, and is reported as such rather than guessed at -- a wrong
+	confident answer here is worse than "unknown", because the whole point of
+	the field is to be trusted.
+]]
 local function rigOf(joints: { [string]: boolean }): (string, string?)
 	local r6, r15 = 0, 0
 	for joint in joints do
@@ -418,21 +418,6 @@ function Anim.read(params: { [string]: any }): { [string]: any }
 	}
 end
 
---[[
-	Builds a KeyframeSequence in memory and registers it for playback.
-
-	The registration is what makes this more than an instance tree: it returns a
-	content id that an Animation can use immediately, in this Studio, with no
-	upload and no moderation wait. That is the whole loop an agent needs to try
-	an idea -- build, set AnimationId, look -- and it is entirely reversible,
-	because nothing left the session.
-
-	Poses arrive flat, named by joint, and are nested under one root pose here.
-	Flat is what a caller can write and nesting is what the engine resolves, and
-	the rig's own hierarchy is not knowable from a list of joint names -- so a
-	single root is the honest structure: it animates the named joints and claims
-	nothing about how they connect.
-]]
 --[[
 	The joint tree to nest poses against.
 
@@ -477,6 +462,21 @@ local function parentMap(params: { [string]: any }, joints: { [string]: boolean
 	return R6_PARENT, "R6"
 end
 
+--[[
+	Builds a KeyframeSequence in memory and registers it for playback.
+
+	The registration is what makes this more than an instance tree: it returns a
+	content id that an Animation can use immediately, in this Studio, with no
+	upload and no moderation wait. That is the whole loop an agent needs to try
+	an idea -- build, set AnimationId, look -- and it is entirely reversible,
+	because nothing left the session.
+
+	Poses arrive flat, named by joint, and are nested under one root pose here.
+	Flat is what a caller can write and nesting is what the engine resolves, and
+	the rig's own hierarchy is not knowable from a list of joint names -- so a
+	single root is the honest structure: it animates the named joints and claims
+	nothing about how they connect.
+]]
 function Anim.build(params: { [string]: any }): { [string]: any }
 	local frames = params.keyframes
 	if typeof(frames) ~= "table" or #(frames :: { any }) == 0 then
@@ -636,25 +636,6 @@ function Anim.build(params: { [string]: any }): { [string]: any }
 	}
 end
 
---[[
-	Plays an animation on a real rig, in edit mode, so it can be looked at.
-
-	`read` says what an animation contains and `build` makes one; neither answers
-	"does it look right", which for a piece of motion is most of the question.
-	Measured: an `Animator` loads and plays a track in an ordinary edit session
-	-- `Length` comes back populated and `IsPlaying` is true -- so the rig in the
-	place can be posed without pressing Play.
-
-	The frame is the point. Playing an animation and returning immediately shows
-	whatever pose the rig happened to be in, so this seeks to a chosen moment and
-	holds it there: play, jump to `at`, pause. Then `screenshot` sees that exact
-	pose, and asking for three different moments gives three comparable frames.
-
-	Deliberately leaves the rig posed rather than restoring it. The whole purpose
-	is to leave something on screen to photograph, and a tool that tidied up
-	before returning would always photograph the idle pose. `op="stop"` puts it
-	back.
-]]
 --[[
 	Puts a rig back the way it was before anything was played on it.
 
@@ -722,6 +703,25 @@ local function restPose(model: Instance, animator: Animator)
 	animator:StepAnimations(1 / 60)
 end
 
+--[[
+	Plays an animation on a real rig, in edit mode, so it can be looked at.
+
+	`read` says what an animation contains and `build` makes one; neither answers
+	"does it look right", which for a piece of motion is most of the question.
+	Measured: an `Animator` loads and plays a track in an ordinary edit session
+	-- `Length` comes back populated and `IsPlaying` is true -- so the rig in the
+	place can be posed without pressing Play.
+
+	The frame is the point. Playing an animation and returning immediately shows
+	whatever pose the rig happened to be in, so this seeks to a chosen moment and
+	holds it there: play, jump to `at`, pause. Then `screenshot` sees that exact
+	pose, and asking for three different moments gives three comparable frames.
+
+	Deliberately leaves the rig posed rather than restoring it. The whole purpose
+	is to leave something on screen to photograph, and a tool that tidied up
+	before returning would always photograph the idle pose. `op="stop"` puts it
+	back.
+]]
 function Anim.preview(params: { [string]: any }): { [string]: any }
 	local rigPath = params.rig
 	if typeof(rigPath) ~= "string" or rigPath == "" then

package/plugin/src/handlers/Character.luau

@@ -178,14 +178,6 @@ local function takeControl(model: Model): boolean
 	return ok
 end
 
---[[
-	Walks to a point, following a computed path around obstacles.
-
-	Reports where it ended up rather than only whether the call returned, because
-	`MoveTo` succeeds at being asked and says nothing about arriving. A route
-	blocked by a wall the agent did not know about looks identical to a
-	successful walk unless the final distance is measured.
-]]
 --[[
 	Agent settings, shared by the route check and the walk.
 
@@ -336,6 +328,14 @@ function Character.path(params: { [string]: any }): { [string]: any }
 	}
 end
 
+--[[
+	Walks to a point, following a computed path around obstacles.
+
+	Reports where it ended up rather than only whether the call returned, because
+	`MoveTo` succeeds at being asked and says nothing about arriving. A route
+	blocked by a wall the agent did not know about looks identical to a
+	successful walk unless the final distance is measured.
+]]
 function Character.moveTo(params: { [string]: any }): { [string]: any }
 	local model, humanoid = humanoidOf(params)