@el4cteo/rbx-studio-mcp 0.1.0

package/dist/tools/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../../src/tools/debug.ts"],"names":[],"mappings":"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"}

package/dist/tools/device.js

@@ -0,0 +1,74 @@
+import { z } from "zod";
+import { json, table, text } from "../lib/format.js";
+import { defineTool } from "../lib/tool.js";
+export function registerDeviceTools(context) {
+    const { bridge } = context;
+    defineTool(context, {
+        name: "device",
+        title: "Emulate a phone, tablet or console",
+        description: "Resizes the Studio viewport to a real device, so you can see what a " +
+            "player on that device sees.\n\n" +
+            "Most Roblox players are on a phone and most UI is built on a desktop " +
+            "monitor, which is where interfaces break: a button under the notch, a " +
+            "menu off the bottom of a 393-pixel-tall screen, text sized for a " +
+            "display three times larger. None of that is visible in the data model " +
+            "— every one of those instances has perfectly correct properties — so " +
+            "this is the only way to find it short of owning the hardware.\n\n" +
+            "The workflow is: `set` a device, `screenshot`, look. Pair it with " +
+            "`playtest` to check a running game's HUD rather than the editor.\n\n" +
+            "`list` gives the ids, each with its real name, form factor and " +
+            "resolution — ids look like \"iphone_16\", \"ipad_a16\", " +
+            "\"samsung_galaxy_s25_ultra\", \"xbox\", \"meta_quest_3\".\n\n" +
+            "`stop` returns Studio to the normal editor viewport. Do that when you " +
+            "are finished: a left-over emulated device makes every later screenshot " +
+            "the wrong shape, and nothing on screen obviously says why.",
+        inputSchema: {
+            op: z
+                .enum(["list", "set", "stop", "state"])
+                .default("state")
+                .describe("'list' shows the available devices, 'set' switches to one, 'stop' " +
+                "returns to the normal viewport, 'state' only reports."),
+            device: z
+                .string()
+                .optional()
+                .describe('set only: the device id, e.g. "iphone_16". See `list`.'),
+            orientation: z
+                .enum(["LandscapeLeft", "LandscapeRight", "Portrait", "Sensor"])
+                .optional()
+                .describe("set only: which way up. Portrait is worth testing separately — " +
+                "most mobile players hold the phone upright and most UI is only " +
+                "ever checked in landscape."),
+            form: z
+                .enum(["Phone", "Tablet", "Console", "Desktop", "VR"])
+                .optional()
+                .describe("list only: show only devices of this form factor."),
+            studioId: z.string().optional().describe("Target Studio; omit for the active one."),
+        },
+        readOnly: false,
+        destructive: false,
+    }, async (args) => {
+        if (args.op === "list") {
+            const response = await bridge.call("device.list", {}, 
+            // One GetDeviceInfoAsync per device, and there are around forty.
+            { studioId: args.studioId, timeoutMs: 45_000 });
+            const rows = response.devices.filter((entry) => args.form === undefined || entry.form === args.form);
+            if (rows.length === 0) {
+                return text(`No ${args.form} devices are available. Studio offers ${response.count} in total; ` +
+                    "call again without `form` to see them.");
+            }
+            return table(["id", "name", "form", "resolution"], rows, {
+                more: `${rows.length} of ${response.count} devices; ` +
+                    `currently ${JSON.stringify(response.current["device"] ?? "default")}`,
+            });
+        }
+        if (args.op === "set" && (args.device === undefined || args.device === "")) {
+            return text('set needs a `device` id. Call `device op="list"` to see them.');
+        }
+        const command = args.op === "set" ? "device.set" : args.op === "stop" ? "device.stop" : "device.state";
+        const response = await bridge.call(command, { device: args.device, orientation: args.orientation }, { studioId: args.studioId, timeoutMs: 30_000 });
+        return json(response, args.op === "set"
+            ? "Take a `screenshot` to see it. Call `device op=\"stop\"` when finished, or every later screenshot stays this shape."
+            : undefined);
+    });
+}
+//# sourceMappingURL=device.js.map

