sbox-mcp-server 1.9.0 → 1.11.0

package/dist/index.js

@@ -44,6 +44,7 @@ import { registerSelfTestTools } from "./tools/selftest.js";
 import { registerGameplayTools } from "./tools/gameplay.js";
 import { registerNpcTools } from "./tools/npc.js";
 import { registerInspectionTools } from "./tools/inspection.js";
+import { registerInputTools } from "./tools/inputs.js";
 // ── CLI flags ──────────────────────────────────────────────────────
 const args = process.argv.slice(2);
 /** Read the package version from package.json, or return "unknown" on failure. */
@@ -191,6 +192,7 @@ registerSelfTestTools(server, bridge);
 registerGameplayTools(server, bridge);
 registerNpcTools(server, bridge);
 registerInspectionTools(server, bridge);
+registerInputTools(server, bridge);
 /** Start the MCP server on stdio and attempt initial Bridge connection. */
 async function main() {
     const transport = new StdioServerTransport();

package/dist/tools/characters.js

@@ -9,17 +9,28 @@ import { z } from "zod";
  * change, take_screenshot and read the result. Animation *playback* is
  * runtime, but poses preview in-editor via PlayAnimationsInEditorScene.
  */
-const ColorSchema = z
-    .object({
+// Colour / vector accepted as EITHER an object OR a comma string, passed
+// through unchanged. The C# handler parses both forms (source of truth). See
+// the cross-language vector/color contract.
+const ColorObject = z.object({
     r: z.number().min(0).describe("Red, 0-1"),
     g: z.number().min(0).describe("Green, 0-1"),
     b: z.number().min(0).describe("Blue, 0-1"),
     a: z.number().min(0).max(1).optional().describe("Alpha, 0-1 (default 1)"),
-})
-    .describe("RGBA colour as 0-1 floats (model tint)");
+});
+const ColorSchema = z
+    .union([
+    ColorObject,
+    z.string().describe('Comma string "r,g,b,a", e.g. "1,0,0,1"'),
+])
+    .describe('RGBA colour — object {r,g,b,a} (0-1) OR comma string "r,g,b,a" (model tint)');
+const Vector3Object = z.object({ x: z.number(), y: z.number(), z: z.number() });
 const Vector3Schema = z
-    .object({ x: z.number(), y: z.number(), z: z.number() })
-    .describe("World position {x,y,z}");
+    .union([
+    Vector3Object,
+    z.string().describe('Comma string "x,y,z", e.g. "0,0,200"'),
+])
+    .describe('World vector — object {x,y,z} OR comma string "x,y,z"');
 const RotationSchema = z
     .object({ pitch: z.number(), yaw: z.number(), roll: z.number() })
     .describe("Rotation {pitch,yaw,roll} in degrees");
@@ -241,8 +252,9 @@ export function registerCharacterTools(server, bridge) {
             z.number(),
             z.boolean(),
             z.object({ x: z.number(), y: z.number(), z: z.number() }),
+            z.string().describe('Vector as a comma string "x,y,z"'),
         ])
-            .describe("Value: number (float), boolean, or {x,y,z} vector"),
+            .describe('Value: number (float), boolean, or a vector as {x,y,z} OR a comma string "x,y,z"'),
         type: z
             .enum(["float", "int", "bool", "vector"])
             .optional()

package/dist/tools/components.js

@@ -74,5 +74,28 @@ export function registerComponentTools(server, bridge) {
             content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
         };
     });
