@el4cteo/rbx-studio-mcp 0.3.6 → 0.3.8

package/plugin/src/History.luau

@@ -0,0 +1,187 @@
+--!strict
+--[[
+	The console log, carried across the boundaries that used to erase it.
+
+	Pressing Play does not pause this plugin, it loads a second and a third copy
+	of it into the playtest's DataModels, each with its own empty console. Studio
+	then shows you the play view's panel, so the session you were watching
+	appears to have been wiped; stopping the test shows the editor's again, and
+	everything that happened during the test is missing from it instead. Nothing
+	crashed and nothing was lost -- the log was simply written in a window that is
+	no longer the one on screen.
+
+	Two halves fix that, and they are deliberately different mechanisms because
+	the two directions have different problems.
+
+	Forwards (editor -> playtest) is a cold start: the playtest's copies begin
+	with nothing and need what was already on screen. That is persistence, and it
+	is what this file does -- the edit session writes its rows to plugin
+	settings, and every copy reads them once at load.
+
+	Backwards (playtest -> editor) is not persistence at all. The editor session
+	is still running the whole time; it just is not the one being asked to do the
+	work. So there is nothing to restore, only something to be told, and it is
+	told over the bridge -- see `announceToPeers` in the server's rpc.ts.
+
+	Only the EDIT session writes. It is the one that outlives every playtest and
+	receives the peer announcements, so its log is the superset; letting the
+	playtest copies write as well would store the same rows twice and replay both
+	on the next load.
+]]
+
+local History = {}
+
+local SETTING = "consoleHistory"
+
+--[[
+	Rows kept, well under the console's own 300.
+
+	This is a settings file, rewritten in full on every save, and the value of an
+	old row falls off quickly -- what you want back is the screenful you were
+	looking at when the playtest started, not yesterday afternoon.
+]]
+local MAX_ROWS = 150
+
+--[[
+	Seconds between saves.
+
+	A burst of commands writes several rows a second and every one of them would
+	otherwise be a rewrite of the whole file. The loss window is the same two
+	seconds, and the only way to lose that window is to close Studio inside it --
+	which `flush` covers anyway.
+]]
+local SAVE_EVERY = 2
+
+export type Row = {
+	level: string,
+	message: string,
+	detail: string?,
+	stamp: string,
+}
+
+local store: Plugin? = nil
+local read: (() -> { Row })? = nil
+local dirty = false
+local running = false
+
+--[[
+	Which place this log belongs to.
+
+	One settings file is shared by every Studio window on the machine, so without
+	a key a second place's session would read back the first's history and show
+	it as its own. An unsaved place has no id, so its name stands in -- imperfect
+	between two unsaved places, and better than merging them.
+]]
+local function placeKey(): string
+	if game.PlaceId ~= 0 then
+		return tostring(game.PlaceId)
+	end
+	return "local:" .. game.Name
+end
+
+--[[
+	Rows survive a round trip through JSON, so nothing that comes back is
+	trusted: a settings file is a file on disk, and a field that is missing or
+	the wrong type must skip the row rather than reach the renderer.
+]]
+local function sane(value: any): Row?
+	if typeof(value) ~= "table" then
+		return nil
+	end
+	local row = value :: { [string]: any }
+	if typeof(row.level) ~= "string" or typeof(row.message) ~= "string" then
+		return nil
+	end
+	if typeof(row.stamp) ~= "string" then
+		return nil
+	end
+	return {
+		level = row.level,
+		message = row.message,
+		detail = if typeof(row.detail) == "string" then row.detail else nil,
+		stamp = row.stamp,
+	}
+end
+
+--[[
+	`snapshot` is a function rather than rows, because saving is throttled: what
+	must be written is whatever the console holds when the timer fires, not what
+	it held when the row that triggered it was logged.
+]]
+function History.attach(pluginObject: Plugin, snapshot: () -> { Row })
+	store = pluginObject
+	read = snapshot
+end
+
+function History.restore(): { Row }
+	local pluginObject = store
+	if pluginObject == nil then
+		return {}
+	end
+	local saved = pluginObject:GetSetting(SETTING)
+	if typeof(saved) ~= "table" then
+		return {}
+	end
+	local record = saved :: { [string]: any }
+	if record.place ~= placeKey() or typeof(record.rows) ~= "table" then
+		return {}
+	end
+	local rows: { Row } = {}
+	for _, entry in record.rows :: { any } do
+		local row = sane(entry)
+		if row ~= nil then
+			table.insert(rows, row)
+		end
+	end
+	return rows
+end
+
+--[[
+	Writes now. Called from the save loop and from `plugin.Unloading`, where
+	there is no next tick to wait for.
+]]
+function History.flush()
+	local pluginObject, snapshot = store, read
+	if pluginObject == nil or snapshot == nil then
+		return
+	end
+	dirty = false
+	local rows = snapshot()
+	while #rows > MAX_ROWS do
+		table.remove(rows, 1)
+	end
+	-- Guarded because a settings write is disk I/O: a full disk or a locked file
+	-- must cost the console its history, not its session.
+	pcall(function()
+		pluginObject:SetSetting(SETTING, { place = placeKey(), rows = rows })
+	end)
+end
+
+-- Marks the log as changed. Cheap on purpose: it runs on every logged row.
+function History.touch()
+	dirty = true
+end
+
+--[[
+	Starts the save loop. Owned here rather than by the caller so the throttle
+	and the thing it throttles cannot drift apart.
+]]
+function History.start()
+	running = true
+	task.spawn(function()
+		while running do
+			task.wait(SAVE_EVERY)
+			if running and dirty then
+				History.flush()
+			end
+		end
+	end)
+end
+
+-- Stops the loop on unload. A reloaded plugin is a fresh module, so without
+-- this every reload would leave another timer running against a dead session.
+function History.stop()
+	running = false
+end
+
+return History