package/dist/tools/device.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device.js","sourceRoot":"","sources":["../../src/tools/device.ts"],"names":[],"mappings":"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"}

package/dist/tools/discover.js

@@ -0,0 +1,217 @@
+import { z } from "zod";
+import { propertiesOf, standardProperties } from "../lib/apidump.js";
+import { cursorSchema, decodeCursor, detailSchema, encodeCursor, json, limitSchema, table, text, } from "../lib/format.js";
+import { defineTool } from "../lib/tool.js";
+/**
+ * Renders a hierarchy page as a table. `concise` drops the child count, which
+ * is the only column a pure scan does not need.
+ */
+function pageOf(response, detail, more) {
+    const columns = detail === "concise" ? ["path", "className"] : ["path", "className", "childCount"];
+    const nextOffset = response.offset + response.items.length;
+    return table(columns, response.items, {
+        total: response.total,
+        ...(nextOffset < response.total ? { nextCursor: encodeCursor(nextOffset) } : {}),
+        ...(more ? { more } : {}),
+    });
+}
+/**
+ * Sorts property and attribute keys alphabetically.
+ *
+ * Luau table iteration order is unspecified, so the same instance inspected
+ * twice comes back with its keys shuffled. That defeats prompt caching, makes
+ * two inspects impossible to diff, and reads as though something changed when
+ * nothing did.
+ */
+function withSortedProperties(item) {
+    const sortKeys = (record) => record
+        ? Object.fromEntries(Object.entries(record).sort(([a], [b]) => a.localeCompare(b)))
+        : undefined;
+    // `requested` exists so callers can correlate an answer with the path they
+    // asked about; it is redundant next to the canonical path and only costs
+    // tokens here.
+    const { requested: _requested, ...rest } = item;
+    return {
+        ...rest,
+        properties: sortKeys(item.properties) ?? {},
+        ...(item.attributes ? { attributes: sortKeys(item.attributes) } : {}),
+    };
+}
+export function registerDiscoverTools(context) {
+    const { bridge } = context;
+    defineTool(context, {
+        name: "tree",
+        title: "Browse hierarchy",
+        description: "Lists the instance hierarchy under a path, breadth-first to a given depth. " +
+            "Returns a flat array of paths — flat is both cheaper and easier to act on " +
+            "than nested JSON, since every entry is directly usable as a path.\n\n" +
+            "Use this to orient yourself in an unfamiliar place. Use `find` instead " +
+            "when you already know what you are looking for; a deep `tree` over a " +
+            "whole place wastes context on instances you will never touch.\n\n" +
+            "With `path` omitted it lists only the containers a place is authored in " +
+            "— Workspace, ReplicatedStorage, ServerScriptService and friends. Roblox " +
+            "exposes ~120 services at the root, almost all engine internals; those are " +
+            "hidden and the response says how many. Pass an explicit `path` to look " +
+            "inside one of them anyway.",
+        inputSchema: {
+            path: z
+                .string()
+                .optional()
+                .describe('Dot-notation root, e.g. "Workspace.Map". Omit to list services from the root.'),
+            depth: z
+                .number()
+                .int()
+                .min(1)
+                .max(10)
+                .default(2)
+                .describe("Levels below `path` to walk. Keep low; each level multiplies the result."),
+            className: z
+                .string()
+                .optional()
+                .describe('Only include instances of this class or a subclass, e.g. "BasePart".'),
+            nameContains: z
+                .string()
+                .optional()
+                .describe("Only include instances whose name contains this text (case-insensitive)."),
+            detail: detailSchema,
+            limit: limitSchema,
+            cursor: cursorSchema,
+            studioId: z.string().optional().describe("Target Studio; omit for the active one."),
+        },
+        readOnly: true,
+    }, async (args) => {
+        const response = await bridge.call("discover.tree", {
+            path: args.path,
+            depth: args.depth,
+            className: args.className,
+            nameContains: args.nameContains,
+            limit: args.limit,
+            offset: decodeCursor(args.cursor),
+        }, { studioId: args.studioId });
+        // Say what was withheld at the root, so an agent that genuinely needs an
+        // engine service knows it can ask for one by path.
+        const hidden = response.hiddenServices ?? 0;
+        return pageOf(response, args.detail, hidden > 0
+            ? `${hidden} engine services hidden — pass an explicit \`path\` to inspect one`
+            : undefined);
+    });
+    defineTool(context, {
+        name: "inspect",
+        title: "Inspect instances",
+        description: "Reads properties, attributes, tags and children of one or more instances. " +
+            "Pass every path you care about in a single call — batching costs one " +
+            "round trip instead of N.\n\n" +
+            "Property selection comes from the live Roblox API dump for each " +
+            "instance's actual class, so it stays correct across engine updates:\n" +
+            "  concise  — class and child count only\n" +
+            "  standard — the properties that characterise the class (Part gets Size, " +
+            "Position, CFrame, Anchored, Material...)\n" +
+            "  full     — every readable property; expensive, use on one or two " +
+            "instances at most\n\n" +
+            "Bad paths do not fail the call: they come back under `failures` while the " +
+            "valid ones still return, so one typo does not cost you the whole batch.",
+        inputSchema: {
+            paths: z
+                .array(z.string())
+                .min(1)
+                .max(50)
+                .describe('Instance paths, e.g. ["Workspace.Baseplate", "Lighting"].'),
+            detail: detailSchema,
+            properties: z
+                .array(z.string())
+                .optional()
+                .describe("Read exactly these properties instead of the detail-level default. " +
+                "Use when you want one specific value across many instances."),
+            includeChildren: z
+                .boolean()
+                .default(true)
+                .describe("Include a name/class listing of direct children."),
+            studioId: z.string().optional().describe("Target Studio; omit for the active one."),
+        },
+        readOnly: true,
+    }, async (args) => {
+        // Classes are not known until the plugin answers, so resolve the property
+        // set in two passes: a cheap probe for class names, then the real read.
+        let requested = args.properties;
+        if (!requested && args.detail !== "concise") {
+            const probe = await bridge.call("discover.inspect", { paths: args.paths, includeChildren: false }, { studioId: args.studioId });
+            const names = new Set();
+            for (const item of probe.items) {
+                const list = args.detail === "full"
+                    ? (await propertiesOf(item.className)).map((property) => property.name)
+                    : await standardProperties(item.className);
+                for (const name of list)
+                    names.add(name);
+            }
+            requested = [...names];
+        }
+        const response = await bridge.call("discover.inspect", {
+            paths: args.paths,
+            properties: requested,
+            includeChildren: args.includeChildren,
+        }, { studioId: args.studioId });
+        const note = response.failures.length > 0
+            ? `Could not resolve ${response.failures.length} path(s):\n` +
+                response.failures.map((failure) => `  - ${failure}`).join("\n")
+            : undefined;
+        return json(response.items.map(withSortedProperties), note);
+    });
+    defineTool(context, {
+        name: "find",
+        title: "Find instances",
+        description: "Searches the data model by name, class, property value and/or tag. Every " +
+            "filter you supply must match, so one call answers questions that would " +
+            'otherwise take several: "anchored BaseParts under Workspace.Map whose ' +
+            'name contains door" is a single request.\n\n' +
+            "This replaces separate name / class / property / tag search tools. " +
+            "Prefer it over `tree` whenever you know what you are looking for.\n\n" +
+            "Tag searches are answered from CollectionService's index rather than by " +
+            "walking the tree, so they stay fast on large places. Narrow with `path` " +
+            "if a search reports TOO_BROAD.",
+        inputSchema: {
+            path: z
+                .string()
+                .optional()
+                .describe('Limit the search to this subtree, e.g. "Workspace.Map". Omit for everything.'),
+            nameContains: z.string().optional().describe("Substring of the instance name, case-insensitive."),
+            className: z.string().optional().describe('Class or superclass, e.g. "BasePart", "Script".'),
+            tag: z.string().optional().describe("CollectionService tag the instance must carry."),
+            propertyName: z
+                .string()
+                .optional()
+                .describe('Property that must exist, e.g. "Anchored". Combine with propertyValue.'),
+            propertyValue: z
+                .string()
+                .optional()
+                .describe('Required value of `propertyName`, compared as text — "true", "0, 5, 0", ' +
+                '"Enum.Material.Neon". Omit to match any instance that has the property.'),
+            detail: detailSchema,
+            limit: limitSchema,
+            cursor: cursorSchema,
+            studioId: z.string().optional().describe("Target Studio; omit for the active one."),
+        },
+        readOnly: true,
+    }, async (args) => {
+        if (!args.nameContains && !args.className && !args.tag && !args.propertyName) {
+            return text("find needs at least one filter (nameContains, className, tag or propertyName).\n" +
+                "To list everything under a path, use `tree` instead.");
+        }
+        const response = await bridge.call("discover.find", {
+            path: args.path,
+            nameContains: args.nameContains,
+            className: args.className,
+            tag: args.tag,
+            propertyName: args.propertyName,
+            propertyValue: args.propertyValue,
+            limit: args.limit,
+            offset: decodeCursor(args.cursor),
+        }, { studioId: args.studioId, timeoutMs: 30_000 });
+        if (response.total === 0) {
+            return text(`No matches (searched ${response.searched ?? 0} instances).\n` +
+                "Check spelling and case — names and class names are case-sensitive. " +
+                "Try a shorter `nameContains`, or drop a filter to widen the search.");
+        }
+        return pageOf(response, args.detail, `searched ${response.searched ?? 0} instances`);
+    });
+}
+//# sourceMappingURL=discover.js.map

