@el4cteo/rbx-studio-mcp 0.6.0 → 0.6.5

package/plugin/src/Emulation.luau

@@ -8,6 +8,12 @@
 	shape. Emulation persists until it is switched off, which is exactly the kind
 	of state that goes wrong quietly.
 
+	The network conditions Studio is shaping traffic with live here too. They are
+	the same kind of state for the same reason: set once, invisible on screen,
+	and they stay until something turns them off. A place that "feels laggy" with
+	a forgotten 400ms delay on it is exactly the bug this file exists to stop
+	people chasing.
+
 	`StudioDeviceSimulatorService` is undocumented on its return shapes, so what
 	is here was read off a live session. Two things are worth knowing:
 
@@ -21,8 +27,172 @@
 
 local StudioDeviceSimulatorService = game:GetService("StudioDeviceSimulatorService")
 
+--[[
+	`NetworkSettings` is not a `game` service; it hangs off `settings()`.
+
+	`game:GetService("NetworkSettings")` throws outright, which is worth writing
+	down because every other service in this codebase is reached that way. The
+	traffic-shaping properties on it -- delay, jitter, loss, in each direction --
+	are PluginSecurity, so they are readable and writable here and nowhere near a
+	running game.
+
+	Guarded: it is reached through a `pcall` at every use rather than captured
+	once, because a Studio old enough to lack the properties should cost the
+	network feature, not the whole `device` tool.
+]]
+local function networkSettings(): any?
+	local ok, service = pcall(function()
+		return (settings() :: any):GetService("NetworkSettings")
+	end)
+	if ok and service ~= nil then
+		return service
+	end
+	return nil
+end
+
 local Emulation = {}
 
