@chrrxs/robloxstudio-mcp-inspector 2.11.4 → 2.13.0

package/studio-plugin/src/modules/handlers/InputHandlers.ts

@@ -1,55 +1,101 @@
-interface VIMethods {
-	SendMouseButtonEvent(x: number, y: number, button: number, isDown: boolean): void;
-	SendMouseMoveEvent(x: number, y: number): void;
-	SendMouseWheelEvent(x: number, y: number, isForward: boolean): void;
-	SendKeyEvent(isPressed: boolean, keyCode: Enum.KeyCode, isRepeatedKey: boolean): void;
+// Virtual input via UserInputService:CreateVirtualInput().
+//
+// We deliberately do NOT use VirtualInputManager:Send*Event — those methods
+// are gated behind RobloxScriptSecurity ("lacking capability RobloxScript")
+// in every context a plugin can reach (edit DM, play server/client DMs), so
+// they silently never worked. CreateVirtualInput() is callable without that
+// capability and drives the REAL input pipeline: SendKey feeds
+// UserInputService.InputBegan/Ended and the control modules (so WASD walks the
+// character at full WalkSpeed with controls intact, no Humanoid hijack),
+// SendMouseButton feeds UIS and activates GUI buttons (and hit-tests against
+// CoreGui), and SendTextInput types into the focused TextBox.
+//
+// Method set on the VirtualInput object (verified live):
+//   SendKey(isDown: boolean, keyCode: Enum.KeyCode)
+//   SendMouseButton(position: Vector2, inputType: Enum.UserInputType, isDown: boolean)
+//   SendTextInput(text: string)
+// There is NO SendMouseMove / SendMouseWheel / SendKeyEvent — so "move" and
+// "scroll" mouse actions are not supported.
+//
+// Coordinate space: SendMouseButton coordinates are viewport pixels matching
+// what capture_screenshot returns (window space, origin at the top-left of the
+// rendered viewport). Pass screenshot pixel coordinates straight through. Note
+// that UserInputService reports input positions in GUI space, which is offset
+// from this by GuiService:GetGuiInset() (~58px on the Y axis) — irrelevant for
+// callers who pick coordinates off a screenshot, which is why we do not
+// translate here.
+
+import * as RenderMonitor from "../RenderMonitor";
+
+const UserInputService = game.GetService("UserInputService");
+
+interface VirtualInput {
+	SendKey(isDown: boolean, keyCode: Enum.KeyCode): void;
+	SendMouseButton(position: Vector2, inputType: Enum.UserInputType, isDown: boolean): void;
+	SendTextInput(text: string): void;
 }
 
-function getVIM(): VIMethods | undefined {
-	const [ok, result] = pcall(() => {
-		return (game as unknown as { GetService(name: string): Instance }).GetService("VirtualInputManager");
+// One VirtualInput per plugin VM, reused across calls so that a key held down
+// in one call (action="press") and released in a later call (action="release")
+// share the same input source.
+let cachedVI: VirtualInput | undefined;
+
+function getVI(): VirtualInput | undefined {
+	if (cachedVI) return cachedVI;
+	const [ok, vi] = pcall(() => {
+		return (UserInputService as unknown as { CreateVirtualInput(): unknown }).CreateVirtualInput();
 	});
-	if (ok && result) return result as unknown as VIMethods;
+	if (ok && vi !== undefined) {
+		cachedVI = vi as VirtualInput;
+		return cachedVI;
+	}
 	return undefined;
 }
 
-const BUTTON_MAP: Record<string, number> = { Left: 0, Right: 1, Middle: 2 };
+const MOUSE_TYPE_MAP: Record<string, Enum.UserInputType> = {
+	Left: Enum.UserInputType.MouseButton1,
+	Right: Enum.UserInputType.MouseButton2,
+	Middle: Enum.UserInputType.MouseButton3,
+};
 
 function simulateMouseInput(requestData: Record<string, unknown>) {
 	const action = requestData.action as string;
 	const x = requestData.x as number | undefined;
 	const y = requestData.y as number | undefined;
 	const button = (requestData.button as string) ?? "Left";
-	const scrollDirection = requestData.scrollDirection as string | undefined;
 
 	if (!action) return { error: "action is required" };
+	if (x === undefined || y === undefined) {
+		return { error: "x and y are required" };
+	}
 
-	const vim = getVIM();
-	if (!vim) return { error: "VirtualInputManager is not available in this context" };
+	// Input is silently dropped by the engine when the window isn't rendering
+	// (e.g. minimized). Surface that instead of returning a false success.
+	const notRendering = RenderMonitor.notRenderingReason();
+	if (notRendering !== undefined) return { error: notRendering };
+
+	const vi = getVI();
+	if (!vi) {
+		return { error: "UserInputService:CreateVirtualInput() is not available in this context" };
+	}
 
-	const buttonNum = BUTTON_MAP[button] ?? 0;
+	const inputType = MOUSE_TYPE_MAP[button] ?? Enum.UserInputType.MouseButton1;
+	const pos = new Vector2(x, y);
 
 	const [success, err] = pcall(() => {
 		if (action === "click") {
-			if (x === undefined || y === undefined) error("x and y are required for click");
-			vim.SendMouseButtonEvent(x, y, buttonNum, true);
+			vi.SendMouseButton(pos, inputType, true);
 			task.wait(0.05);
-			vim.SendMouseButtonEvent(x, y, buttonNum, false);
+			vi.SendMouseButton(pos, inputType, false);
 		} else if (action === "mouseDown") {
-			if (x === undefined || y === undefined) error("x and y are required for mouseDown");
-			vim.SendMouseButtonEvent(x, y, buttonNum, true);
+			vi.SendMouseButton(pos, inputType, true);
 		} else if (action === "mouseUp") {
-			if (x === undefined || y === undefined) error("x and y are required for mouseUp");
-			vim.SendMouseButtonEvent(x, y, buttonNum, false);
-		} else if (action === "move") {
-			if (x === undefined || y === undefined) error("x and y are required for move");
-			vim.SendMouseMoveEvent(x, y);
-		} else if (action === "scroll") {
-			if (x === undefined || y === undefined) error("x and y are required for scroll");
-			if (!scrollDirection) error("scrollDirection is required for scroll");
-			vim.SendMouseWheelEvent(x, y, scrollDirection === "up");
+			vi.SendMouseButton(pos, inputType, false);
 		} else {
-			error(`Unknown action: ${action}`);
+			error(
+				`Unsupported action "${action}". CreateVirtualInput supports click, mouseDown, mouseUp ` +
+					`(no move/scroll — those methods don't exist on VirtualInput).`,
+			);
 		}
 	});
 
@@ -60,31 +106,46 @@ function simulateMouseInput(requestData: Record<string, unknown>) {
 }
 
 function simulateKeyboardInput(requestData: Record<string, unknown>) {
+	const notRendering = RenderMonitor.notRenderingReason();
+	if (notRendering !== undefined) return { error: notRendering };
+
+	const vi = getVI();
+	if (!vi) {
+		return { error: "UserInputService:CreateVirtualInput() is not available in this context" };
+	}
+
+	// Text mode: type a string into the focused TextBox.
+	const text = requestData.text as string | undefined;
+	if (text !== undefined) {
+		const [ok, err] = pcall(() => vi.SendTextInput(text));
+		if (ok) return { success: true, text };
+		return { error: `Failed to send text input: ${err}` };
+	}
+
 	const keyCodeName = requestData.keyCode as string;
+	if (!keyCodeName) return { error: "keyCode (or text) is required" };
+
 	const action = (requestData.action as string) ?? "tap";
 	const duration = (requestData.duration as number) ?? 0.1;
 
-	if (!keyCodeName) return { error: "keyCode is required" };
-
-	const vim = getVIM();
-	if (!vim) return { error: "VirtualInputManager is not available in this context" };
-
 	const [enumOk, keyCode] = pcall(() => {
 		return (Enum.KeyCode as unknown as Record<string, Enum.KeyCode>)[keyCodeName];
 	});
 	if (!enumOk || !keyCode) {
-		return { error: `Unknown keyCode: ${keyCodeName}. Use Enum.KeyCode names like "W", "Space", "E", "LeftShift", etc.` };
+		return {
+			error: `Unknown keyCode: ${keyCodeName}. Use Enum.KeyCode names like "W", "Space", "E", "LeftShift", etc.`,
+		};
 	}
 
 	const [success, err] = pcall(() => {
 		if (action === "press") {
-			vim.SendKeyEvent(true, keyCode, false);
+			vi.SendKey(true, keyCode);
 		} else if (action === "release") {
-			vim.SendKeyEvent(false, keyCode, false);
+			vi.SendKey(false, keyCode);
 		} else if (action === "tap") {
-			vim.SendKeyEvent(true, keyCode, false);
+			vi.SendKey(true, keyCode);
 			task.wait(duration);
-			vim.SendKeyEvent(false, keyCode, false);
+			vi.SendKey(false, keyCode);
 		} else {
 			error(`Unknown action: ${action}`);
 		}

package/studio-plugin/src/modules/handlers/MetadataHandlers.ts

@@ -1,6 +1,7 @@
-import { CollectionService, LogService } from "@rbxts/services";
+import { CollectionService } from "@rbxts/services";
 import Utils from "../Utils";
 import Recording from "../Recording";
+import LuauExec from "../LuauExec";
 
 const ChangeHistoryService = game.GetService("ChangeHistoryService");
 const Selection = game.GetService("Selection");
@@ -262,151 +263,11 @@ function getSelection(_requestData: Record<string, unknown>) {
 function executeLuau(requestData: Record<string, unknown>) {
 	const code = requestData.code as string;
 	if (!code || code === "") return { error: "Code is required" };
-
-	// Both execution paths (loadstring + ModuleScript-require fallback) run
-	// the SAME wrapped source so they return a uniform { ok, value, output }
-	// shape. Two problems the wrapper solves at once:
-	//
-	//   1. pcall(require, m) swallows the real error and returns Roblox's
-	//      generic "Requested module experienced an error while loading"
-	//      message. Wrapping user code in xpcall INSIDE the IIFE keeps the
-	//      ModuleScript itself returning successfully — the real error +
-	//      traceback live in the returned table.
-	//
-	//   2. The ModuleScript path runs in its own environment, so a plugin-
-	//      side getfenv print/warn override never reached user prints. A
-	//      lexical local print/warn inside the IIFE captures user prints
-	//      regardless of which path executes. We also call the real global
-	//      print/warn so messages still flow to Studio's output and
-	//      LogService.MessageOut (which powers get_runtime_logs).
-	//
-	// Prints from required sub-modules don't reach this capture (they have
-	// their own env) — those go through the runtime log buffer.
-	const wrapped = `return ((function()
-\tlocal __mcp_output = {}
-\tlocal __mcp_real_print = print
-\tlocal __mcp_real_warn = warn
-\tlocal print = function(...)
-\t\t__mcp_real_print(...)
-\t\tlocal args = {...}
-\t\tlocal parts = table.create(#args)
-\t\tfor i, a in ipairs(args) do parts[i] = tostring(a) end
-\t\ttable.insert(__mcp_output, table.concat(parts, "\\t"))
-\tend
-\tlocal warn = function(...)
-\t\t__mcp_real_warn(...)
-\t\tlocal args = {...}
-\t\tlocal parts = table.create(#args)
-\t\tfor i, a in ipairs(args) do parts[i] = tostring(a) end
-\t\ttable.insert(__mcp_output, "[warn] " .. table.concat(parts, "\\t"))
-\tend
-\tlocal function __mcp_run()
-${code}
-\tend
-\tlocal ok, errOrValue = xpcall(__mcp_run, debug.traceback)
-\treturn { ok = ok, value = errOrValue, output = __mcp_output }
-end)())`;
-
-	interface WrapperResult {
-		ok?: boolean;
-		value?: unknown;
-		output?: defined;
-	}
-
-	const runViaModuleScript = (): WrapperResult => {
-		const m = new Instance("ModuleScript");
-		m.Name = "__MCPExecLuauPayload";
-		const [okSet, setErr] = pcall(() => {
-			(m as unknown as { Source: string }).Source = wrapped;
-		});
-		if (!okSet) {
-			m.Destroy();
-			error(`ModuleScript Source set failed: ${tostring(setErr)}`);
-		}
-		m.Parent = game.GetService("Workspace");
-		const [okReq, reqResult] = pcall(() => require(m));
-		m.Destroy();
-		if (!okReq) {
-			let errMsg = tostring(reqResult);
-			// pcall(require, m) collapses parse/compile failures into the
-			// canned engine string below. Walk LogService backward for the
-			// real diagnostic, which was emitted to MessageOut just before.
-			if (errMsg === "Requested module experienced an error while loading") {
-				// The parser diagnostic is emitted to LogService on the next
-				// engine frame, not synchronously with pcall(require). task.wait(0)
-				// yields too early; 50ms is enough to let the frame complete and
-				// the message land in GetLogHistory.
-				task.wait(0.05);
-				const hist = LogService.GetLogHistory();
-				for (let i = hist.size() - 1; i >= 0; i--) {
-					const e = hist[i];
-					if (
-						e.messageType === Enum.MessageType.MessageError &&
-						string.sub(e.message, 1, 31) === "Workspace.__MCPExecLuauPayload:"
-					) {
-						errMsg = e.message;
-						break;
-					}
-				}
-			}
-			error(errMsg);
-		}
-		return reqResult as unknown as WrapperResult;
-	};
-
-	const isLoadstringUnavailable = (err: unknown): boolean => {
-		const errStr = tostring(err);
-		const [matchStart] = string.find(errStr, "not available", 1, true);
-		return matchStart !== undefined;
-	};
-
-	let [success, result] = pcall(() => {
-		const [fn, compileError] = loadstring(wrapped);
-		if (!fn) {
-			if (isLoadstringUnavailable(compileError)) {
-				return runViaModuleScript();
-			}
-			error(`Compile error: ${compileError}`);
-		}
-		return fn() as unknown as WrapperResult;
-	});
-
-	// loadstring throws (not returns nil) in some plugin contexts when
-	// LoadStringEnabled=false. Catch that as a second-chance fallback.
-	if (!success && isLoadstringUnavailable(result)) {
-		[success, result] = pcall(runViaModuleScript);
-	}
-
-	if (!success) {
-		// Outer pcall failed - the wrapper itself didn't even run (e.g. compile
-		// error in the user code, or ModuleScript setup error). 'result' is the
-		// raw error string from pcall.
-		return {
-			success: false,
-			error: tostring(result),
-			output: [],
-			message: "Code execution failed",
-		};
-	}
-
-	// Wrapper executed - unpack { ok, value, output }.
-	const r = result as unknown as WrapperResult;
-	const capturedOutput = r.output as unknown as string[] | undefined;
-	const output = capturedOutput !== undefined ? capturedOutput : ([] as string[]);
-	if (r.ok === true) {
-		return {
-			success: true,
-			returnValue: r.value !== undefined ? tostring(r.value) : undefined,
-			output,
-			message: "Code executed successfully",
-		};
-	}
-	return {
-		success: false,
-		error: r.value !== undefined ? tostring(r.value) : "(unknown error)",
-		output,
-		message: "Code execution failed",
-	};
+	// All wrapping, print/warn capture, loadstring fallback, JSON-encoding
+	// of table returns, and parse-error recovery live in LuauExec so the
+	// edit/server (this handler) and the play-client (ClientBroker) take
+	// the same code path and produce identical output shapes.
+	return LuauExec.execute(code);
 }
 
 function undo(_requestData: Record<string, unknown>) {

package/studio-plugin/src/modules/handlers/TestHandlers.ts

@@ -1,5 +1,5 @@
 import { HttpService, LogService, RunService } from "@rbxts/services";
-import { installBridges, cleanupBridges } from "../EvalBridges";
+import { installBridges, ensureBridgesInstalled } from "../EvalBridges";
 import StopPlayMonitor from "../StopPlayMonitor";
 
 const StudioTestService = game.GetService("StudioTestService");
@@ -135,7 +135,9 @@ function startPlaytest(requestData: Record<string, unknown>) {
 			logConnection = undefined;
 		}
 		cleanupStopListener();
-		cleanupBridges();
+		// Note: eval bridges are intentionally NOT cleaned up — they live
+		// permanently in the edit DM so manual playtests also get them. See
+		// EvalBridges.ts lifecycle comment.
 	}
 
 	if (testRunning) {
@@ -169,9 +171,10 @@ function startPlaytest(requestData: Record<string, unknown>) {
 		warn(`[MCP] Failed to inject stop listener: ${injErr}`);
 	}
 
-	// Auto-install the game-VM eval bridges (ServerEvalBridge + ClientEvalBridge)
-	// so eval_server_runtime / eval_client_runtime work without manual setup.
-	// Bridges are cleaned up from the edit DM after the play DMs tear down.
+	// Force-refresh the game-VM eval bridges (ServerEvalBridge + ClientEvalBridge)
+	// right before cloning so the play DMs get the current source. They also
+	// live permanently in the edit DM (installed on connect) so manually-started
+	// playtests get them too; here we just ensure they're fresh.
 	const bridgeInstall = installBridges();
 	if (!bridgeInstall.installed) {
 		warn(`[MCP] Eval bridge install failed: ${bridgeInstall.error}`);
@@ -203,7 +206,9 @@ function startPlaytest(requestData: Record<string, unknown>) {
 		testRunning = false;
 
 		cleanupStopListener();
-		cleanupBridges();
+		// Eval bridges persist in the edit DM (see EvalBridges.ts) — do not
+		// clean up here, so the next manual playtest still gets them.
+		ensureBridgesInstalled();
 	});
 
 	const msg = numPlayers !== undefined
@@ -235,9 +240,27 @@ function stopPlaytest(_requestData: Record<string, unknown>) {
 		return { error: "Plugin not ready. Try again in a moment." };
 	}
 	if (!StopPlayMonitor.waitForConsumption()) {
-		// Clean up the pending flag so a future playtest's monitor doesn't fire
-		// EndTest on its own startup against a stale signal.
+		// Two distinct failure modes collapse here, distinguished by whether
+		// THIS edit DM has a playtest tracked:
+		//
+		// - testRunning=false: no playtest was running from this edit DM
+		//   (true negative). Return "no active playtest" — fine to retry only
+		//   after actually starting a playtest.
+		// - testRunning=true: a playtest IS running but the cross-DM signal
+		//   didn't propagate within the consumption timeout (false negative
+		//   from the caller's perspective — playtest may actually have ended).
+		//   Tell the caller it's a timing issue and they can retry.
+		//
+		// Either way clean up the pending flag so a future playtest's monitor
+		// doesn't fire EndTest on startup against a stale signal.
 		StopPlayMonitor.clearPending();
+		if (testRunning) {
+			return {
+				error:
+					"Playtest stop signal sent but consumption confirmation timed out. " +
+					"The playtest may have ended anyway; check get_connected_instances.",
+			};
+		}
 		return { error: "No active playtest to stop." };
 	}
 	// Flag was consumed (EndTest called). ExecutePlayModeAsync in our

package/studio-plugin/src/server/index.server.ts

@@ -4,6 +4,12 @@ import Communication from "../modules/Communication";
 import ClientBroker from "../modules/ClientBroker";
 import RuntimeLogBuffer from "../modules/RuntimeLogBuffer";
 import StopPlayMonitor from "../modules/StopPlayMonitor";
+import * as RenderMonitor from "../modules/RenderMonitor";
+
+// Track render-loop liveness so input/screenshot tools can report "window
+// minimized / not rendering" instead of silently no-op'ing. No-op in the
+// server DM (RenderStepped can't connect there).
+RenderMonitor.start();
 
 // Attach the per-peer LogService.MessageOut listener as early as possible so
 // boot-time prints from the user's place scripts are captured. Powers the

package/studio-plugin/src/types/index.d.ts

@@ -33,14 +33,17 @@ export interface PollResponse {
 	request?: RequestPayload;
 	requestId?: string;
 	// Server signals knownInstance=false when its in-memory instances map
-	// doesn't contain our instanceId (typically after an MCP process restart).
-	// The plugin re-issues /ready when it sees this.
+	// doesn't contain our pluginSessionId (typically after an MCP process
+	// restart). The plugin re-issues /ready when it sees this.
 	knownInstance?: boolean;
 }
 
 export interface ReadyResponse {
 	success: boolean;
 	assignedRole?: string;
+	instanceId?: string;
+	error?: string;
+	message?: string;
 }
 
 declare global {