package/plugin/src/Mirror.luau

@@ -40,6 +40,25 @@ local Mirror = {}
 
 local remote: RemoteEvent? = nil
 
+--[[
+	Held shut until the server session has finished introducing itself.
+
+	Both halves of a playtest log their own banner, place and status, so a
+	channel that is open from the start delivers the server's copy of all of it
+	to a client that has already written its own -- the panel comes up saying
+	"rbx-studio v0.3.6" and "place: Game" twice, a line apart, which reads as a
+	glitch because it is one.
+
+	Opened on the server's "connected" row rather than after a fixed wait: that
+	is the exact point where its startup ends and the session's real activity
+	begins, and everything after it is news the client does not already have.
+]]
+local open = false
+
+function Mirror.open()
+	open = true
+end
+
 --[[
 	True only in the half of a playtest that can reach the bridge.
 
@@ -88,7 +107,7 @@ end
 ]]
 function Mirror.send(kind: string, arguments: { any })
 	local event = remote
-	if event == nil then
+	if event == nil or not open then
 		return
 	end
 	pcall(function()

package/plugin/src/handlers/Capture.luau

@@ -40,6 +40,37 @@ local COMPRESSION_LEVEL = 3
 
 local Capture = {}
 
+--[[
+	Channel value at or under which a byte counts as black.
+
+	Not zero. A capture that failed comes back at exactly zero, but so does a
+	frame that picked up a hair of dithering, and being off by one is not worth
+	an argument.
+]]
+local BLACK_LEVEL = 8
+
+--[[
+	Whether every pixel in the image is black.
+
+	A black screenshot is the one failure this tool cannot report by failing: the
+	call succeeds, the PNG is valid, and the agent reads it as "the game is dark"
+	and reasons on from there. So it is measured and said out loud instead.
+
+	Written to leave on the first byte that is not black, which is what makes it
+	free. A real frame -- even a night scene, which still has a skybox gradient,
+	a GUI or the topbar somewhere -- exits within the first handful of pixels.
+	The whole buffer is only ever walked when the answer is yes, and at that
+	point the walk has earned itself.
+]]
+local function isBlack(rgb: buffer): boolean
+	for offset = 0, buffer.len(rgb) - 1 do
+		if buffer.readu8(rgb, offset) > BLACK_LEVEL then
+			return false
+		end
+	end
+	return true
+end
+
 -- Only a content id comes back over the remote, so this is the time to start a
 -- LocalScript and take one shot, not to move any pixels.
 local CLIENT_TIMEOUT = 25
@@ -74,6 +105,7 @@ local CLIENT_TIMEOUT = 25
 ]]
 local CLIENT_SOURCE = [==[
 local CaptureService = game:GetService("CaptureService")
+local RunService = game:GetService("RunService")
 
 local relay = script
 local report = relay:WaitForChild("Report", 10)
@@ -81,6 +113,15 @@ if report == nil then
 	return
 end
 
+-- One rendered frame before the shot. The RemoteEvent is already a child of
+-- this script when it lands, so `WaitForChild` returns at once and the capture
+-- would otherwise happen on the frame the relay arrived -- which is the frame
+-- least likely to have finished drawing. Roblox's own working repro for
+-- CaptureService waits on PreRender first, and it costs a sixtieth of a second.
+pcall(function()
+	RunService.PreRender:Wait()
+end)
+
 local contentId = nil
 local okShot, shotErr = pcall(function()
 	CaptureService:CaptureScreenshot(function(id)
@@ -259,6 +300,7 @@ local function encode(contentId: string, width: number, context: string): { [str
 	end
 
 	local rgb, outWidth, outHeight = Png.downscaleToRgb(pixels, sourceWidth, sourceHeight, width)
+	local black = isBlack(rgb)
 
 	--[[
 		Raw pixels, compressed by the engine, assembled into a PNG by Node.
@@ -298,6 +340,7 @@ local function encode(contentId: string, width: number, context: string): { [str
 			rawBytes = buffer.len(rgb),
 			bytes = #(packed :: string),
 			context = context,
+			black = black,
 			device = Emulation.deviceId(),
 		}
 	end
@@ -313,6 +356,7 @@ local function encode(contentId: string, width: number, context: string): { [str
 		sourceHeight = sourceHeight,
 		bytes = buffer.len(png),
 		context = context,
+		black = black,
 		device = Emulation.deviceId(),
 	}
 end