@chrrxs/robloxstudio-mcp 2.12.0 → 2.14.0

package/studio-plugin/src/modules/ClientBroker.ts

@@ -1,8 +1,18 @@
 import { HttpService, Players, ReplicatedStorage, RunService, ServerStorage } from "@rbxts/services";
 import RuntimeLogBuffer from "./RuntimeLogBuffer";
 import MemoryHandlers from "./handlers/MemoryHandlers";
+import CaptureHandlers from "./handlers/CaptureHandlers";
+import InputHandlers from "./handlers/InputHandlers";
 import LuauExec from "./LuauExec";
 
+interface StudioTestServiceMultiplayer extends StudioTestService {
+	CanLeaveTest(): boolean;
+	LeaveTest(): void;
+	EditModeActive: boolean;
+}
+
+const StudioTestService = game.GetService("StudioTestService") as StudioTestServiceMultiplayer;
+
 // Mirror of Communication.computeInstanceId() — duplicated here because the
 // client broker runs in the play-server DM where it can't easily import from
 // the edit-side module, and the place identifier must match what the edit-DM
@@ -53,6 +63,7 @@ function resolvePlaceName(): string {
 
 const MCP_URL = "http://localhost:58741";
 const BROKER_NAME = "__MCPClientBroker";
+const BROKER_OWNER_ATTRIBUTE = "__MCPBrokerOwner";
 
 interface ProxyEntry {
 	pluginSessionId: string;
@@ -76,6 +87,15 @@ const CLIENT_BROKER_ALLOWED_ENDPOINTS = new Set<string>([
 	"/api/execute-luau",
 	"/api/get-runtime-logs",
 	"/api/get-memory-breakdown",
+	"/api/multiplayer-test-state",
+	"/api/multiplayer-test-leave-client",
+	// Screenshot capture must run in the client peer (CaptureService captures
+	// the play viewport there); the edit DM reads the temp id back separately.
+	"/api/capture-begin",
+	// Virtual input (CreateVirtualInput) drives the running client's input
+	// pipeline, so it must execute in the client peer's VM.
+	"/api/simulate-mouse-input",
+	"/api/simulate-keyboard-input",
 ]);
 
 interface ReadyResponseBody {
@@ -155,6 +175,52 @@ function handleGetRuntimeLogs(data: Record<string, unknown> | undefined): unknow
 	return RuntimeLogBuffer.query({ since, tail, filter }, "client");
 }
 
+function handleMultiplayerTestState(): unknown {
+	const [argsOk, args] = pcall(() => StudioTestService.GetTestArgs());
+	const [canLeaveOk, canLeave] = pcall(() => StudioTestService.CanLeaveTest());
+	const players = Players.GetPlayers().map((player) => ({
+		name: player.Name,
+		userId: player.UserId,
+		displayName: player.DisplayName,
+	}));
+	players.sort((a, b) => a.name < b.name);
+	return {
+		success: true,
+		peer: "client",
+		isRunning: RunService.IsRunning(),
+		isRunMode: RunService.IsRunMode(),
+		editModeActive: StudioTestService.EditModeActive,
+		testArgsOk: argsOk,
+		testArgs: argsOk ? args : undefined,
+		testArgsError: argsOk ? undefined : tostring(args),
+		players,
+		playerCount: players.size(),
+		localPlayer: Players.LocalPlayer ? Players.LocalPlayer.Name : undefined,
+		canLeaveOk,
+		canLeave: canLeaveOk ? canLeave : false,
+		canLeaveError: canLeaveOk ? undefined : tostring(canLeave),
+	};
+}
+
+function handleMultiplayerTestLeaveClient(): unknown {
+	const [canLeaveOk, canLeave] = pcall(() => StudioTestService.CanLeaveTest());
+	if (!canLeaveOk) {
+		return { error: tostring(canLeave), canLeaveOk: false };
+	}
+	if (!canLeave) {
+		return { error: "This client cannot leave the current test session.", canLeaveOk: true, canLeave: false };
+	}
+	const localPlayer = Players.LocalPlayer ? Players.LocalPlayer.Name : undefined;
+	task.defer(() => {
+		pcall(() => StudioTestService.LeaveTest());
+	});
+	return {
+		success: true,
+		message: "Client leave requested.",
+		localPlayer,
+	};
+}
+
 function setupClientBroker() {
 	const rf = ReplicatedStorage.WaitForChild(BROKER_NAME, 10);
 	if (!rf || !rf.IsA("RemoteFunction")) {
@@ -174,6 +240,21 @@ function setupClientBroker() {
 		if (payload && payload.endpoint === "/api/get-memory-breakdown") {
 			return MemoryHandlers.getMemoryBreakdown(payload.data ?? {});
 		}
+		if (payload && payload.endpoint === "/api/multiplayer-test-state") {
+			return handleMultiplayerTestState();
+		}
+		if (payload && payload.endpoint === "/api/multiplayer-test-leave-client") {
+			return handleMultiplayerTestLeaveClient();
+		}
+		if (payload && payload.endpoint === "/api/capture-begin") {
+			return CaptureHandlers.captureBegin();
+		}
+		if (payload && payload.endpoint === "/api/simulate-mouse-input") {
+			return InputHandlers.simulateMouseInput(payload.data ?? {});
+		}
+		if (payload && payload.endpoint === "/api/simulate-keyboard-input") {
+			return InputHandlers.simulateKeyboardInput(payload.data ?? {});
+		}
 		if (payload && payload.endpoint === "/api/execute-luau") {
 			return handleExecuteLuau(payload.data);
 		}
@@ -183,6 +264,7 @@ function setupClientBroker() {
 }
 
 const proxyByPlayer = new Map<Player, ProxyEntry>();
+let serverBrokerStarted = false;
 
 function pollProxy(proxyId: string, player: Player, rf: RemoteFunction) {
 	while (player.Parent !== undefined && proxyByPlayer.has(player)) {
@@ -215,10 +297,12 @@ function pollProxy(proxyId: string, player: Player, rf: RemoteFunction) {
 							response = { success: false, error: `InvokeClient failed: ${tostring(invokeRes)}` };
 						}
 					} else {
+						const allowed: string[] = [];
+						for (const ep of CLIENT_BROKER_ALLOWED_ENDPOINTS) allowed.push(ep);
 						response = {
 							error:
 								`Client-proxy does not forward ${tostring(request.endpoint)}. ` +
-								`Allowed: /api/execute-luau, /api/get-runtime-logs.`,
+								`Allowed: ${allowed.join(", ")}.`,
 						};
 					}
 					postJson("/response", { requestId: body.requestId, response });
@@ -257,12 +341,18 @@ function registerProxy(player: Player, rf: RemoteFunction) {
 // which doesn't depend on MCP server state or peer registration at all.)
 
 function setupServerBroker() {
+	if (serverBrokerStarted) return;
 	let rf = ReplicatedStorage.FindFirstChild(BROKER_NAME) as RemoteFunction | undefined;
 	if (!rf) {
 		rf = new Instance("RemoteFunction");
 		rf.Name = BROKER_NAME;
 		rf.Parent = ReplicatedStorage;
 	}
+	if (rf.GetAttribute(BROKER_OWNER_ATTRIBUTE) !== undefined) {
+		return;
+	}
+	rf.SetAttribute(BROKER_OWNER_ATTRIBUTE, HttpService.GenerateGUID(false));
+	serverBrokerStarted = true;
 	const broker = rf;
 	Players.PlayerAdded.Connect((p) => registerProxy(p, broker));
 	for (const p of Players.GetPlayers()) {

package/studio-plugin/src/modules/Communication.ts

@@ -2,6 +2,7 @@ import { HttpService, RunService, ServerStorage } from "@rbxts/services";
 import State from "./State";
 import Utils from "./Utils";
 import UI from "./UI";
+import { ensureBridgesInstalled } from "./EvalBridges";
 import QueryHandlers from "./handlers/QueryHandlers";
 import PropertyHandlers from "./handlers/PropertyHandlers";
 import InstanceHandlers from "./handlers/InstanceHandlers";
@@ -132,6 +133,11 @@ const routeMap: Record<string, Handler> = {
 	"/api/start-playtest": TestHandlers.startPlaytest,
 	"/api/stop-playtest": TestHandlers.stopPlaytest,
 	"/api/get-playtest-output": TestHandlers.getPlaytestOutput,
+	"/api/multiplayer-test-start": TestHandlers.multiplayerTestStart,
+	"/api/multiplayer-test-state": TestHandlers.multiplayerTestState,
+	"/api/multiplayer-test-add-players": TestHandlers.multiplayerTestAddPlayers,
+	"/api/multiplayer-test-leave-client": TestHandlers.multiplayerTestLeaveClient,
+	"/api/multiplayer-test-end": TestHandlers.multiplayerTestEnd,
 	"/api/character-navigation": TestHandlers.characterNavigation,
 
 	"/api/export-build": BuildHandlers.exportBuild,
@@ -143,6 +149,8 @@ const routeMap: Record<string, Handler> = {
 	"/api/preview-asset": AssetHandlers.previewAsset,
 
 	"/api/capture-screenshot": CaptureHandlers.captureScreenshot,
+	"/api/capture-begin": CaptureHandlers.captureBegin,
+	"/api/capture-read": CaptureHandlers.captureRead,
 	"/api/simulate-mouse-input": InputHandlers.simulateMouseInput,
 	"/api/simulate-keyboard-input": InputHandlers.simulateKeyboardInput,
 
@@ -458,6 +466,20 @@ function activatePlugin(connIndex?: number) {
 	// later reports knownInstance=false (process restart, etc).
 	sendReady(conn);
 
+	// Keep the eval bridges present in the edit DM so that ANY playtest —
+	// including one the dev starts manually via the Studio Play button —
+	// clones them into the play DMs and eval_*_runtime works with no setup
+	// roundtrip. Only the edit DM installs; play DMs already have the cloned
+	// copies. Idempotent, so reconnects don't re-dirty the place.
+	if (!RunService.IsRunning()) {
+		task.spawn(() => {
+			const result = ensureBridgesInstalled();
+			if (!result.installed) {
+				warn(`[MCPPlugin] Eval bridge install failed: ${result.error}`);
+			}
+		});
+	}
+
 	// Watch for game.Name updates so a stale "Place1" captured at first
 	// /ready gets refreshed once Studio settles on the real DM name.
 	ensureNameChangeWatcher(conn);

package/studio-plugin/src/modules/EvalBridges.ts

@@ -21,11 +21,16 @@
 // ServerScriptService.LoadStringEnabled, so eval_server_runtime works even
 // when LoadStringEnabled=false (the default in fresh places).
 //
-// Lifecycle: TestHandlers.startPlaytest inserts both scripts into the EDIT
-// DM right before ExecutePlayModeAsync. ExecutePlayModeAsync clones the
-// DataModel into the play DMs, so the scripts come along and run there.
-// TestHandlers cleans them up from the edit DM when ExecutePlayModeAsync
-// returns (test ended for any reason: stop_playtest, manual close, EndTest).
+// Lifecycle: the bridges live PERMANENTLY in the edit DM. Communication
+// installs them (ensureBridgesInstalled) when the plugin connects in edit,
+// and TestHandlers.startPlaytest force-refreshes them right before
+// ExecutePlayModeAsync. ExecutePlayModeAsync clones the DataModel into the
+// play DMs, so the scripts come along and run there. We keep them in the edit
+// DM after a playtest ends (rather than cleaning up) so that a playtest the
+// dev starts MANUALLY via the Studio Play button — not the MCP start_playtest
+// tool — also gets the bridges cloned in. This is intentionally a little
+// intrusive (two helper scripts visible in Explorer) in exchange for a
+// zero-roundtrip eval_*_runtime experience for devs working 1:1 with an agent.
 //
 // Archivable handling: ExecutePlayModeAsync's deep-clone SKIPS instances
 // with Archivable=false (verified empirically in v2.9.0 testing - bridges
@@ -61,9 +66,9 @@ export const BRIDGE_NAMES = {
 // Embedded Luau. The double `${...}` references our exported names so a
 // rename here propagates to both the script source and the tool wrappers.
 const SERVER_BRIDGE_SOURCE = `
--- Auto-installed by @chrrxs/robloxstudio-mcp at start_playtest, removed at
--- stop_playtest. Provides shared-require-cache eval on the server peer for
--- the eval_server_runtime MCP tool.
+-- Installed by @chrrxs/robloxstudio-mcp to power the eval_server_runtime MCP
+-- tool (shared-require-cache eval on the server during playtests). Inert
+-- outside Studio (no-ops in live games); safe to leave in place.
 
 local ServerScriptService = game:GetService("ServerScriptService")
 local RunService = game:GetService("RunService")
@@ -88,9 +93,9 @@ end
 `;
 
 const CLIENT_BRIDGE_SOURCE = `
--- Auto-installed by @chrrxs/robloxstudio-mcp at start_playtest, removed at
--- stop_playtest. Provides shared-require-cache eval on the client peer for
--- the eval_client_runtime MCP tool.
+-- Installed by @chrrxs/robloxstudio-mcp to power the eval_client_runtime MCP
+-- tool (shared-require-cache eval on the client during playtests). Inert
+-- outside Studio (no-ops in live games); safe to leave in place.
 
 local ReplicatedStorage = game:GetService("ReplicatedStorage")
 local RunService = game:GetService("RunService")
@@ -114,6 +119,28 @@ bf.OnInvoke = function(payload)
 end
 `;
 
+// Stamp written onto each installed bridge Script so we can tell whether the
+// bridge currently in the DM was produced by THIS plugin build. It's a djb2
+// hash of the actual bridge source plus the plugin version, so ANY change to
+// the source (or a version bump) yields a new stamp — which makes
+// ensureBridgesInstalled() force a refresh on the next plugin load instead of
+// keeping a stale bridge that happens to still be present (e.g. one saved into
+// the .rbxl from an older build).
+const STAMP_ATTR = "__MCPBridgeStamp";
+
+function computeBridgeStamp(): string {
+	const combined = `${SERVER_BRIDGE_SOURCE}|${CLIENT_BRIDGE_SOURCE}`;
+	let h = 5381;
+	for (let i = 1; i <= combined.size(); i++) {
+		h = (h * 33 + string.byte(combined, i)[0]) % 2147483647;
+	}
+	// "__VERSION__" is replaced with the package version at package time
+	// (scripts/build-plugin.mjs injectVersion), so a release bump also restamps.
+	return `${tostring(h)}-__VERSION__`;
+}
+
+const BRIDGE_STAMP = computeBridgeStamp();
+
 function setSource(scriptInst: Script | LocalScript, source: string): void {
 	// ScriptEditorService is the cleaner API and integrates with Studio's
 	// edit history; fall back to direct Source mutation (allowed in plugin
@@ -144,6 +171,26 @@ export function cleanupBridges(): void {
 	}
 }
 
+// Idempotent variant: install only if the bridge scripts aren't already
+// present in the edit DM. Used to keep the bridges always available (so a
+// playtest the dev starts manually — not via the MCP start_playtest tool —
+// still clones them into the play DMs). Cheap no-op when already installed,
+// which avoids re-dirtying the place on every plugin reconnect.
+export function ensureBridgesInstalled(): { installed: boolean; error?: string } {
+	const { server, client } = findBridges();
+	if (server && client) {
+		// Both present — but only skip the reinstall if they were produced by
+		// THIS build. A mismatched/absent stamp means a stale bridge (older
+		// plugin, or one persisted in the saved place), so force a refresh.
+		const sStamp = server.GetAttribute(STAMP_ATTR);
+		const cStamp = client.GetAttribute(STAMP_ATTR);
+		if (sStamp === BRIDGE_STAMP && cStamp === BRIDGE_STAMP) {
+			return { installed: true };
+		}
+	}
+	return installBridges();
+}
+
 export function installBridges(): { installed: boolean; error?: string } {
 	// Defensive: clear any stale bridges from a prior unclean exit before
 	// inserting fresh. The injected script also self-cleans its
@@ -158,6 +205,7 @@ export function installBridges(): { installed: boolean; error?: string } {
 		// script. cleanupBridges() removes it from the edit DM when the
 		// playtest ends.
 		setSource(serverScript, SERVER_BRIDGE_SOURCE);
+		serverScript.SetAttribute(STAMP_ATTR, BRIDGE_STAMP);
 		serverScript.Parent = ServerScriptService;
 
 		const sps = getStarterPlayerScripts();
@@ -167,6 +215,7 @@ export function installBridges(): { installed: boolean; error?: string } {
 		const clientScript = new Instance("LocalScript");
 		clientScript.Name = CLIENT_SCRIPT_NAME;
 		setSource(clientScript, CLIENT_BRIDGE_SOURCE);
+		clientScript.SetAttribute(STAMP_ATTR, BRIDGE_STAMP);
 		clientScript.Parent = sps;
 	});
 

package/studio-plugin/src/modules/RenderMonitor.ts

@@ -0,0 +1,60 @@
+// Detects whether the Studio window is actually rendering, so virtual input
+// and screenshot tools can surface a clear reason instead of silently failing.
+//
+// When a Studio window is MINIMIZED, the engine suspends the render loop AND
+// input processing, but keeps running scripts (Heartbeat keeps firing). That's
+// why simulate_*_input would return success while having zero effect, and
+// CaptureService:CaptureScreenshot would time out. Validated live: during a 3s
+// minimize, RenderStepped's max inter-frame gap was 5.08s while Heartbeat's was
+// 0.10s. So RenderStepped freshness is the reliable "is this window rendering?"
+// signal; Heartbeat is not.
+
+import { RunService } from "@rbxts/services";
+
+let lastFrame = 0;
+let connected = false;
+
+// Above this many seconds since the last rendered frame, we treat the window
+// as not rendering. RenderStepped normally fires every ~16ms; a multi-second
+// gap only happens when minimized/suspended, so 1s cleanly avoids false
+// positives from ordinary frame hitches while still catching the real case.
+const STALE_THRESHOLD = 1.0;
+
+export function start(): void {
+	if (connected) return;
+	// RenderStepped can only be connected from a client/edit render loop; it
+	// throws in the play-server DM. pcall so a server-DM call is a safe no-op
+	// (connected stays false → notRenderingReason() returns undefined there).
+	const [ok] = pcall(() => {
+		RunService.RenderStepped.Connect(() => {
+			lastFrame = tick();
+		});
+	});
+	if (ok) {
+		connected = true;
+		lastFrame = tick();
+	}
+}
+
+export function secondsSinceFrame(): number {
+	if (!connected) return 0;
+	return tick() - lastFrame;
+}
+
+// Returns a human-readable reason if the window appears minimized / not
+// rendering (so input + screenshots won't work), else undefined. Fail-open:
+// when the monitor isn't active in this DM (server peer, or connect failed) it
+// returns undefined so we never block on a false signal.
+export function notRenderingReason(): string | undefined {
+	if (!connected) return undefined;
+	const gap = secondsSinceFrame();
+	if (gap > STALE_THRESHOLD) {
+		return string.format(
+			"Studio window appears minimized or not rendering (no frame in %.1fs). " +
+				"Virtual input and screenshots only work while the window is visible — " +
+				"restore/un-minimize the Studio window and retry.",
+			gap,
+		);
+	}
+	return undefined;
+}

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

@@ -1,3 +1,5 @@
+import * as RenderMonitor from "../RenderMonitor";
+
 const CaptureService = game.GetService("CaptureService");
 const AssetService = game.GetService("AssetService");
 
@@ -71,7 +73,17 @@ function readPixelsTiled(img: EditableImage, w: number, h: number): buffer {
 	return fullBuf;
 }
 
-function captureScreenshotData(): unknown {
+// Triggers CaptureService:CaptureScreenshot and waits for the temporary
+// content id. Works in any DM, including the play CLIENT (where reading the
+// pixels back is blocked, but capturing is not). The returned rbxtemp:// id is
+// a process-scoped handle: it can be dereferenced from a DIFFERENT, more
+// privileged DM (the edit DM) — see captureRead.
+function doCaptureScreenshot(): { contentId: string } | { error: string } {
+	// Fast-fail with a clear reason if the window isn't rendering — otherwise
+	// CaptureScreenshot's callback never fires and we'd block for the full 10s.
+	const notRendering = RenderMonitor.notRenderingReason();
+	if (notRendering !== undefined) return { error: notRendering };
+
 	let contentId: string | undefined;
 
 	CaptureService.CaptureScreenshot((id: string) => {
@@ -82,14 +94,23 @@ function captureScreenshotData(): unknown {
 	while (contentId === undefined) {
 		if (tick() - startTime > 10) {
 			return {
-				error: "Screenshot capture timed out. Ensure the Studio viewport is visible and you are in Edit mode (not Play mode). Known Roblox bug: capture may fail if viewport renders a solid color.",
+				error: "Screenshot capture timed out (CaptureScreenshot callback never fired). The Studio window is likely minimized or occluded — restore it so the viewport renders. (Known Roblox bug: capture can also fail if the viewport renders a solid color.)",
 			};
 		}
 		task.wait(0.1);
 	}
 
+	return { contentId };
+}
+
+// Promotes a CaptureScreenshot content id into an EditableImage and reads its
+// RGBA pixels. MUST run in the edit/plugin context: the running game VM lacks
+// the privilege to create an EditableImage from a temporary texture id (errors
+// "cannot currently create editable image from temporary texture id"), while
+// the edit DM can — even for an id captured in the play client DM.
+function readContentToBase64(contentId: string): unknown {
 	const [editableOk, editableResult] = pcall(() => {
-		return AssetService.CreateEditableImageAsync(Content.fromUri(contentId!));
+		return AssetService.CreateEditableImageAsync(Content.fromUri(contentId));
 	});
 
 	if (!editableOk) {
@@ -118,11 +139,32 @@ function captureScreenshotData(): unknown {
 	return { success: true, width: w, height: h, data: base64Data };
 }
 
+// Edit-mode single shot: capture and read back in the same (edit) context.
+function captureScreenshotData(): unknown {
+	const cap = doCaptureScreenshot();
+	if ("error" in cap) return cap;
+	return readContentToBase64(cap.contentId);
+}
+
 function captureScreenshot(): unknown {
 	return captureScreenshotData();
 }
 
+// Play-mode step 1 (run on the CLIENT): capture only, return the temp id.
+function captureBegin(): unknown {
+	return doCaptureScreenshot();
+}
+
+// Play-mode step 2 (run on EDIT): read pixels from a temp id captured elsewhere.
+function captureRead(requestData: Record<string, unknown>): unknown {
+	const contentId = requestData.contentId as string | undefined;
+	if (!contentId) return { error: "contentId is required" };
+	return readContentToBase64(contentId);
+}
+
 export = {
 	captureScreenshotData,
 	captureScreenshot,
+	captureBegin,
+	captureRead,
 };

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}`);
 		}