+Emulation.networkSettings = networkSettings
+
+--[[
+	The six traffic-shaping properties, in the order a person reads them.
+
+	Inbound is what the client receives and is what a laggy connection feels
+	like; outbound is what it sends, which is what makes a player's own actions
+	arrive late to everyone else. Both are shaped separately by Studio, so both
+	are carried separately here.
+]]
+--[[
+	The memory ceiling this session set, if any.
+
+	Session-local by necessity: see the note in `Emulation.network`. A cap set by
+	Studio's own toolbar before the plugin loaded is invisible to this, which is
+	the honest failure -- reporting a cap that is not there was the alternative,
+	and it was worse.
+]]
+local memoryCap: number? = nil
+
+local NETWORK_FIELDS = {
+	{ key = "inLatency", property = "InboundNetworkMinDelayMs", scale = 1 },
+	{ key = "inJitter", property = "InboundNetworkJitterMs", scale = 1 },
+	{ key = "inLoss", property = "InboundNetworkLossPercent", scale = 100 },
+	{ key = "outLatency", property = "OutboundNetworkMinDelayMs", scale = 1 },
+	{ key = "outJitter", property = "OutboundNetworkJitterMs", scale = 1 },
+	{ key = "outLoss", property = "OutboundNetworkLossPercent", scale = 100 },
+}
+
+--[[
+	What the engine will actually accept, measured rather than assumed.
+
+	None of this is documented and all three of them bite. Writes outside these
+	ranges SUCCEED and are silently clamped, so a preset asking for 2% loss was
+	reporting 0.5 back and the only way to notice was to read the value again --
+	which is how this was found.
+
+	* Loss is a FRACTION, despite `LossPercent` in the name: it tops out at 0.5,
+	  and 0.5 is half the packets, not half a percent. Everything above this
+	  layer speaks in percent because that is what a person means by "2% loss",
+	  so the conversion happens at the edges -- `scale` above on the way out, and
+	  `LOSS_LIMIT` on the way in.
+	* Delay and jitter both stop at 1000ms. A second of latency is already past
+	  anything a real connection does, so this costs nothing but honesty.
+]]
+local LOSS_LIMIT = 0.5
+local DELAY_LIMIT = 1000
+
+Emulation.LOSS_LIMIT_PERCENT = LOSS_LIMIT * 100
+Emulation.DELAY_LIMIT = DELAY_LIMIT
+
+--[[
+	What Studio is currently doing to network traffic.
+
+	`shaping` is the field callers should branch on: every value being zero is
+	the normal, un-emulated state, and reporting six zeroes without saying so
+	makes "is anything on" a question the caller has to work out for itself.
+]]
+function Emulation.network(): { [string]: any }
+	local service = networkSettings()
+	if service == nil then
+		return { available = false, shaping = false }
+	end
+
+	local state: { [string]: any } = { available = true }
+	local shaping = false
+	for _, field in NETWORK_FIELDS do
+		local ok, value = pcall(function()
+			return (service :: any)[field.property]
+		end)
+		local number = if ok then tonumber(value) or 0 else 0
+		--[[
+			Scaled into the caller's units, then rounded to two places. These are
+			32-bit floats: 2% loss is stored as 0.02 and reads back as
+			0.019999999552965164, and reporting that instead of 2 makes a
+			perfectly applied setting look like a failed one.
+		]]
+		number *= field.scale
+		state[field.key] = math.round(number * 100) / 100
+		if number > 0 then
+			shaping = true
+		end
+	end
+
+	--[[
+		Reported, but deliberately not counted as shaping.
+
+		`EmulatedTotalMemoryInMB` does not read back 0 when nothing is emulated:
+		it answers with the machine's real memory -- measured, 16159 on the
+		session this was written against. Treating "greater than zero" as a cap
+		therefore declared every untouched Studio to be emulating a low-memory
+		device, and `studio_status` told the agent traffic was being degraded on
+		a session where nothing had ever been set.
+
+		There is no read that distinguishes a cap from the true figure, so the
+		cap is remembered instead, by the one thing that sets it.
+	]]
+	local okMemory, memory = pcall(function()
+		return (service :: any).EmulatedTotalMemoryInMB
+	end)
+	if okMemory then
+		state.memoryMB = math.floor(tonumber(memory) or 0)
+	end
+
+	if memoryCap ~= nil and memoryCap > 0 then
+		state.memoryCapMB = memoryCap
+		shaping = true
+	end
+
+	state.shaping = shaping
+	return state
+end
+
+--[[
+	Records the memory ceiling this session asked for.
+
+	Held here rather than in the handler because `network` writes it and
+	`Emulation.network` reports it, and a value those two disagree about is worse
+	than no value at all. nil or 0 means no cap.
+]]
+function Emulation.setMemoryCap(megabytes: number?)
+	memoryCap = if megabytes ~= nil and megabytes > 0 then megabytes else nil
+end
+
+--[[
+	The short form for `studio_status`, or nil when traffic is untouched.
+
+	Separate from the device summary rather than folded into it: a session can be
+	shaping traffic without emulating a device, and the device summary returns
+	nil in exactly that case.
+]]
+function Emulation.networkSummary(): { [string]: any }?
+	local state = Emulation.network()
+	if state.shaping ~= true then
+		return nil
+	end
+	state.note = 'Studio is degrading network traffic on purpose. `device op="network" '
+		.. 'preset="clear"` restores it.'
+	return state
+end
+
 --[[
 	The resolution as it actually appears, rather than as the panel is specified.
 
@@ -128,6 +298,8 @@ function Emulation.state(): { [string]: any }
 		state.scalingMode = tostring(scaling)
 	end
 
+	state.network = Emulation.network()
+
 	return state
 end
 

package/plugin/src/Phrase.luau

@@ -272,9 +272,6 @@ local DESCRIBERS: { [string]: Describer } = {
 		return "Search the place"
 	end,
 
-	["script.debugSet"] = function()
-		return "Set breakpoints"
-	end,
 	["debug.set"] = function(params)
 		local breakpoints = params.breakpoints
 		local total = count(breakpoints)
@@ -481,19 +478,6 @@ local DESCRIBERS: { [string]: Describer } = {
 	["studio.ping"] = function()
 		return "Ping"
 	end,
-	["studio.transport"] = function(params)
-		local mode = params.mode
-		return if typeof(mode) == "string" and mode ~= ""
-			then string.format("Switch to %s transport", mode)
-			else "Check the transport"
-	end,
-
-	--[[
-		The one a person actually watches: a live playtest is the point where
-		"what is the AI doing" stops being abstract, and a console line reading
-		"Input send" says nothing a bystander could act on. One step names the
-		key or point; several collapse to a count, same as every other batch op.
-	]]
 	["input.send"] = function(params)
 		local steps = params.steps
 		local total = count(steps)
@@ -535,6 +519,158 @@ local DESCRIBERS: { [string]: Describer } = {
 			else "Measure the scene"
 	end,
 
+	--[[
+		Everything below was added after the first pass over this table, and each
+		one spent time showing as the fallback -- "Anim preview", "Data set",
+		"Terrain fill". That form is honest but says nothing about the subject,
+		which is the whole point of this module: the panel is watched to see WHAT
+		an agent is touching, and 26 of 72 operations were declining to say.
+	]]
+	["anim.read"] = function(params)
+		local name = leaf(params.assetId)
+		return if name ~= nil then "Read the animation " .. name else "Read an animation"
+	end,
+	["anim.build"] = function(params)
+		local frames = count(params.keyframes)
+		return string.format("Build an animation from %s", plural(frames, "keyframe"))
+	end,
+	["anim.preview"] = function(params)
+		local rig = leaf(params.rig) or "a rig"
+		if params.op == "stop" then
+			return "Clear the pose on " .. rig
+		end
+		local at = tonumber(params.at)
+		return if at ~= nil
+			then string.format("Pose %s at %.2fs", rig, at)
+			else "Pose " .. rig
+	end,
+
+	["data.list"] = function(params)
+		local store = params.store
+		if typeof(store) == "string" and store ~= "" then
+			return string.format("List the keys in %s", store)
+		end
+		return "List the data stores"
+	end,
+	["data.get"] = function(params)
+		return string.format("Read %s from %s", tostring(params.key), tostring(params.store))
+	end,
+	["data.versions"] = function(params)
+		return string.format("Read the history of %s", tostring(params.key))
+	end,
+	["data.set"] = function(params)
+		return string.format("SAVE over %s in %s", tostring(params.key), tostring(params.store))
+	end,
+	["data.remove"] = function(params)
+		return string.format("DELETE %s from %s", tostring(params.key), tostring(params.store))
+	end,
+
+	["discover.tags"] = function(params)
+		local where = leaf(params.path)
+		return if where ~= nil then "List the tags used in " .. where else "List every tag in use"
+	end,
+
+	["viewport.ui"] = function()
+		return "Check the interface for layout faults"
+	end,
+	["viewport.textbounds"] = function(params)
+		local name = leaf(params.path)
+		return if name ~= nil then "Measure the text in " .. name else "Measure some text"
+	end,
+
+	["perf.audit"] = function()
+		return "Look for references that point at nothing"
+	end,
+
+	["assets.audio"] = function(params)
+		local keyword = params.keyword
+		return if typeof(keyword) == "string" and keyword ~= ""
+			then string.format('Search audio for "%s"', keyword)
+			else "Search the audio library"
+	end,
+	["assets.peek"] = function(params)
+		return string.format("Look inside asset %s without inserting it", tostring(params.assetId))
+	end,
+	["assets.bake"] = function(params)
+		return "Bake " .. subjectOf(params.paths, "instance")
+	end,
+
+	["character.path"] = function(params)
+		local target = leaf(params.toPath)
+		return if target ~= nil then "Check the route to " .. target else "Check a route"
+	end,
+
+	["device.network"] = function(params)
+		local preset = params.preset
+		return if typeof(preset) == "string" and preset ~= ""
+			then string.format("Simulate a %s connection", preset)
+			else "Shape the network connection"
+	end,
+
+	["geometry.sweep"] = function(params)
+		local name = leaf(params.path)
+		return if name ~= nil then "Sweep the path of " .. name else "Sweep a motion volume"
+	end,
+	["geometry.mesh"] = function(params)
+		return "Read the geometry of " .. subjectOf(params.paths, "mesh")
+	end,
+
+	["generate.model"] = function(params)
+		local prompt = params.prompt
+		return if typeof(prompt) == "string" and prompt ~= ""
+			then string.format('Generate a model: "%s"', prompt)
+			else "Generate a model"
+	end,
+	["generate.segment"] = function(params)
+		local name = leaf(params.path)
+		return if name ~= nil then "Cut " .. name .. " into named parts" else "Segment a mesh"
+	end,
+
+	["script.open"] = function(params)
+		local name = leaf(params.path)
+		return if name ~= nil then "Open " .. name .. " in the editor" else "Open a script"
+	end,
+
+	["terrain.fill"] = function(params)
+		--[[
+			The material lives inside the shapes, not beside them.
+
+			Written first against a top-level `material`, which this op has never
+			taken, so it always fell through to the bare "Fill terrain" -- seen in
+			the panel for a call that laid 50 voxels of sand. The parameters a
+			describer reads have to be the ones the handler reads.
+		]]
+		local shapes = params.shapes
+		if typeof(shapes) == "table" and #(shapes :: { any }) > 0 then
+			local list = shapes :: { any }
+			local first = list[1]
+			local material = if typeof(first) == "table" then first.material else nil
+			local named = typeof(material) == "string" and material ~= ""
+			if #list == 1 then
+				return if named
+					then string.format("Fill terrain with %s", material)
+					else "Fill terrain"
+			end
+			return if named
+				then string.format("Fill %s, starting with %s", plural(#list, "terrain shape"), material)
+				else string.format("Fill %s", plural(#list, "terrain shape"))
+		end
+		return "Fill terrain"
+	end,
+	["terrain.clear"] = function()
+		return "CLEAR terrain"
+	end,
+	["terrain.replace"] = function(params)
+		return string.format(
+			"Replace %s terrain with %s",
+			tostring(params.from or "one material"),
+			tostring(params.to or "another")
+		)
+	end,
+	["terrain.stats"] = function()
+		return "Measure the terrain"
+	end,
+
 	["device.list"] = function()
 		return "List devices"
 	end,
@@ -576,6 +712,18 @@ local KINDS: { [string]: string } = {
 	perf = "debug",
 	api = "read",
 	device = "read",
+	--[[
+		Absent groups defaulted to "read", which is the wrong way round for a
+		default: a missing entry made `terrain.clear` and `data.set` -- one of
+		which erases the map and the other of which overwrites a player's save
+		with no undo -- show in the panel with the same weight as an inspect.
+		A kind is a warning, so the ones that change things are named here
+		explicitly.
+	]]
+	terrain = "write",
+	generate = "write",
+	anim = "write",
+	data = "write",
 }
 
 function Phrase.kindOf(op: string): string

package/plugin/src/Png.luau

@@ -207,10 +207,14 @@ end
 --[[
 	Nearest-neighbour downscale, RGBA in and RGB out.
 
-	Nearest rather than averaged on purpose. A screenshot is read for what is in
-	it -- is the part there, is the GUI covering it, is the material wrong -- and
-	averaging softens exactly the thin edges and one-pixel text that carry that.
-	It is also a single read per output pixel instead of four.
+	The fallback path. `Capture` scales on the engine side now -- see
+	`Capture.resample` -- because this loop is six buffer calls per output pixel
+	in Luau and nearest-neighbour is the wrong filter for the job: at the usual
+	2x reduction it does not "keep thin edges", it deletes every other row and
+	column outright, which is exactly where one-pixel GUI text lives. This stays
+	for the cases the engine path cannot take: a Studio without
+	`CreateEditableImage`, or a target wider than the 1024 an EditableImage can
+	be created at.
 ]]
 function Png.downscaleToRgb(rgba: buffer, width: number, height: number, targetWidth: number): (buffer, number, number)
 	local scale = math.min(1, targetWidth / width)