@el4cteo/rbx-studio-mcp 0.8.0 → 0.8.2

package/plugin/src/Emulation.luau

@@ -75,34 +75,62 @@ 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 = "inLoss", property = "InboundNetworkLossPercent", scale = 1 },
 	{ key = "outLatency", property = "OutboundNetworkMinDelayMs", scale = 1 },
 	{ key = "outJitter", property = "OutboundNetworkJitterMs", scale = 1 },
-	{ key = "outLoss", property = "OutboundNetworkLossPercent", scale = 100 },
+	{ key = "outLoss", property = "OutboundNetworkLossPercent", scale = 1 },
 }
 
 --[[
 	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.
+	Writes outside these ranges SUCCEED and are silently clamped, so the only
+	way to notice is to read the value again.
 
-	* 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.
+	* Loss is a PERCENT, as the name says, and Roblox caps it at 0.5% "to
+	  prevent interfering with standard congestion control" (the Network
+	  Simulation announcement; its own "Poor" profile is 0.5%). This file once
+	  read the 0.5 ceiling as a fraction -- half of all packets -- and divided
+	  every request by 100, so "0.5% loss" applied 0.005% while the reply,
+	  scaled back up, still said 0.5.
 	* 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 LOSS_LIMIT_PERCENT = 0.5
 local DELAY_LIMIT = 1000
 
-Emulation.LOSS_LIMIT_PERCENT = LOSS_LIMIT * 100
+Emulation.LOSS_LIMIT_PERCENT = LOSS_LIMIT_PERCENT
 Emulation.DELAY_LIMIT = DELAY_LIMIT
 
+--[[
+	The machine's real memory, read before this plugin could have capped it.
+
+	`EmulatedTotalMemoryInMB` defaults to the physical memory and 0 is a real
+	value, not "off": clearing a cap by writing 0 left Studio emulating a
+	device with no memory at all. Removing a cap therefore means writing this
+	back. Read once at load, which is before anything here writes it.
+]]
+local machineMemory: number? = nil
+do
+	local service = networkSettings()
+	if service ~= nil then
+		local ok, value = pcall(function()
+			return service.EmulatedTotalMemoryInMB
+		end)
+		if ok and tonumber(value) and (tonumber(value) :: number) > 0 then
+			machineMemory = tonumber(value)
+		end
+	end
+end
+
+function Emulation.machineMemory(): number?
+	return machineMemory
+end
+
+function Emulation.memoryCap(): number?
+	return memoryCap
+end
+
 --[[
 	What Studio is currently doing to network traffic.
 
@@ -125,9 +153,9 @@ function Emulation.network(): { [string]: any }
 		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.
+			32-bit floats: 0.3% loss reads back as 0.30000001192092896, and
+			reporting that instead of 0.3 makes a perfectly applied setting look
+			like a failed one.
 		]]
 		number *= field.scale
 		state[field.key] = math.round(number * 100) / 100

package/plugin/src/ExecRuntime.luau

@@ -1,161 +1,168 @@
---!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
+--!strict
+-- Shared bounded execution results in the VM that calls run.
+local LogService = game:GetService("LogService")
+local LogBuffer = require(script.Parent.LogBuffer)
+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, context)
+		if #output < MAX_OUTPUT_LINES then
+			-- A structured log's context rides on the line, as it does in `console`.
+			local encoded = LogBuffer.encodeContext(context)
+			if encoded then
+				message ..= "  " .. encoded
+			end
+			table.insert(output, {
+				message = message,
+				level = if messageType == Enum.MessageType.MessageError
+					then "error"
+					elseif messageType == Enum.MessageType.MessageWarning then "warning"
+					elseif messageType == Enum.MessageType.MessageInfo then "info"
+					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/LogBuffer.luau

@@ -35,6 +35,10 @@ local SLACK = 500
 -- handful of entries is a mismatch rather than a late delivery.
 local CORRELATION_WINDOW = 20
 
+-- A structured log's context, as JSON, is cut here: Roblox's own server logs
+-- drop context past 1KiB, so nothing longer is worth carrying.
+local MAX_CONTEXT = 1000
+
 export type Entry = {
 	sequence: number?,
 	level: string,
@@ -43,6 +47,8 @@ export type Entry = {
 	-- Present on errors once the matching stack trace has been correlated.
 	stack: string?,
 	source: string?,
+	-- The table a structured log (`LogService:Info(msg, context)`) carried, as JSON.
+	context: string?,
 }
 
 local LEVELS: { [number]: string } = {
@@ -153,6 +159,7 @@ function LogBuffer.pushClient(player: Player, payload: any)
 		timestamp = if typeof(payload.timestamp) == "number" and payload.timestamp >= 0 and payload.timestamp < 100000000000 then payload.timestamp else os.time(),
 		stack = if typeof(payload.stack) == "string" then string.sub(payload.stack, 1, 4000) else nil,
 		source = if typeof(payload.source) == "string" then string.sub(payload.source, 1, 500) else nil,
+		context = if typeof(payload.context) == "string" then string.sub(payload.context, 1, MAX_CONTEXT) else nil,
 	}
 	local waiting = buffer.orphan[entry.message]
 	if level == "error" and waiting then
@@ -183,12 +190,60 @@ function LogBuffer.stream(player: Player?): ({ Entry }, number, string, number,
 	return table.move(entries, 1, #entries, 1, {}), dropped, studioToken, nextSequence, LogBuffer.recordingSeconds()
 end
 
-local function push(message: string, messageType: Enum.MessageType, timestamp: number?)
+--[[
+	The context table of a structured log, as compact JSON.
+
+	`LogService:Info("{player} leveled up", { player = "Bob" })` prints only the
+	filled-in message; the table is the part that says which player and what
+	state, and MessageOut hands it over as a third argument. Plain prints pass an
+	empty table, which is dropped. Capped at 1000 characters -- the ceiling
+	Roblox's own server logs apply -- and a table JSON cannot hold (a Vector3, an
+	Instance) falls back to text rather than being lost.
+]]
+-- JSONEncode writes a Vector3 or an Instance as `null` without complaint, so
+-- anything JSON has no shape for is turned into its text first.
+local function plain(value: any, depth: number): any
+	local kind = typeof(value)
+	if kind == "string" or kind == "number" or kind == "boolean" then
+		return value
+	elseif kind == "table" then
+		if depth >= 4 then
+			return "<table>"
+		end
+		local copy = {}
+		for key, item in value do
+			copy[if typeof(key) == "number" then key else tostring(key)] = plain(item, depth + 1)
+		end
+		return copy
+	elseif kind == "Instance" then
+		local ok, full = pcall(function()
+			return value:GetFullName()
+		end)
+		return if ok then full else value.Name
+	end
+	return tostring(value)
+end
+
+function LogBuffer.encodeContext(context: any): string?
+	if typeof(context) ~= "table" or next(context) == nil then
+		return nil
+	end
+	local ok, encoded = pcall(function()
+		return HttpService:JSONEncode(plain(context, 0))
+	end)
+	if not ok then
+		return nil
+	end
+	return string.sub(encoded :: string, 1, MAX_CONTEXT)
+end
+
+local function push(message: string, messageType: Enum.MessageType, timestamp: number?, context: any?)
 	local level = LEVELS[messageType.Value] or "print"
 	local entry: Entry = {
 		level = level,
 		message = message,
 		timestamp = timestamp or os.time(),
+		context = LogBuffer.encodeContext(context),
 	}
 
 	-- Claim a trace that beat its own error line here.
@@ -261,7 +316,7 @@ function LogBuffer.start()
 		end
 	end
 
-	LogService.MessageOut:Connect(function(message: string, messageType: Enum.MessageType)
+	LogService.MessageOut:Connect(function(message: string, messageType: Enum.MessageType, context: any?)
 		local buffered = collecting
 
 		if buffered then
@@ -305,7 +360,7 @@ function LogBuffer.start()
 			return
 		end
 
-		push(message, messageType)
+		push(message, messageType, nil, context)
 	end)
 
 	--[[

package/plugin/src/Phrase.luau

@@ -341,6 +341,8 @@ local DESCRIBERS: { [string]: Describer } = {
 			return "Run the place"
 		elseif op == "multiplayer" then
 			return string.format("Start a %s test", plural(tonumber(params.players) or 2, "player"))
+		elseif op == "addPlayers" then
+			return string.format("Add %s to the test", plural(tonumber(params.players) or 1, "player"))
 		elseif op == "stop" then
 			return "Stop the playtest"
 		elseif op == "endTest" then

package/plugin/src/handlers/Assets.luau

@@ -17,6 +17,7 @@ local InsertService = game:GetService("InsertService")
 
 local Dispatch = require(script.Parent.Parent.Dispatch)
 local Paths = require(script.Parent.Parent.Paths)
+local Serialize = require(script.Parent.Parent.Serialize)
 local Undo = require(script.Parent.Parent.Undo)
 
 local Assets = {}
@@ -53,6 +54,17 @@ function Assets.insert(params: { [string]: any }): { [string]: any }
 		then Paths.resolve(params.parent)
 		else workspace
 
+	-- Parsed before anything loads. A position that did not parse used to be
+	-- skipped in silence, and the model landed wherever it was saved.
+	local position: Vector3? = nil
+	if typeof(params.position) == "string" and params.position ~= "" then
+		local ok, value, why = Serialize.parse(params.position, "Vector3")
+		if not ok then
+			Dispatch.fail("BAD_PARAMS", string.format("`position` is not a Vector3: %s", tostring(why)), 'Write it as "x, y, z".')
+		end
+		position = value :: Vector3
+	end
+
 	--[[
 		`game:GetObjects`, not `InsertService:LoadAsset`.
 
@@ -135,10 +147,8 @@ function Assets.insert(params: { [string]: any }): { [string]: any }
 		-- nothing silently is worse than saying so.
 		local remaining: { Instance } = {}
 		for _, child in children do
-			if child.Parent ~= nil or child:IsDescendantOf(game) or child.Name ~= "" then
-				if not child:IsA("LuaSourceContainer") then
-					table.insert(remaining, child)
-				end
+			if not child:IsA("LuaSourceContainer") then
+				table.insert(remaining, child)
 			end
 		end
 		children = remaining
@@ -160,20 +170,19 @@ function Assets.insert(params: { [string]: any }): { [string]: any }
 			table.insert(inserted, Paths.of(child))
 		end
 
-		-- Position after parenting, so PrimaryPart and pivot are settled.
-		if typeof(params.position) == "string" and params.position ~= "" then
-			local x, y, z = string.match(params.position, "^%s*(-?[%d%.]+)%s*,%s*(-?[%d%.]+)%s*,%s*(-?[%d%.]+)%s*$")
-			if x then
-				local target = CFrame.new(tonumber(x) :: number, tonumber(y) :: number, tonumber(z) :: number)
-				for _, child in children do
-					pcall(function()
-						if child:IsA("Model") then
-							(child :: Model):PivotTo(target)
-						elseif child:IsA("BasePart") then
-							(child :: BasePart).CFrame = target
-						end
-					end)
-				end
+		-- Position after parenting, so PrimaryPart and pivot are settled. Only
+		-- the position moves: the asset keeps the rotation it was saved with.
+		if position then
+			for _, child in children do
+				pcall(function()
+					if child:IsA("Model") then
+						local model = child :: Model
+						model:PivotTo(model:GetPivot().Rotation + position)
+					elseif child:IsA("BasePart") then
+						local part = child :: BasePart
+						part.CFrame = part.CFrame.Rotation + position
+					end
+				end)
 			end
 		end
 	end)