sbox-mcp-server 1.9.0 → 1.12.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/assets.js

@@ -76,5 +76,27 @@ export function registerAssetTools(server, bridge) {
             content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
         };
     });
+    // ── copy_asset_with_dependencies ─────────────────────────────────
+    server.tool("copy_asset_with_dependencies", "Copy a project asset and its full dependency closure (via Asset.GetReferences(deep:true)) into a target directory, preserving relative path structure so material references to textures keep resolving. SHADOW GUARD: refuses to write under core engine trees (models/citizen, models/dev, materials/dev, materials/default) -- copying there triggers an infinite asset-recompile loop (BRIDGE_GOTCHAS #5). Cloud/procedural/transient assets are skipped with a reason. Returns { copied:[{from,to}], skipped:[{path,reason}], count, note }.", {
+        sourcePath: z
+            .string()
+            .describe("Absolute path OR project-relative path of the source asset (e.g. 'models/props/crate.vmdl'). Use search_assets to find the exact path."),
+        targetDir: z
+            .string()
+            .optional()
+            .describe("Project-relative destination directory (e.g. 'Assets/library'). Defaults to 'Assets/library'"),
+        overwrite: z
+            .boolean()
+            .optional()
+            .describe("Overwrite existing files at the destination. Defaults to false"),
+    }, async (params) => {
+        const res = await bridge.send("copy_asset_with_dependencies", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
 }
 //# sourceMappingURL=assets.js.map

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,7 +189,127 @@ export function registerGameplayTools(server, bridge) {
             content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
         };
     });