+    // ── invoke_method ────────────────────────────────────────────────
+    server.tool("invoke_method", "Call a public method BY NAME on a component of a live scene GameObject, passing ARGUMENTS. The with-args sibling of invoke_button (which only calls parameterless [Button]/methods on a scene component). Finds a public method matching name + arg-count, coerces each JSON arg to the parameter type (primitives/enums; Color/Vector3 as comma strings '1,0,0,1'; asset refs as a path; GameObject/Component refs as a target GUID), invokes it, and returns the method's return value as a string (null for void). Returns success=false with a clear error on resolve/coerce/throw", {
+        id: z.string().describe("GUID of the GameObject"),
+        component: z
+            .string()
+            .optional()
+            .describe("Component type name to target (e.g. 'Health', 'PlayerController'). Omit to search all components on the object for a method matching name + arg-count"),
+        method: z
+            .string()
+            .describe("Name of the public method to call (e.g. 'TakeDamage', 'AddGold')"),
+        args: z
+            .array(z.unknown())
+            .optional()
+            .describe("Ordered arguments, each coerced to the matching parameter's type. Numbers/bools/strings pass through; Color/Vector3/Rotation as comma strings '1,0,0,1'; enum member names; ASSET refs as a path ('models/dev/box.vmdl'); GameObject/Component refs as a target GUID. Omit (or []) for a no-arg method"),
+    }, async (params) => {
+        const res = await bridge.send("invoke_method", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
 }
 //# sourceMappingURL=components.js.map

package/dist/tools/diagnostics.js

@@ -94,6 +94,15 @@ function tailLines(text, n) {
     const lines = text.split(/\r?\n/);
     return lines.slice(Math.max(0, lines.length - n));
 }
+// A 3D point accepted as EITHER an object {x,y,z} OR a comma string "x,y,z",
+// passed through unchanged. The C# handler parses both forms (source of truth).
+// See the cross-language vector/color contract.
+const Vector3Schema = z
+    .union([
+    z.object({ x: z.number(), y: z.number(), z: z.number() }),
+    z.string().describe('Comma string "x,y,z", e.g. "0,0,200"'),
+])
+    .describe('World point — object {x,y,z} OR comma string "x,y,z"');
 export function registerDiagnosticTools(server, bridge) {
     // ── read_log ───────────────────────────────────────────────────────
     server.tool("read_log", "Read s&box's editor log (sbox-dev.log) so Claude can see compile errors, exceptions, and Log.Info output directly. Reads the log file (not via the bridge), so it works even when the editor has crashed. If auto-detection fails (non-Windows / non-Steam install), set the SBOX_LOG_PATH environment variable to the full log path.", {
@@ -142,7 +151,7 @@ export function registerDiagnosticTools(server, bridge) {
         return { content: [{ type: "text", text: header + out.join("\n") }] };
     });
     // ── get_compile_errors ─────────────────────────────────────────────
-    server.tool("get_compile_errors", "Scan the recent s&box log for compile errors and exceptions — the fast way for Claude to confirm whether its last script/addon edit actually compiled. Reads sbox-dev.log directly (works even if the editor is mid-crash). Returns the matching lines, or an all-clear.", {
+    server.tool("get_compile_errors", "Scan the recent s&box log for compile errors and exceptions — the fast way for Claude to confirm whether its last script/addon edit actually compiled. Reads sbox-dev.log directly (works even if the editor is mid-crash). Filters out the noisy 'Broken Reference: package.local.* (the compiler failed)' cascade (which masks the real cause) and surfaces the underlying '[Generic] Error | ...CSxxxx... file:line' diagnostics. Returns the real error lines, or an all-clear.", {
         lines: z
             .number()
             .int()
@@ -175,9 +184,38 @@ export function registerDiagnosticTools(server, bridge) {
             };
         }
         const recent = tailLines(text, n);
-        const re = /(error CS\d+|Compile of .* Failed|Exception|Couldn't add project|Broken Reference|StackTrace|^\s*at Sandbox\.)/i;
-        const hits = recent.filter((l) => re.test(l));
-        if (hits.length === 0) {
+        // The cascade: when a project's code fails to compile, every dependent
+        // package (including the bridge's own editor assembly) emits a
+        //   "Broken Reference: package.local.<x> (the compiler failed)"
+        // line. There can be dozens of these and they MASK the real diagnostic —
+        // so we drop them and surface the actual CSxxxx / [Generic] Error lines.
+        const cascadeRe = /Broken Reference:.*\(the compiler failed\)/i;
+        // Real compile diagnostics. We accept:
+        //  - any line carrying a C# error code (error CS#### or "CS#### | file:line")
+        //  - the "[Generic] Error | ..." diagnostic lines s&box emits
+        //  - genuine compile-failure / exception markers
+        // Whitelist (always surface, even with NO file path), e.g. a bare
+        // location like "- :352,1" that s&box prints for project-level errors.
+        const realErrorRe = /(error CS\d+|\bCS\d{3,5}\b|\[Generic\]\s*Error|Compile of .* Failed|Couldn't add project|Unhandled [Ee]xception|^\s*at Sandbox\.|StackTrace)/;
+        const noFileWhitelistRe = /^\s*-\s*:\d+,\d+/; // e.g. "- :352,1"
+        const cascadeLines = recent.filter((l) => cascadeRe.test(l));
+        const realHits = recent.filter((l) => !cascadeRe.test(l) && (realErrorRe.test(l) || noFileWhitelistRe.test(l)));
+        if (realHits.length === 0) {
+            if (cascadeLines.length > 0) {
+                // We saw the masking cascade but none of the underlying diagnostics
+                // fell within the scanned window — point Claude at the fuller log.
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Saw ${cascadeLines.length} "Broken Reference: package.local.* (the compiler failed)" cascade line(s), ` +
+                                `but the real compile error isn't in the last ${n} lines (the cascade masks it). ` +
+                                `The underlying CSxxxx / [Generic] Error line is likely just above — call read_log ` +
+                                `with more lines (e.g. lines: 1000) to find it, or get_compile_errors with a larger 'lines'.\n(${path})`,
+                        },
+                    ],
+                };
+            }
             return {
                 content: [
                     {
@@ -187,11 +225,14 @@ export function registerDiagnosticTools(server, bridge) {
                 ],
             };
         }
+        const suffix = cascadeLines.length > 0
+            ? `\n\n(Filtered out ${cascadeLines.length} "Broken Reference … (the compiler failed)" cascade line(s) that mask the real cause.)`
+            : "";
         return {
             content: [
                 {
                     type: "text",
-                    text: `Found ${hits.length} error/exception line(s) in the last ${n} log lines:\n\n${hits.join("\n")}`,
+                    text: `Found ${realHits.length} real error line(s) in the last ${n} log lines:\n\n${realHits.join("\n")}${suffix}`,
                 },
             ],
         };
@@ -199,10 +240,9 @@ export function registerDiagnosticTools(server, bridge) {
     // ── frame_camera ─────────────────────────────────────────────────── (bridge)
     server.tool("frame_camera", "Aim the s&box EDITOR viewport camera at a GameObject (by id) or a world point (position + optional radius), then call take_screenshot to capture that view. This is how Claude points its own screenshots at what it's working on — frame a spawned object, then screenshot to verify it actually looks right.", {
         id: z.string().optional().describe("GUID of a GameObject to frame on"),
-        position: z
-            .object({ x: z.number(), y: z.number(), z: z.number() })
+        position: Vector3Schema
             .optional()
-            .describe("World point to frame on (use instead of id)"),
+            .describe('World point to frame on (use instead of id) — object {x,y,z} or comma string "x,y,z"'),
         radius: z
             .number()
             .optional()
@@ -219,14 +259,12 @@ export function registerDiagnosticTools(server, bridge) {
     // ── screenshot_from ──────────────────────────────────────────────── (bridge)
     server.tool("screenshot_from", "Take a screenshot from a chosen angle. take_screenshot is locked to the scene's main camera; this temporarily moves that camera to frame your target, captures, then restores it — so Claude can finally AIM its own screenshots. Pass id (frame an object) OR position {x,y,z} with optional lookAt {x,y,z} or rotation {pitch,yaw,roll}. After it returns, read the newest PNG in the editor's screenshots folder.", {
         id: z.string().optional().describe("GUID of a GameObject to frame"),
-        position: z
-            .object({ x: z.number(), y: z.number(), z: z.number() })
+        position: Vector3Schema
             .optional()
-            .describe("Camera world position (use instead of id)"),
-        lookAt: z
-            .object({ x: z.number(), y: z.number(), z: z.number() })
+            .describe('Camera world position (use instead of id) — object {x,y,z} or comma string "x,y,z"'),
+        lookAt: Vector3Schema
             .optional()
-            .describe("World point to look at (pair with position)"),
+            .describe('World point to look at (pair with position) — object {x,y,z} or comma string "x,y,z"'),
         rotation: z
             .object({ pitch: z.number(), yaw: z.number(), roll: z.number() })
             .optional()
@@ -458,14 +496,12 @@ export function registerDiagnosticTools(server, bridge) {
     // ── capture_view ──────────────────────────────────────────────────── (bridge, Batch 34)
     server.tool("capture_view", "Capture a PNG of the scene from a camera — and crucially this WORKS IN PLAY MODE, capturing the RUNNING game (via CameraComponent.RenderToBitmap, unlike take_screenshot/screenshot_from which are edit-only). With no args it renders the live main camera = the player's POV (incl. HUD). Pass position {x,y,z} (+ lookAt or rotation) or id (a GameObject to frame) to capture from a temporary camera that never disturbs the game's own camera. Returns the saved PNG's absolute 'path' — READ it to see the result.", {
         id: z.string().optional().describe("GUID of a GameObject to frame (uses a temp camera)"),
-        position: z
-            .object({ x: z.number(), y: z.number(), z: z.number() })
+        position: Vector3Schema
             .optional()
-            .describe("Camera world position (temp camera; use instead of id)"),
-        lookAt: z
-            .object({ x: z.number(), y: z.number(), z: z.number() })
+            .describe('Camera world position (temp camera; use instead of id) — object {x,y,z} or comma string "x,y,z"'),
+        lookAt: Vector3Schema
             .optional()
-            .describe("World point to look at (pair with position)"),
+            .describe('World point to look at (pair with position) — object {x,y,z} or comma string "x,y,z"'),
         rotation: z
             .object({ pitch: z.number(), yaw: z.number(), roll: z.number() })
             .optional()

package/dist/tools/gameobjects.js

@@ -9,13 +9,21 @@ import { z } from "zod";
  * Uses shared Zod schemas (Vector3Schema, RotationSchema) for consistent
  * Vector3 and Rotation parameter validation across multiple tools.
  */
-const Vector3Schema = z
-    .object({
+// A 3D vector accepted as EITHER an object {x,y,z} OR a comma string "x,y,z".
+// The value is passed through to the bridge unchanged; the C# handler parses
+// both forms (C# is the source of truth for parsing). See the cross-language
+// vector/color contract.
+const Vector3Object = z.object({
     x: z.number().describe("X coordinate"),
     y: z.number().describe("Y coordinate"),
     z: z.number().describe("Z coordinate"),
-})
-    .describe("3D vector with x, y, z components");
+});
+const Vector3Schema = z
+    .union([
+    Vector3Object,
+    z.string().describe('Comma string "x,y,z", e.g. "0,0,200"'),
+])
+    .describe('3D vector — object {x,y,z} OR comma string "x,y,z"');
 const RotationSchema = z
     .object({
     pitch: z.number().describe("Pitch angle in degrees"),
@@ -35,7 +43,7 @@ export function registerGameObjectTools(server, bridge) {
         scale: z
             .union([z.number(), Vector3Schema])
             .optional()
-            .describe("Uniform scale (number) or per-axis scale (Vector3)"),
+            .describe('Uniform scale (number) or per-axis scale — object {x,y,z} or comma string "x,y,z"'),
         parent: z
             .string()
             .optional()
@@ -126,7 +134,7 @@ export function registerGameObjectTools(server, bridge) {
         scale: z
             .union([z.number(), Vector3Schema])
             .optional()
-            .describe("New scale — uniform number or per-axis Vector3"),
+            .describe('New scale — uniform number, per-axis object {x,y,z}, or comma string "x,y,z"'),
         local: z
             .boolean()
             .optional()

package/dist/tools/gameplay.js

@@ -14,13 +14,20 @@ import { z } from "zod";
  * The `sbox-scaffold-game` skill orchestrates these into a playable starter.
  * All scene/file-mutating; refused during play mode by the bridge dispatch.
  */
-const Vector3Schema = z
-    .object({
+// A 3D vector accepted as EITHER an object {x,y,z} OR a comma string "x,y,z",
+// passed through unchanged. The C# handler parses both forms (source of truth).
+// See the cross-language vector/color contract.
+const Vector3Object = z.object({
     x: z.number().describe("X coordinate"),
     y: z.number().describe("Y coordinate"),
     z: z.number().describe("Z coordinate"),
-})
-    .describe("3D vector with x, y, z components");
+});
+const Vector3Schema = z
+    .union([
+    Vector3Object,
+    z.string().describe('Comma string "x,y,z", e.g. "0,0,200"'),
+])
+    .describe('3D vector — object {x,y,z} OR comma string "x,y,z"');
 const RotationSchema = z
     .object({
     pitch: z.number().describe("Pitch angle in degrees"),
@@ -182,6 +189,74 @@ export function registerGameplayTools(server, bridge) {
             content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
         };
     });
+    // ── create_economy_wallet ─────────────────────────────────────────
+    server.tool("create_economy_wallet", "Generate a host-authoritative currency Wallet component: a [Sync(SyncFlags.FromHost)] Money balance (only the host can write it — plain [Sync] money is the classic economy exploit) with AddMoney / TrySpend / SetMoney / CanAfford and an OnMoneyChanged event. Single-player safe. Optionally attached to an existing GameObject by GUID (after a hotload). Pairs with a save system for persistence. Mined from the most-requested currency pattern across 51 games.", {
+        name: z.string().optional().describe("Class name. Defaults to 'Wallet'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the .cs file. Defaults to 'Code'"),
+        startingMoney: z
+            .number()
+            .int()
+            .optional()
+            .describe("Initial balance the host seeds on start. Defaults to 0"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of an existing GameObject to attach the Wallet to (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_economy_wallet", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── create_round_phase_machine ────────────────────────────────────
+    server.tool("create_round_phase_machine", "Generate a host-authoritative round/phase machine: a [Sync(SyncFlags.FromHost)] CurrentPhase cycled through your named phases on a per-phase timer (host-only), with a static OnPhaseChanged event that fires on every machine. Great for round/match flow, match phases, or a day/night cycle. Single-player safe. Optionally attached to an existing GameObject by GUID (after a hotload). Mined from the round-flow pattern across the 51 games.", {
+        name: z.string().optional().describe("Class name. Defaults to 'GameDirector'"),
+        directory: z.string().optional().describe("Subdirectory for the .cs file. Defaults to 'Code'"),
+        phases: z
+            .array(z.string())
+            .optional()
+            .describe('Ordered phase names (become an enum), e.g. ["Lobby","Day","Night","Payout"]. Defaults to ["Lobby","Active","Ended"]'),
+        duration: z
+            .number()
+            .optional()
+            .describe("Default seconds per phase (each phase also gets its own tunable [Property]). Defaults to 60"),
+        loop: z
+            .boolean()
+            .optional()
+            .describe("Loop back to the first phase after the last (true) or hold on the last phase (false). Defaults to true"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of an existing GameObject to attach to (only if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_round_phase_machine", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── create_day_night_clock ────────────────────────────────────────
+    server.tool("create_day_night_clock", "Generate a host-authoritative time-of-day clock: [Sync(SyncFlags.FromHost)] TimeOfDay (0–24) + Day advancing by Time.Delta, IsDay/IsNight from sunrise/sunset hours, and static OnNewDay / OnDayNightChanged events to drive lighting, NPC schedules, or spawns. Single-player safe. Pairs with create_round_phase_machine. Optionally attached to a GameObject by GUID (after a hotload).", {
+        name: z.string().optional().describe("Class name. Defaults to 'DayNightClock'"),
+        directory: z.string().optional().describe("Subdirectory for the .cs file. Defaults to 'Code'"),
+        dayLengthSeconds: z.number().optional().describe("Real seconds per in-game day. Defaults to 600 (10 min)"),
+        startHour: z.number().optional().describe("Hour the clock starts at (0–24). Defaults to 8"),
+        sunriseHour: z.number().optional().describe("Hour day begins. Defaults to 6"),
+        sunsetHour: z.number().optional().describe("Hour night begins. Defaults to 20"),
+        targetId: z.string().optional().describe("GUID of an existing GameObject to attach to (hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_day_night_clock", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
     // ── create_pickup ─────────────────────────────────────────────────
     server.tool("create_pickup", "Generate a trigger-based collectible component. On enter by a tagged object it raises OnCollected (wire it to your objective/score system) and despawns. Optionally builds a visible pickup GameObject with a trigger SphereCollider (+ a model) in one call", {
         name: z.string().optional().describe("Class name. Defaults to 'Pickup'"),

package/dist/tools/inputs.d.ts

@@ -0,0 +1,18 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Input action tools — register the custom named verbs a scaffolded game needs.
+ *
+ * s&box stores input actions in the project's `.sbproj` under
+ * `Metadata.InputSettings.Actions[]` (each: { Name, KeyboardCode, GamepadCode?,
+ * GroupName }). A game that defines NO actions is handed a default set by the
+ * engine (Forward/Back/Left/Right/Jump/Use/...). The catch: the moment a game
+ * writes its own InputSettings block, that block becomes the authoritative
+ * full list — so the handler seeds the full default set when none exists, then
+ * appends the custom action, so movement/use survive.
+ *
+ *   ensure_input_action — add a named action (e.g. "interact") if missing so
+ *                         Input.Pressed("interact") actually fires in play mode.
+ */
+export declare function registerInputTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=inputs.d.ts.map

package/dist/tools/inputs.js

@@ -0,0 +1,44 @@
+import { z } from "zod";
+/**
+ * Input action tools — register the custom named verbs a scaffolded game needs.
+ *
+ * s&box stores input actions in the project's `.sbproj` under
+ * `Metadata.InputSettings.Actions[]` (each: { Name, KeyboardCode, GamepadCode?,
+ * GroupName }). A game that defines NO actions is handed a default set by the
+ * engine (Forward/Back/Left/Right/Jump/Use/...). The catch: the moment a game
+ * writes its own InputSettings block, that block becomes the authoritative
+ * full list — so the handler seeds the full default set when none exists, then
+ * appends the custom action, so movement/use survive.
+ *
+ *   ensure_input_action — add a named action (e.g. "interact") if missing so
+ *                         Input.Pressed("interact") actually fires in play mode.
+ */
+export function registerInputTools(server, bridge) {
+    // ── ensure_input_action ───────────────────────────────────────────
+    server.tool("ensure_input_action", 'Register a custom named INPUT ACTION in the project so a generated game\'s custom verbs work in play mode. Writes to <project>.sbproj → Metadata.InputSettings.Actions[]. Idempotent: if the action already exists it is left alone (pass update=true to rebind its key). If the project has no InputSettings yet, the full DEFAULT action set (Forward/Back/Left/Right/Jump/Use/attack1/...) is seeded first so player movement/use are preserved — the engine only auto-injects defaults when a game defines NONE. After adding, call it from game code with Input.Pressed("name") / Input.Down("name") / Input.Released("name"). Note: input config is read at project load, so restart_editor (or reload the project) for a new action to take effect in play mode.', {
+        name: z
+            .string()
+            .describe('The action verb game code will call, e.g. "interact", "sprint", "drop". Matches Input.Pressed("interact").'),
+        keyboardKey: z
+            .string()
+            .optional()
+            .describe('Default keyboard binding, e.g. "e", "f", "space", "mouse1", "shift". Omit to add the action with no default key (player can bind it).'),
+        group: z
+            .string()
+            .optional()
+            .describe('UI group the action is listed under in the bindings menu (e.g. "Actions", "Movement", "Other"). Defaults to "Actions".'),
+        update: z
+            .boolean()
+            .optional()
+            .describe("If the action already exists, rebind its keyboardKey to the provided value instead of leaving it untouched. Default false (idempotent no-op when present)."),
+    }, async (params) => {
+        const res = await bridge.send("ensure_input_action", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=inputs.js.map

package/dist/tools/inspection.js

@@ -87,9 +87,12 @@ export function registerInspectionTools(server, bridge) {
             .default("press")
             .describe("press = one tick (Pressed); hold = held for durationMs; release = clear a held action"),
         analogMove: z
-            .object({ x: z.number(), y: z.number(), z: z.number().default(0) })
+            .union([
+            z.object({ x: z.number(), y: z.number(), z: z.number().default(0) }),
+            z.string().describe('Comma string "x,y,z", e.g. "1,0,0"'),
+        ])
             .optional()
-            .describe("AnalogMove vector to apply (forward/left)"),
+            .describe('AnalogMove vector to apply (forward/left) — object {x,y,z} or comma string "x,y,z"'),
         analogLook: z
             .object({ pitch: z.number(), yaw: z.number(), roll: z.number().default(0) })
             .optional()

package/dist/tools/leveltools.js

@@ -4,9 +4,28 @@ import { z } from "zod";
  * grid-duplicate, and measure. Transform-level operations for arranging a
  * scene — all verifiable via the editor (screenshot or hierarchy/state).
  */
+// Vector / colour accepted as EITHER an object OR a comma string, passed
+// through unchanged. The C# handler parses both forms (source of truth). See
+// the cross-language vector/color contract.
+const Vector3Object = z.object({ x: z.number(), y: z.number(), z: z.number() });
 const Vector3Schema = z
-    .object({ x: z.number(), y: z.number(), z: z.number() })
-    .describe("Vector {x,y,z}");
+    .union([
+    Vector3Object,
+    z.string().describe('Comma string "x,y,z", e.g. "100,100,100"'),
+])
+    .describe('Vector — object {x,y,z} OR comma string "x,y,z"');
+const ColorObject = z.object({
+    r: z.number().min(0),
+    g: z.number().min(0),
+    b: z.number().min(0),
+    a: z.number().min(0).max(1).optional(),
+});
+const ColorSchema = z
+    .union([
+    ColorObject,
+    z.string().describe('Comma string "r,g,b,a", e.g. "1,0,0,1"'),
+])
+    .describe('RGBA colour — object {r,g,b,a} (0-1) OR comma string "r,g,b,a"');
 export function registerLevelTools(server, bridge) {
     // ── snap_to_ground ─────────────────────────────────────────────────
     server.tool("snap_to_ground", "Drop a GameObject straight down onto the surface below it (physics raycast). Works best on collider-less props (an object with its own collider may self-hit). Optional offset lifts it off the surface.", {
@@ -94,15 +113,9 @@ export function registerLevelTools(server, bridge) {
         snapToGround: z.boolean().optional().describe("Raycast each onto the surface below (default true)"),
         scaleMin: z.number().optional().describe("Min uniform scale (default 1)"),
         scaleMax: z.number().optional().describe("Max uniform scale (default 1; set >min for size variation)"),
-        tint: z
-            .object({
-            r: z.number().min(0),
-            g: z.number().min(0),
-            b: z.number().min(0),
-            a: z.number().min(0).max(1).optional(),
-        })
+        tint: ColorSchema
             .optional()
-            .describe("Tint applied to every copy"),
+            .describe('Tint applied to every copy — object {r,g,b,a} or comma string "r,g,b,a"'),
         seed: z.number().int().optional().describe("PRNG seed for a reproducible layout (default 1)"),
         group: z.boolean().optional().describe("Parent all copies under one group object (default true)"),
         name: z.string().optional().describe("Base name for the props/group (default 'Prop')"),

package/dist/tools/npc.js

@@ -16,13 +16,19 @@ import { z } from "zod";
  * Mirrors the templates.ts / navigation.ts module shape: zod params, one
  * bridge.send per tool, JSON.stringify(res.data) on success.
  */
+// A world-space Vector3 accepted as EITHER an object {x,y,z} OR a comma string
+// "x,y,z", passed through unchanged. The C# handler parses both forms (source of
+// truth). See the cross-language vector/color contract.
 const Vec3 = z
-    .object({
-    x: z.number().describe("X"),
-    y: z.number().describe("Y"),
-    z: z.number().describe("Z"),
-})
-    .describe("A world-space Vector3");
+    .union([
+    z.object({
+        x: z.number().describe("X"),
+        y: z.number().describe("Y"),
+        z: z.number().describe("Z"),
+    }),
+    z.string().describe('Comma string "x,y,z", e.g. "0,0,200"'),
+])
+    .describe('A world-space Vector3 — object {x,y,z} OR comma string "x,y,z"');
 export function registerNpcTools(server, bridge) {
     // ── create_npc_brain ──────────────────────────────────────────────
     server.tool("create_npc_brain", "Generate an NpcBrain Component: a behavior state machine (Idle/Patrol/Wander/Chase/Search/Flee/Ambush) driven by occlusion-aware perception — FOV cone + sight range + a line-of-sight trace (respects walls/trees) + proximity hearing — with last-known-position memory (lose-LOS -> search -> give up -> resume). This is the decision layer on top of bake_navmesh / NavMeshAgent movement. Pick a behavior preset, then tune via the generated [Property] fields with set_property. After generating: trigger_hotload + get_compile_errors, place a route with place_patrol_route + assign_patrol_route, bake_navmesh, and verify perception in EDIT mode with simulate_npc_perception (chase/search behavior needs play mode). The component is added to a GameObject like any other; it auto-adds a NavMeshAgent in OnStart.", {

package/dist/tools/objecttools.js

@@ -5,14 +5,22 @@ import { z } from "zod";
  * the composable workhorse — query GUIDs, then feed them to align/distribute/
  * set_tint/group/etc.
  */
-const ColorSchema = z
-    .object({
+// A colour accepted as EITHER an object {r,g,b,a} OR a comma string "r,g,b,a".
+// The value is passed through to the bridge unchanged; the C# handler parses
+// both forms (C# is the source of truth). See the cross-language vector/color
+// contract.
+const ColorObject = z.object({
     r: z.number().min(0).describe("Red, 0-1"),
     g: z.number().min(0).describe("Green, 0-1"),
     b: z.number().min(0).describe("Blue, 0-1"),
     a: z.number().min(0).max(1).optional().describe("Alpha, 0-1 (default 1)"),
-})
-    .describe("RGBA colour as 0-1 floats");
+});
+const ColorSchema = z
+    .union([
+    ColorObject,
+    z.string().describe('Comma string "r,g,b,a", e.g. "1,0,0,1"'),
+])
+    .describe('RGBA colour — object {r,g,b,a} (0-1) OR comma string "r,g,b,a"');
 export function registerObjectTools(server, bridge) {
     // ── find_objects ───────────────────────────────────────────────────
     server.tool("find_objects", "Query the scene for GameObjects by name (case-insensitive substring), component type name, and/or tag — combine filters (AND). Returns {id,name} for matches (limit default 50, max 500). Read-only; works during play. Use it to get GUIDs to feed into align/distribute/set_tint/group/delete/etc.", {
@@ -33,12 +41,24 @@ export function registerObjectTools(server, bridge) {
         };
     });
     // ── set_tint ───────────────────────────────────────────────────────
-    server.tool("set_tint", "Set the renderer tint colour on one object (id) or many (ids) at once. Works on any ModelRenderer/SkinnedModelRenderer.", {
+    server.tool("set_tint", 'Set the renderer tint colour on one object (id) or many (ids) at once. Works on any ModelRenderer/SkinnedModelRenderer. Pass the colour as "tint" (or its alias "color"); each accepts an object {r,g,b,a} OR a comma string "r,g,b,a".', {
         id: z.string().optional().describe("Single GameObject GUID"),
         ids: z.array(z.string()).optional().describe("Multiple GameObject GUIDs"),
-        tint: ColorSchema.describe("Tint colour to apply"),
+        tint: ColorSchema.optional().describe("Tint colour to apply (object or comma string)"),
+        color: ColorSchema.optional().describe('Alias for "tint" (object or comma string)'),
     }, async (params) => {
-        const res = await bridge.send("set_tint", params);
+        // "color" is an accepted alias for "tint"; normalize to "tint" and pass
+        // the value through unchanged (C# parses object-or-string).
+        const { color, tint, ...rest } = params;
+        const tintValue = tint ?? color;
+        if (tintValue === undefined) {
+            return {
+                content: [
+                    { type: "text", text: 'Error: provide "tint" (or its alias "color").' },
+                ],
+            };
+        }
+        const res = await bridge.send("set_tint", { ...rest, tint: tintValue });
         if (!res.success) {
             return { content: [{ type: "text", text: `Error: ${res.error}` }] };
         }

package/dist/tools/physics.d.ts

@@ -1,8 +1,4 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { BridgeClient } from "../transport/bridge-client.js";
-/**
- * Physics tools: add_physics, add_collider, add_joint, raycast.
- * Manages rigidbodies, colliders, physics constraints, and ray tracing.
- */
 export declare function registerPhysicsTools(server: McpServer, bridge: BridgeClient): void;
 //# sourceMappingURL=physics.d.ts.map

package/dist/tools/physics.js

@@ -3,6 +3,15 @@ import { z } from "zod";
  * Physics tools: add_physics, add_collider, add_joint, raycast.
  * Manages rigidbodies, colliders, physics constraints, and ray tracing.
  */
+// A 3D vector accepted as EITHER an object {x,y,z} OR a comma string "x,y,z",
+// passed through unchanged. The C# handler parses both forms (source of truth).
+// See the cross-language vector/color contract.
+const Vector3Schema = z
+    .union([
+    z.object({ x: z.number(), y: z.number(), z: z.number() }),
+    z.string().describe('Comma string "x,y,z", e.g. "0,0,200"'),
+])
+    .describe('3D vector — object {x,y,z} OR comma string "x,y,z"');
 export function registerPhysicsTools(server, bridge) {
     // ── add_physics ───────────────────────────────────────────────────
     server.tool("add_physics", "Add a Rigidbody and collider to a GameObject, making it a dynamic physics object. Auto-selects BoxCollider if no collider type specified", {
@@ -38,10 +47,9 @@ export function registerPhysicsTools(server, bridge) {
             .boolean()
             .optional()
             .describe("If true, the collider acts as a trigger (no physics collision). Defaults to false"),
-        size: z
-            .object({ x: z.number(), y: z.number(), z: z.number() })
+        size: Vector3Schema
             .optional()
-            .describe("Size for BoxCollider (x, y, z dimensions)"),
+            .describe('Size for BoxCollider (x, y, z dimensions) — object {x,y,z} or comma string "x,y,z"'),
         radius: z
             .number()
             .optional()
@@ -90,15 +98,12 @@ export function registerPhysicsTools(server, bridge) {
     });
     // ── raycast ───────────────────────────────────────────────────────
     server.tool("raycast", "Perform a physics raycast (Scene.Trace.Ray) and return hit results. Useful for line-of-sight checks, object placement, and collision detection", {
-        start: z
-            .object({ x: z.number(), y: z.number(), z: z.number() })
-            .describe("Ray start position (world space)"),
-        end: z
-            .object({ x: z.number(), y: z.number(), z: z.number() })
+        start: Vector3Schema
+            .describe('Ray start position (world space) — object {x,y,z} or comma string "x,y,z"'),
+        end: Vector3Schema
             .optional()
             .describe("Ray end position. Use either end or direction+maxDistance"),
-        direction: z
-            .object({ x: z.number(), y: z.number(), z: z.number() })
+        direction: Vector3Schema
             .optional()
             .describe("Ray direction (normalized). Used with maxDistance instead of end"),
         maxDistance: z
@@ -128,15 +133,13 @@ export function registerPhysicsTools(server, bridge) {
     });
     // ── physics_overlap ───────────────────────────────────────────────
     server.tool("physics_overlap", "Spatial volume query: return the GameObjects whose colliders intersect a SPHERE (center + radius) or a BOX (center + size) — the volume counterpart to raycast's ray. Use it for 'what's near this point' / 'what's inside this trigger volume' checks (proximity, blast radius, spawn-clearance). Read-only.", {
-        center: z
-            .object({ x: z.number(), y: z.number(), z: z.number() })
-            .describe("Center of the query volume (world space)"),
+        center: Vector3Schema
+            .describe('Center of the query volume (world space) — object {x,y,z} or comma string "x,y,z"'),
         radius: z
             .number()
             .optional()
             .describe("Sphere radius. Provide this OR size (box), not both"),
-        size: z
-            .object({ x: z.number(), y: z.number(), z: z.number() })
+        size: Vector3Schema
             .optional()
             .describe("Full box size (not half-extents). Provide this OR radius"),
     }, async (params) => {

package/dist/tools/playmode.js

@@ -121,5 +121,84 @@ export function registerPlayModeTools(server, bridge) {
             content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
         };
     });
+    // ── drive_player (EXPERIMENTAL) ──────────────────────────────────
+    server.tool("drive_player", "EXPERIMENTAL — Drive the active PlayerController DURING PLAY MODE across multiple frames: synthesize sustained look (EyeAngles), analog movement (wish velocity), and/or hold a named action down long enough that Input.Pressed fires its rising edge. This is the reliable alternative to simulate_input, which only sets an action for ONE frame and so MISSES edge-triggered controls (Input.Pressed) and cannot inject analog move/look at all. Requires start_play first. Runs ASYNC across editor frames and returns immediately — the job keeps applying for `frames` (or `durationMs`) frames. After it runs, confirm with drive_player_status, then verify the actual effect with capture_view / get_runtime_property. Provide at least one of look / lookDelta / move / action.", {
+        id: z
+            .string()
+            .optional()
+            .describe("GUID of the GameObject holding the controller. Omit to auto-resolve the first PlayerController (or *Controller with EyeAngles/WishVelocity) in the play scene"),
+        component: z
+            .string()
+            .optional()
+            .describe("Controller component type name to target (e.g. 'PlayerController'). Omit to auto-detect"),
+        frames: z
+            .number()
+            .int()
+            .optional()
+            .describe("How many editor frames to drive for (1–1800, ~60/sec). Default 30 (~0.5s). Takes precedence over durationMs"),
+        durationMs: z
+            .number()
+            .int()
+            .optional()
+            .describe("Duration in ms, converted at ~60fps (ignored if `frames` is given). Default ~500ms"),
+        look: z
+            .union([
+            z.object({
+                pitch: z.number().default(0),
+                yaw: z.number().default(0),
+                roll: z.number().default(0),
+            }),
+            z.array(z.number()),
+            z.string(),
+        ])
+            .optional()
+            .describe("Absolute EyeAngles target {pitch,yaw,roll} held for the whole duration (aim the camera/body). Object, [pitch,yaw,roll], or 'pitch,yaw,roll'. pitch is clamped to ±89"),
+        lookDelta: z
+            .union([
+            z.object({
+                pitch: z.number().default(0),
+                yaw: z.number().default(0),
+                roll: z.number().default(0),
+            }),
+            z.array(z.number()),
+            z.string(),
+        ])
+            .optional()
+            .describe("Per-frame EyeAngles delta added each frame (turn/pan over time, e.g. {yaw:2} to sweep right). Combine with `frames` to control total rotation"),
+        move: z
+            .union([
+            z.object({ x: z.number().default(0), y: z.number().default(0) }),
+            z.array(z.number()),
+            z.string(),
+        ])
+            .optional()
+            .describe("Analog movement in the controller's facing frame: x = forward(+)/back(-), y = left(+)/right(-). Magnitude clamped to 1. e.g. {x:1} walks forward for the whole duration"),
+        moveSpeed: z
+            .number()
+            .optional()
+            .describe("Units/sec used when synthesizing WishVelocity from `move` (default 160). Ignored if the controller exposes its own AnalogMove field"),
+        action: z
+            .string()
+            .optional()
+            .describe("A named input action ('jump','use','attack1',…) HELD DOWN every frame for the whole duration, so Input.Pressed catches the edge single-frame simulate_input misses. Auto-released on the final frame"),
+    }, async (params) => {
+        const res = await bridge.send("drive_player", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── drive_player_status (EXPERIMENTAL) ───────────────────────────
+    server.tool("drive_player_status", "EXPERIMENTAL — Read the result of the most recently FINISHED drive_player job: which controller members were actually written (EyeAngles / WishVelocity / AnalogMove…), how many frames applied, and why it ended. Because drive_player runs across frames and returns immediately, this is how you confirm it took effect. Returns lastResult=null if no job has finished yet.", {}, async () => {
+        const res = await bridge.send("drive_player_status");
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
 }
 //# sourceMappingURL=playmode.js.map

package/dist/tools/prefabs.js

@@ -25,13 +25,16 @@ export function registerPrefabTools(server, bridge) {
             .string()
             .describe("Path to the .prefab file (e.g. 'prefabs/enemies/grunt.prefab')"),
         position: z
-            .object({
-            x: z.number(),
-            y: z.number(),
-            z: z.number(),
-        })
+            .union([
+            z.object({
+                x: z.number(),
+                y: z.number(),
+                z: z.number(),
+            }),
+            z.string().describe('Comma string "x,y,z", e.g. "0,0,64"'),
+        ])
             .optional()
-            .describe("World position to spawn at. Defaults to origin"),
+            .describe('World position to spawn at — object {x,y,z} or comma string "x,y,z". Defaults to origin'),
         rotation: z
             .object({
             pitch: z.number(),

package/dist/tools/templates.js

@@ -42,9 +42,12 @@ export function registerTemplateTools(server, bridge) {
             .optional()
             .describe("When placeInScene is true, also create a Camera (FP/TP: child at eye/boom offset; top_down: fixed overhead). Defaults to true."),
         spawnPosition: z
-            .object({ x: z.number(), y: z.number(), z: z.number() })
+            .union([
+            z.object({ x: z.number(), y: z.number(), z: z.number() }),
+            z.string().describe('Comma string "x,y,z", e.g. "0,0,64"'),
+        ])
             .optional()
-            .describe("When placeInScene is true, the world position to spawn the player rig at. Defaults to the origin."),
+            .describe('When placeInScene is true, the world position to spawn the player rig at — object {x,y,z} or comma string "x,y,z". Defaults to the origin.'),
     }, async (params) => {
         const res = await bridge.send("create_player_controller", params);
         if (!res.success) {

package/dist/tools/ui.js

@@ -76,9 +76,12 @@ export function registerUITools(server, bridge) {
             .optional()
             .describe("Name for the UI GameObject. Defaults to 'World UI'"),
         position: z
-            .object({ x: z.number(), y: z.number(), z: z.number() })
+            .union([
+            z.object({ x: z.number(), y: z.number(), z: z.number() }),
+            z.string().describe('Comma string "x,y,z", e.g. "0,0,64"'),
+        ])
             .optional()
-            .describe("World position for the panel"),
+            .describe('World position for the panel — object {x,y,z} or comma string "x,y,z"'),
         rotation: z
             .object({
             pitch: z.number(),

package/dist/tools/visuals.js

@@ -8,17 +8,28 @@ import { z } from "zod";
  * (which can't even set a Color). After any change, screenshot the scene and read
  * the result — this layer is where the screenshot loop matters most.
  */
-const ColorSchema = z
-    .object({
+// Colour / vector accepted as EITHER an object OR a comma string, passed
+// through unchanged. The C# handler parses both forms (source of truth). See
+// the cross-language vector/color contract.
+const ColorObject = z.object({
     r: z.number().min(0).describe("Red, 0-1"),
     g: z.number().min(0).describe("Green, 0-1"),
     b: z.number().min(0).describe("Blue, 0-1"),
     a: z.number().min(0).max(1).optional().describe("Alpha, 0-1 (default 1)"),
-})
-    .describe("RGBA colour as 0-1 floats");
+});
+const ColorSchema = z
+    .union([
+    ColorObject,
+    z.string().describe('Comma string "r,g,b,a", e.g. "1,0,0,1"'),
+])
+    .describe('RGBA colour — object {r,g,b,a} (0-1) OR comma string "r,g,b,a"');
+const Vector3Object = z.object({ x: z.number(), y: z.number(), z: z.number() });
 const Vector3Schema = z
-    .object({ x: z.number(), y: z.number(), z: z.number() })
-    .describe("World position {x,y,z}");
+    .union([
+    Vector3Object,
+    z.string().describe('Comma string "x,y,z", e.g. "0,0,200"'),
+])
+    .describe('World position — object {x,y,z} OR comma string "x,y,z"');
 const RotationSchema = z
     .object({ pitch: z.number(), yaw: z.number(), roll: z.number() })
     .describe("Rotation {pitch,yaw,roll} in degrees");
@@ -81,10 +92,9 @@ export function registerVisualTools(server, bridge) {
         heightWidth: z.number().optional().describe("cubemap: height-fog band width"),
         heightExponent: z.number().optional().describe("cubemap: height-fog falloff exponent"),
         strength: z.number().optional().describe("volumetric: fog density/strength"),
-        size: z
-            .object({ x: z.number(), y: z.number(), z: z.number() })
+        size: Vector3Schema
             .optional()
-            .describe("volumetric: bounds size (units) centred on the object"),
+            .describe('volumetric: bounds size (units) centred on the object — object {x,y,z} or comma string "x,y,z"'),
     }, async (params) => {
         const res = await bridge.send("set_fog", params);
         if (!res.success) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sbox-mcp-server",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "MCP Server for s&box game engine — enables Claude to build games through conversation",
   "type": "module",
   "main": "dist/index.js",