package/dist/tools/discover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discover.js","sourceRoot":"","sources":["../../src/tools/discover.ts"],"names":[],"mappings":"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"}

package/dist/tools/exec.js

@@ -0,0 +1,191 @@
+import { z } from "zod";
+import { json, table, text } from "../lib/format.js";
+import { defineTool } from "../lib/tool.js";
+export function registerExecTools(context) {
+    const { bridge } = context;
+    defineTool(context, {
+        name: "execute_luau",
+        title: "Run Luau in Studio",
+        description: "Runs Luau in Studio's plugin context and returns whatever it printed, " +
+            "returned, or threw.\n\n" +
+            "This is the escape hatch. Reach for it only when no dedicated tool " +
+            "fits — `create`, `modify`, `delete`, `move`, `script_edit` and `find` " +
+            "validate their input, type values from the live API dump, and wrap " +
+            "writes in an undo recording. Code run here does none of that, so a typo " +
+            "becomes a runtime error instead of a suggestion, and changes it makes " +
+            "may not be undoable as one step.\n\n" +
+            "Good uses: reading something no tool exposes, a one-off calculation " +
+            "over many instances, or calling an engine API the tools do not cover.\n\n" +
+            "Output printed while it runs is captured and returned, so `print` is a " +
+            "reasonable way to get values out. `return` works too, including " +
+            "returning a table — it comes back as a structure, not a summary. There " +
+            "is no timeout: an infinite loop will hang Studio until it is " +
+            "force-quit.\n\n" +
+            "Against a running playtest server, Studio disables `loadstring`, so the " +
+            "code is compiled through a ModuleScript instead and runs at script " +
+            "identity — plugin-only APIs are unavailable there. When that happens it " +
+            "is stated in the result rather than left to be inferred from a failure.",
+        inputSchema: {
+            source: z
+                .string()
+                .min(1)
+                .describe("Luau to run. In an editor session this has plugin permissions, so " +
+                "`game`, `workspace` and plugin-only APIs are all reachable."),
+            studioId: z.string().optional().describe("Target Studio; omit for the active one."),
+        },
+        destructive: true,
+    }, async (args) => {
+        const response = await bridge.call("exec.run", { source: args.source }, { studioId: args.studioId, timeoutMs: 60_000 });
+        const parts = [];
+        if (response.output.length > 0) {
+            parts.push("Output:\n" +
+                response.output.map((line) => `  [${line.level}] ${line.message}`).join("\n"));
+        }
+        if (response.ok) {
+            if (response.returned && response.returned.length > 0) {
+                // Indented, because returned values are now whole structures rather
+                // than one-line summaries and a single-line dump of a nested table is
+                // no more readable than the "<table with 5 entries>" it replaced.
+                const single = response.returned.length === 1 ? response.returned[0] : response.returned;
+                parts.push(`Returned:\n${JSON.stringify(single, null, 2)}`);
+            }
+            if (parts.length === 0) {
+                parts.push("Ran successfully. Nothing was printed or returned.");
+            }
+        }
+        else {
+            // A thrown error is reported as content rather than a tool failure: the
+            // output captured before the throw is usually what explains it.
+            parts.push(`Error: ${response.error ?? "unknown"}`);
+        }
+        if (response.note)
+            parts.push(`Note: ${response.note}`);
+        parts.push(`(${response.milliseconds}ms)`);
+        return text(parts.join("\n\n"));
+    });
+    defineTool(context, {
+        name: "viewport",
+        title: "Viewport and selection",
+        description: "Works with the 3D view and the Studio selection.\n\n" +
+            "`select` sets, extends or shrinks what is highlighted in Studio. Select " +
+            "what you just built or changed — it shows the user the result, and puts " +
+            "the instance under Studio's own move and scale handles. `studio_status` " +
+            "reports the current selection; this sets it.\n\n" +
+            "`focus` aims the Studio camera at an instance and frames it so the " +
+            "whole thing is on screen. This is what makes `screenshot` worth having: " +
+            "a picture of wherever the camera happened to be answers nothing, while " +
+            "a picture of the thing you just built answers 'does it look right', " +
+            "which no amount of reading properties can. Build, focus, screenshot.\n\n" +
+            "The distance is computed from the subject's size and the camera's field " +
+            "of view, so a doorway and a whole map both arrive filling a similar " +
+            "share of the frame. `from` changes the angle you view it from, and " +
+            "`padding` how tightly it is framed.\n\n" +
+            "`camera` sets or reads the camera directly, for shots framing cannot " +
+            "express — standing inside a room, or looking along a corridor.\n\n" +
+            "`raycast` fires a ray through the world and reports the first thing it " +
+            "hits, with position, surface normal, distance and material. This answers " +
+            "'what occupies this space', which the data model alone cannot: use it to " +
+            "find the ground under a spawn point, or check whether a gap is clear " +
+            "before placing something.",
+        inputSchema: {
+            op: z
+                .enum(["select", "raycast", "focus", "camera"])
+                .describe("'focus' points the camera at something and frames it, 'camera' sets " +
+                "it explicitly, 'select' changes the Studio selection, 'raycast' " +
+                "queries the world."),
+            path: z
+                .string()
+                .optional()
+                .describe("focus only: the instance to look at. A model, part, or folder containing them."),
+            at: z
+                .string()
+                .optional()
+                .describe('focus only: look at this point instead of an instance, e.g. "0, 10, 0".'),
+            from: z
+                .string()
+                .optional()
+                .describe('focus only: direction to view from, e.g. "0, 1, 0" for directly above ' +
+                'or "1, 0, 0" from the side. Defaults to a raised three-quarter view.'),
+            padding: z
+                .number()
+                .min(1)
+                .max(5)
+                .default(1.5)
+                .describe("focus only: how much room to leave around the subject. 1 is tight."),
+            position: z.string().optional().describe('camera only: where to put the camera, e.g. "0, 20, 30".'),
+            lookAt: z.string().optional().describe("camera only: the point to aim at."),
+            fieldOfView: z
+                .number()
+                .min(1)
+                .max(120)
+                .optional()
+                .describe("camera only: field of view in degrees. Lower is more zoomed in."),
+            paths: z
+                .array(z.string())
+                .optional()
+                .describe("select only: instances to select. An empty array clears the selection."),
+            mode: z
+                .enum(["set", "add", "remove"])
+                .default("set")
+                .describe("select only: replace the selection, extend it, or remove from it."),
+            origin: z
+                .string()
+                .optional()
+                .describe('raycast only: where the ray starts, e.g. "0, 50, 0".'),
+            direction: z
+                .string()
+                .optional()
+                .describe('raycast only: which way it points, e.g. "0, -1, 0" for straight down.'),
+            maxDistance: z
+                .number()
+                .positive()
+                .default(1000)
+                .describe("raycast only: how far to look, in studs."),
+            ignore: z
+                .array(z.string())
+                .optional()
+                .describe("raycast only: instances the ray passes through."),
+            studioId: z.string().optional().describe("Target Studio; omit for the active one."),
+        },
+        destructive: false,
+        idempotent: true,
+    }, async (args) => {
+        if (args.op === "focus") {
+            if (!args.path && !args.at) {
+                return text("focus needs a `path` to look at, or an `at` position.");
+            }
+            const response = await bridge.call("viewport.focus", { path: args.path, at: args.at, from: args.from, padding: args.padding }, { studioId: args.studioId });
+            return json(response, "Take a `screenshot` to see it.");
+        }
+        if (args.op === "camera") {
+            const response = await bridge.call("viewport.camera", { position: args.position, lookAt: args.lookAt, fieldOfView: args.fieldOfView }, { studioId: args.studioId });
+            return json(response);
+        }
+        if (args.op === "raycast") {
+            if (!args.origin || !args.direction) {
+                return text("raycast needs `origin` and `direction`.\n" +
+                    'For example origin "0, 100, 0" and direction "0, -1, 0" to find the ' +
+                    "ground below a point.");
+            }
+            const response = await bridge.call("viewport.raycast", {
+                origin: args.origin,
+                direction: args.direction,
+                maxDistance: args.maxDistance,
+                ignore: args.ignore,
+            }, { studioId: args.studioId });
+            if (!response.hit) {
+                return text(`Nothing within ${args.maxDistance} studs along that ray.\n` +
+                    "Check the direction points the way you expect, or raise `maxDistance`.");
+            }
+            return json(response);
+        }
+        const response = await bridge.call("viewport.select", { paths: args.paths ?? [], mode: args.mode }, { studioId: args.studioId });
+        if (response.count === 0)
+            return text("Selection cleared.");
+        return table(["path", "className"], response.items, {
+            total: response.count,
+            more: `${response.count} selected in Studio`,
+        });
+    });
+}
+//# sourceMappingURL=exec.js.map

