@el4cteo/rbx-studio-mcp 0.3.5 → 0.3.7

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

@@ -0,0 +1,145 @@
+--!strict
+--[[
+	Carries console activity from a playtest's SERVER view to its CLIENT view.
+
+	Pressing Play gives this plugin three lives: the editor's, the playtest
+	server's, and the playtest client's. Studio shows whichever belongs to the
+	view you are looking at, and it defaults to the client -- which is the one
+	life that can do nothing. Roblox forbids HTTP from a client session, so that
+	panel has no way to see the bridge, and it sat on a standby notice while the
+	agent worked a few feet away in a view the user was not looking at.
+
+	The two DataModels share no memory, no globals and no services. The only
+	channel between them is the game's own replication, so that is what this
+	uses: the server plugin puts a RemoteEvent in ReplicatedStorage and fires
+	each console event across it; the client plugin listens and replays them
+	into its own console. The prism reacts, the log fills, and the view the user
+	actually has open stops lying about what is happening.
+
+	The cost is honest and worth stating: this plugin writes one instance into
+	the running game. It is `Archivable = false` so it can never be saved with
+	the place, it exists only while a playtest is running, and it goes when the
+	playtest's DataModel does. Nothing reads it but the client half of this
+	plugin, and nothing is sent up from the client -- the traffic is one-way, so
+	a game's own scripts cannot use it to reach the editor.
+]]
+
+local ReplicatedStorage = game:GetService("ReplicatedStorage")
+local RunService = game:GetService("RunService")
+
+--[[
+	Named to be recognised in the Explorer rather than to be hidden.
+
+	Someone will see this appear in ReplicatedStorage mid-playtest and want to
+	know what put it there; a cryptic name turns that into a hunt. The prefix is
+	unlikely enough to collide with a real game's instances.
+]]
+local CHANNEL = "__rbxStudioMcpMirror"
+
+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.
+
+	`IsRunning` separates a playtest from the editor, and `IsServer` separates
+	the two halves of it. The editor session must not do any of this: it has no
+	playtest to mirror and writing to its ReplicatedStorage would put the
+	instance in the user's actual place.
+]]
+function Mirror.isPlaytestServer(): boolean
+	return RunService:IsRunning() and RunService:IsServer()
+end
+
+function Mirror.isPlaytestClient(): boolean
+	return RunService:IsRunning() and RunService:IsClient()
+end
+
+--[[
+	Opens the channel from the playtest server.
+
+	A leftover from an earlier test in the same DataModel is replaced rather
+	than reused: reusing one whose connections are gone looks like a working
+	channel that silently delivers nothing.
+]]
+function Mirror.startServer()
+	if not Mirror.isPlaytestServer() then
+		return
+	end
+	local existing = ReplicatedStorage:FindFirstChild(CHANNEL)
+	if existing ~= nil then
+		existing:Destroy()
+	end
+	local event = Instance.new("RemoteEvent")
+	event.Name = CHANNEL
+	-- Never saved with the place, whatever the user does while the test runs.
+	event.Archivable = false
+	event.Parent = ReplicatedStorage
+	remote = event
+end
+
+--[[
+	Sends one console event, and never fails loudly.
+
+	This is decoration on top of the console. A replication error here must not
+	take down the call it was reporting on, so every send is guarded and a dead
+	channel simply stops mirroring.
+]]
+function Mirror.send(kind: string, arguments: { any })
+	local event = remote
+	if event == nil or not open then
+		return
+	end
+	pcall(function()
+		event:FireAllClients(kind, arguments)
+	end)
+end
+
+--[[
+	Listens on the playtest client.
+
+	`WaitForChild` with a timeout rather than an indefinite wait: if the server
+	half never opens the channel the client should go quiet, not hang a thread
+	for the length of the playtest.
+]]
+function Mirror.startClient(onMessage: (string, { any }) -> ())
+	if not Mirror.isPlaytestClient() then
+		return
+	end
+	task.spawn(function()
+		local event = ReplicatedStorage:WaitForChild(CHANNEL, 30)
+		if event == nil or not event:IsA("RemoteEvent") then
+			return
+		end
+		event.OnClientEvent:Connect(function(kind, arguments)
+			-- Shape-checked because anything on the wire can be forged by a
+			-- script in the place being tested. Nothing here is trusted enough
+			-- to index without looking.
+			if typeof(kind) == "string" and typeof(arguments) == "table" then
+				onMessage(kind, arguments :: { any })
+			end
+		end)
+	end)
+end
+
+return Mirror