-    // ── create_pickup ─────────────────────────────────────────────────
+    // ── 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_interactable ───────────────────────────────────────────
+    server.tool("create_interactable", "Generate a Component.IPressable interactable: the built-in PlayerController 'use' key drives Press()/Hover()/Blur() with no custom player code. Includes a static OnPressed event, an optional cooldown (TimeUntil), and a private OnPress() extensionpoint for effects. For host-authoritative side-effects call an [Rpc.Host] from OnPress(). The Prompt property is left to your game's HUD. Optionally attached to an existing GameObject by GUID (after a hotload).", {
+        name: z.string().optional().describe("Class name. Defaults to 'Interactable'"),
+        directory: z.string().optional().describe("Subdirectory for the .cs file. Defaults to 'Code'"),
+        prompt: z
+            .string()
+            .optional()
+            .describe("Prompt string shown by the game's HUD when hovering. Defaults to 'Press'"),
+        cooldownSeconds: z
+            .number()
+            .optional()
+            .describe("Seconds before the interactable can be pressed again. 0 = no cooldown. Defaults to 0"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of an existing GameObject to attach the component to (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_interactable", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // -- create_weighted_loot_table ----------------------------------------
+    server.tool("create_weighted_loot_table", "Generate a cumulative-weight random loot picker: parallel Name/Weight lists (inspector-editable), a Roll() method that returns a winning entry name and fires a static OnLoot event, and optional pity (guarantee the last/rarest entry after PityAfter consecutive non-rare rolls). Roll() is host-authoritative -- only call it on the host and replicate the result (clients rolling their own loot is equivalent to clients writing their own money balance). Optionally attached to an existing GameObject by GUID (after a hotload).", {
+        name: z.string().optional().describe("Class name. Defaults to 'LootTable'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the .cs file. Defaults to 'Code'"),
+        entries: z
+            .union([
+            z.array(z.object({ name: z.string(), weight: z.number() })),
+            z.string().describe('Compact "name:weight,name:weight" string, e.g. "common:70,uncommon:25,rare:5"'),
+        ])
+            .optional()
+            .describe("Loot table entries. Defaults to common:70 / uncommon:25 / rare:5"),
+        pity: z
+            .boolean()
+            .optional()
+            .describe("If true, guarantee the last (rarest) entry after PityAfter consecutive non-rare rolls. Defaults to false"),
+        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_weighted_loot_table", 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'"),
         directory: z
@@ -223,5 +350,33 @@ export function registerGameplayTools(server, bridge) {
             content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
         };
     });
+    // -- create_save_system ------------------------------------------------
+    server.tool("create_save_system", "Generate a versioned save-system component: a SaveData POCO with Version bump on schema change, dirty-flag autosave on a TimeUntil timer, clamp-on-load Sanitize() for corrupt/hand-edited saves, and delete-on-version-mismatch to start fresh instead of crashing. Runs only on the owning machine (IsProxy guard). Fires static OnLoaded/OnSaved hooks for HUD and analytics. FileSystem.Data.ReadJsonOrDefault/WriteJson verified live on the current SDK. Optionally attached to an existing GameObject by GUID (after a hotload).", {
+        name: z.string().optional().describe("Class name. Defaults to 'SaveSystem'"),
+        directory: z.string().optional().describe("Subdirectory for the .cs file. Defaults to 'Code'"),
+        fileName: z
+            .string()
+            .optional()
+            .describe("Save file name under FileSystem.Data (e.g. 'save.json'). Defaults to 'save.json'"),
+        version: z
+            .number()
+            .int()
+            .optional()
+            .describe("Schema version embedded in SaveData. Old saves with a different version start fresh. Defaults to 1"),
+        autosaveSeconds: z
+            .number()
+            .optional()
+            .describe("Seconds between autosave ticks (0 disables autosave). Defaults to 10"),
+        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_save_system", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
 }
 //# sourceMappingURL=gameplay.js.map

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

@@ -38,6 +38,30 @@ export function registerInspectionTools(server, bridge) {
             return { content: [{ type: "text", text: `Error: ${res.error}` }] };
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
+    // ── sandbox_lint ──────────────────────────────────────────────────
+    server.tool("sandbox_lint", "Static-scan the project's C# for s&box sandbox whitelist violations BEFORE they cause compile errors: System.MathF (use MathX), System.Math (use MathX), Array.Clone() (use .ToArray()), System.Net / raw sockets (use Sandbox.Http), System.IO.File (use FileSystem.Data), and raw System.Threading.Thread (use async/Task or GameTask). Returns { scanned, findings: [{file, line, match, advice}], clean }. Scope to a subdirectory with the directory param.", {
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory under the project root to scan (e.g. 'Code', 'Code/Player'). Defaults to 'Code'"),
+    }, async (params) => {
+        const res = await bridge.send("sandbox_lint", params);
+        if (!res.success)
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── razor_lint ────────────────────────────────────────────────────
+    server.tool("razor_lint", "Static-scan .razor and .razor.scss files for the silent footguns that crash the Razor transpiler or stylesheet engine with no useful error message: switch expressions inside @code blocks (use if/else instead), non-ASCII/emoji inside @code (move to markup or a string constant), PanelComponent subclasses missing a BuildHash override (panel never re-renders), and root uppercase type-selector rules in .razor.scss (silently skipped -- use a class selector like .my-panel). Returns { scanned, findings: [{file, line, match, advice}], clean } matching the sandbox_lint shape.", {
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory under the project root to scan (e.g. 'UI', 'Code'). Defaults to 'Code'"),
+    }, async (params) => {
+        const res = await bridge.send("razor_lint", params);
+        if (!res.success)
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
     // ── scene_validate ────────────────────────────────────────────────
     server.tool("scene_validate", "Validate the active scene for the silent setup footguns that break controllers/physics/cameras: no CameraComponent, no player controller, multiple root Rigidbodies, a Rigidbody with MotionEnabled=false fighting a kinematic root, IsTrigger colliders that Scene.Trace will ignore, child Rigidbodies breaking collider binding, and missing required child anchors. Returns each issue with the GameObject and the exact fix.", {}, async () => {
         const res = await bridge.send("scene_validate", {});
@@ -87,9 +111,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,55 +1,55 @@
-{
-  "name": "sbox-mcp-server",
-  "version": "1.9.0",
-  "description": "MCP Server for s&box game engine — enables Claude to build games through conversation",
-  "type": "module",
-  "main": "dist/index.js",
-  "bin": {
-    "sbox-mcp-server": "dist/index.js",
-    "sbox-mcp": "dist/index.js"
-  },
-  "files": [
-    "dist/**/*.js",
-    "dist/**/*.d.ts",
-    "README.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "tsc",
-    "test": "npm run build && node --test",
-    "start": "node dist/index.js",
-    "dev": "tsc --watch",
-    "prepublishOnly": "npm run build"
-  },
-  "keywords": [
-    "mcp",
-    "sbox",
-    "s&box",
-    "game-engine",
-    "claude",
-    "ai",
-    "source2",
-    "model-context-protocol"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/LouSputthole/Sbox-Claude.git"
-  },
-  "author": "sboxskins.gg (https://sboxskins.gg)",
-  "homepage": "https://sboxskins.gg",
-  "bugs": {
-    "url": "https://github.com/LouSputthole/Sbox-Claude/issues"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1",
-    "zod": "^3.24.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.7.0"
-  },
-  "engines": {
-    "node": ">=18.0.0"
-  },
-  "license": "AGPL-3.0-or-later"
-}
+{
+  "name": "sbox-mcp-server",
+  "version": "1.12.0",
+  "description": "MCP Server for s&box game engine — enables Claude to build games through conversation",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "sbox-mcp-server": "dist/index.js",
+    "sbox-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "npm run build && node --test",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "sbox",
+    "s&box",
+    "game-engine",
+    "claude",
+    "ai",
+    "source2",
+    "model-context-protocol"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LouSputthole/Sbox-Claude.git"
+  },
+  "author": "sboxskins.gg (https://sboxskins.gg)",
+  "homepage": "https://sboxskins.gg",
+  "bugs": {
+    "url": "https://github.com/LouSputthole/Sbox-Claude/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "AGPL-3.0-or-later"
+}