package/dist/tools/exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec.js","sourceRoot":"","sources":["../../src/tools/exec.ts"],"names":[],"mappings":"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"}

package/dist/tools/input.js

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { json } from "../lib/format.js";
+import { defineTool } from "../lib/tool.js";
+export function registerInputTools(context) {
+    const { bridge } = context;
+    defineTool(context, {
+        name: "input",
+        title: "Send keyboard and mouse input",
+        description: "Sends real keyboard and mouse input to a running playtest — the same " +
+            "events a person pressing the keys would produce.\n\n" +
+            "This is how to test what `character` cannot reach. `character` drives " +
+            "the Humanoid directly, which answers 'can it get to the door'; this " +
+            "answers 'does pressing E open it', 'does the sprint key work', 'does " +
+            "the menu close on Escape' — anything bound to input rather than to " +
+            "movement. Use `character` for going places and this for controls.\n\n" +
+            "Steps run in order, so a sequence is one call: tap E, wait, click at a " +
+            "point, type a name. `hold` is how long a key or button stays down, " +
+            "`after` is how long to wait before the next step — a jump held for a " +
+            "second is a different test from a tapped one.\n\n" +
+            "REQUIRES A RUNNING PLAYTEST, and must be addressed to the playtest's " +
+            "studioId from `list_studios`, not the editor's.\n\n" +
+            "How it works, because it explains the one thing that will surprise " +
+            "you: input belongs to the data model that creates it, and the " +
+            "character is driven by the CLIENT. Sending from the playtest's server " +
+            "succeeds and moves nothing. So this parents a short script into the " +
+            "player's PlayerGui, which runs on their client, and that reports back " +
+            "when the input has actually been delivered. Nothing is reported as " +
+            "sent until the client confirms it. If confirmation never arrives you " +
+            "get an error, not a success — check where things really are with " +
+            "`character op=\"state\"`.\n\n" +
+            "Mouse coordinates are viewport pixels from the top-left, so pair this " +
+            "with `screenshot` to see what is where before clicking it.",
+        inputSchema: {
+            steps: z
+                .array(z
+                .object({
+                kind: z
+                    .enum(["key", "click", "move", "text"])
+                    .default("key")
+                    .describe("'key' presses a keyboard key, 'click' a mouse button at a " +
+                    "point, 'move' just moves the pointer, 'text' types a string."),
+                key: z
+                    .string()
+                    .optional()
+                    .describe('key only: an Enum.KeyCode name — "W", "Space", "E", "LeftShift", "Escape".'),
+                action: z
+                    .enum(["tap", "press", "release"])
+                    .optional()
+                    .describe("'tap' presses and releases (the default), 'press' holds it " +
+                    "down until a later 'release', 'release' lets go. Use " +
+                    "press/release across steps to hold a key while doing " +
+                    "something else."),
+                button: z
+                    .enum(["MouseButton1", "MouseButton2", "MouseButton3"])
+                    .optional()
+                    .describe("click only: which button. Defaults to left."),
+                x: z.number().optional().describe("click/move only: viewport pixels from the left."),
+                y: z.number().optional().describe("click/move only: viewport pixels from the top."),
+                text: z.string().optional().describe("text only: the string to type."),
+                hold: z
+                    .number()
+                    .min(0)
+                    .max(10)
+                    .optional()
+                    .describe("Seconds to hold the key or button down before releasing it."),
+                after: z
+                    .number()
+                    .min(0)
+                    .max(10)
+                    .optional()
+                    .describe("Seconds to wait after this step before the next one."),
+            })
+                .strict())
+                .min(1)
+                .max(40)
+                .describe("Input steps, delivered in order."),
+            player: z
+                .string()
+                .optional()
+                .describe("Which player, by name. Omit for the only one; needed in a multiplayer test."),
+            studioId: z
+                .string()
+                .optional()
+                .describe("The PLAYTEST session's id — not the editor's. See list_studios."),
+        },
+        readOnly: false,
+        destructive: false,
+    }, async (args) => {
+        const response = await bridge.call("input.send", { steps: args.steps, player: args.player }, 
+        // The plugin waits for the client's acknowledgement, and the steps
+        // themselves can hold keys for seconds, so the deadline must outlast both.
+        { studioId: args.studioId, timeoutMs: 90_000 });
+        return json(response, "Delivered on the client and confirmed back. Read the result with `character op=\"state\"`, `console`, or `screenshot`.");
+    });
+}
+//# sourceMappingURL=input.js.map

package/dist/tools/input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.js","sourceRoot":"","sources":["../../src/tools/input.ts"],"names":[],"mappings":"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"}