sbox-mcp-server 1.5.1 → 1.6.0

package/README.md

@@ -1,6 +1,6 @@
 # sbox-mcp-server
 
-MCP Server for the s&box game engine. Lets Claude Code build s&box games through conversation — **150 tools / 142 editor handlers** for scenes, scripts, GameObjects, components, assets, materials, audio, physics, UI, networking, publishing, world-gen, lighting & atmosphere, characters, scene layout, navmesh & spatial queries, particles, self-diagnosis, console/C# execution, live docs search, and type discovery.
+MCP Server for the s&box game engine. Lets Claude Code build s&box games through conversation — **150+ tools** for scenes, scripts, GameObjects, components, assets, materials, audio, physics, UI, networking, publishing, world-gen, lighting & atmosphere, characters, scene layout, navmesh & spatial queries, particles, self-diagnosis, console/C# execution, live docs search, and type discovery.
 
 ## Fastest install — the Claude Code plugin
 
@@ -44,7 +44,7 @@ Open your project. The bridge starts automatically. Verify with:
 Check the bridge status.
 ```
 
-You should see `connected: true, handlerCount: 142`. (That's the editor-side handler count; the server exposes 150 tools total — a handful run MCP-server-side and need no editor handler.)
+You should see `connected: true` with a healthy `handlerCount`. (That's the editor-side handler count; the server exposes a few more tools total — a handful run MCP-server-side and need no editor handler.)
 
 ## How it works
 
@@ -54,9 +54,9 @@ Claude Code → (stdio) → sbox-mcp-server → (file IPC) → bridge addon →
 
 Communication uses file-based IPC through `%TEMP%/sbox-bridge-ipc/`. The MCP server writes request JSON files, the bridge addon (running inside s&box) polls and processes on the main editor thread, then writes response files back. WebSocket is not used — s&box's sandboxed C# environment blocks `System.Net`.
 
-## Tools (150 / 142 editor handlers — v1.5.0)
+## Tools (v1.5.2)
 
-`get_bridge_status` reports `handlerCount: 142` — that's the C# handlers compiled inside the editor. Six tools run **MCP-server-side** and need no editor handler: `read_log`, `get_compile_errors`, `execute_csharp`, `search_docs`, `get_doc_page`, `list_doc_categories`. They read the log / hotload-eval / fetch docs directly, so they keep working even when the editor has crashed or stalled.
+`get_bridge_status` reports the `handlerCount` — that's the C# handlers compiled inside the editor. Six tools run **MCP-server-side** and need no editor handler: `read_log`, `get_compile_errors`, `execute_csharp`, `search_docs`, `get_doc_page`, `list_doc_categories`. They read the log / hotload-eval / fetch docs directly, so they keep working even when the editor has crashed or stalled.
 
 | Category | Tools |
 |----------|-------|

package/dist/tools/characters.js

@@ -205,5 +205,56 @@ export function registerCharacterTools(server, bridge) {
             content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
         };
     });
+    // ── list_animations ───────────────────────────────────────────────── (Batch 33)
+    server.tool("list_animations", "List the animation sequences available on a GameObject's SkinnedModelRenderer (a spawned Citizen or animated model), plus whether it's driven by an AnimationGraph. Call this before play_animation or set_animgraph_param to see valid names.", {
+        id: z.string().describe("GUID of the GameObject with a SkinnedModelRenderer"),
+    }, async (params) => {
+        const res = await bridge.send("list_animations", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── play_animation ─────────────────────────────────────────────────
+    server.tool("play_animation", "Play a named animation sequence on a GameObject's SkinnedModelRenderer (sets the Sequence). Best for models with raw sequences; for AnimationGraph characters (Citizen) prefer set_animgraph_param. The renderer needs PlayAnimationsInEditorScene = true to animate in-editor — then screenshot to verify. Use list_animations for valid names.", {
+        id: z.string().describe("GUID of the GameObject with a SkinnedModelRenderer"),
+        animation: z.string().describe("Sequence name to play (see list_animations)"),
+        looping: z.boolean().optional().describe("Loop the sequence (default: the model's setting)"),
+        speed: z.number().optional().describe("Playback rate multiplier (default 1)"),
+    }, async (params) => {
+        const res = await bridge.send("play_animation", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── set_animgraph_param ────────────────────────────────────────────
+    server.tool("set_animgraph_param", "Set an AnimationGraph parameter on a GameObject's SkinnedModelRenderer (calls Set). This drives Citizen/animgraph motion — e.g. 'move_x'/'move_y' (float), 'b_grounded'/'b_ducked' (bool), or a Vector3. Pose previews in-editor when PlayAnimationsInEditorScene is on; screenshot to verify. Param names are defined by the model's animation graph.", {
+        id: z.string().describe("GUID of the GameObject with a SkinnedModelRenderer"),
+        param: z.string().describe("Animgraph parameter name, e.g. 'move_x', 'b_grounded'"),
+        value: z
+            .union([
+            z.number(),
+            z.boolean(),
+            z.object({ x: z.number(), y: z.number(), z: z.number() }),
+        ])
+            .describe("Value: number (float), boolean, or {x,y,z} vector"),
+        type: z
+            .enum(["float", "int", "bool", "vector"])
+            .optional()
+            .describe("Force the parameter type (default: inferred from value)"),
+    }, async (params) => {
+        const res = await bridge.send("set_animgraph_param", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
 }
 //# sourceMappingURL=characters.js.map

package/dist/tools/diagnostics.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
-import { existsSync, readFileSync, statSync } from "fs";
-import { join } from "path";
+import { existsSync, readFileSync, statSync, readdirSync } from "fs";
+import { join, dirname } from "path";
 /**
  * Diagnostic tools (Batch 24 — "let Claude see its own errors"): read s&box's
  * editor log so Claude can check compile errors, exceptions, and Log.Info
@@ -60,6 +60,36 @@ function locateSboxLog() {
     }
     return { path: null, tried };
 }
+/**
+ * Derive the editor's screenshots folder from the located log path
+ * (<sbox>/logs/sbox-dev.log → <sbox>/screenshots). SBOX_SCREENSHOTS_DIR overrides.
+ */
+function locateScreenshotsDir() {
+    if (process.env.SBOX_SCREENSHOTS_DIR)
+        return process.env.SBOX_SCREENSHOTS_DIR;
+    const { path } = locateSboxLog();
+    if (!path)
+        return null;
+    return join(dirname(dirname(path)), "screenshots");
+}
+/** Newest .png in a dir with mtime strictly greater than afterMs, or null. */
+function newestPng(dir, afterMs) {
+    try {
+        let best = null;
+        for (const f of readdirSync(dir)) {
+            if (!f.toLowerCase().endsWith(".png"))
+                continue;
+            const fp = join(dir, f);
+            const m = statSync(fp).mtimeMs;
+            if (m > afterMs && (!best || m > best.mtimeMs))
+                best = { path: fp, mtimeMs: m };
+        }
+        return best;
+    }
+    catch {
+        return null;
+    }
+}
 function tailLines(text, n) {
     const lines = text.split(/\r?\n/);
     return lines.slice(Math.max(0, lines.length - n));
@@ -321,5 +351,109 @@ export function registerDiagnosticTools(server, bridge) {
             ],
         };
     });
+    // ── get_bounds ─────────────────────────────────────────────────────── (bridge, Batch 33)
+    server.tool("get_bounds", "Get a GameObject's world-space bounding box — center, size, extents, mins/maxs, and a radius. Useful for placing/framing objects and sizing camera moves. Reads GameObject.GetBounds(); objects with no renderer report empty:true with their world position.", {
+        id: z.string().describe("GUID of the GameObject to measure"),
+    }, async (params) => {
+        const res = await bridge.send("get_bounds", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── screenshot_orbit ──────────────────────────────────────────────── (orchestrated, Batch 33)
+    server.tool("screenshot_orbit", "Capture a GameObject from several angles in ONE call — orbits the scene's main camera around the object and screenshots each angle, so Claude can verify 3D work from multiple sides instead of guessing from one. Drives get_bounds (framing) + screenshot_from per angle (each its own frame, the reliable capture path). Returns the saved PNG paths in order — READ them to inspect.", {
+        id: z.string().describe("GUID of the GameObject to orbit"),
+        shots: z
+            .number()
+            .int()
+            .optional()
+            .describe("Number of angles around the object (default 4, clamped 2-8)"),
+        elevation: z
+            .number()
+            .optional()
+            .describe("Camera height factor: 0 = level, 1 = high (default 0.4)"),
+        distance: z
+            .number()
+            .optional()
+            .describe("Camera distance in units (default: auto from bounds)"),
+        width: z.number().int().optional().describe("Screenshot width (default 1280)"),
+        height: z.number().int().optional().describe("Screenshot height (default 720)"),
+    }, async (params) => {
+        const b = await bridge.send("get_bounds", { id: params.id });
+        if (!b.success) {
+            return { content: [{ type: "text", text: `Error (get_bounds): ${b.error}` }] };
+        }
+        const data = b.data;
+        const c = data.center;
+        const sizeLen = Math.hypot(data.size.x, data.size.y, data.size.z);
+        const dist = params.distance ?? Math.max(sizeLen * 1.6, 150);
+        let shots = params.shots ?? 4;
+        shots = Math.max(2, Math.min(8, shots));
+        const elev = params.elevation ?? 0.4;
+        const w = params.width ?? 1280;
+        const h = params.height ?? 720;
+        const ssDir = locateScreenshotsDir();
+        let lastMtime = 0;
+        if (ssDir) {
+            const n = newestPng(ssDir, 0);
+            if (n)
+                lastMtime = n.mtimeMs;
+        }
+        const results = [];
+        for (let i = 0; i < shots; i++) {
+            // s&box names screenshots at 1-second granularity, so two shots in the
+            // same wall-clock second overwrite each other. Space them out.
+            if (i > 0)
+                await new Promise((res) => setTimeout(res, 1100));
+            const ang = (2 * Math.PI * i) / shots;
+            const dx = Math.cos(ang);
+            const dy = Math.sin(ang);
+            const len = Math.hypot(dx, dy, elev) || 1;
+            const camPos = {
+                x: c.x + (dx / len) * dist,
+                y: c.y + (dy / len) * dist,
+                z: c.z + (elev / len) * dist,
+            };
+            const deg = Math.round((ang * 180) / Math.PI);
+            const r = await bridge.send("screenshot_from", {
+                position: camPos,
+                lookAt: c,
+                width: w,
+                height: h,
+            });
+            if (!r.success) {
+                results.push({ angle: deg, error: r.error });
+                continue;
+            }
+            let file = null;
+            if (ssDir) {
+                const started = Date.now();
+                while (Date.now() - started < 4000) {
+                    const n = newestPng(ssDir, lastMtime);
+                    if (n) {
+                        file = n.path;
+                        lastMtime = n.mtimeMs;
+                        break;
+                    }
+                    await new Promise((res) => setTimeout(res, 200));
+                }
+            }
+            results.push({ angle: deg, position: camPos, file });
+        }
+        const files = results
+            .filter((s) => typeof s.file === "string")
+            .map((s) => s.file);
+        const summary = {
+            orbited: data.name ?? params.id,
+            center: c,
+            distance: Math.round(dist),
+            shots: results,
+            note: ssDir
+                ? `Captured ${files.length}/${shots} angle(s). READ these PNGs to inspect the object from each side:\n${files.join("\n")}`
+                : `Captured ${shots} angle(s), but couldn't locate the screenshots folder (set SBOX_LOG_PATH or SBOX_SCREENSHOTS_DIR). Read the newest PNGs in <sbox>/screenshots/.`,
+        };
+        return { content: [{ type: "text", text: JSON.stringify(summary, null, 2) }] };
+    });
 }
 //# sourceMappingURL=diagnostics.js.map

package/dist/tools/project.js

@@ -96,5 +96,19 @@ export function registerProjectTools(server, bridge) {
             ],
         };
     });
+    // ── recompile_asset ──────────────────────────────────────────────
+    server.tool("recompile_asset", "Compile a project asset by path — registers it with the editor's AssetSystem then compiles it (e.g. .vmat → .vmat_c). Use after writing/editing an asset with write_file so the change takes effect without a manual editor step. Verified on materials. NOTE: the engine exposes no reachable particle (.vpcf) compiler, so this can't compile particles — author those in s&box's particle editor, then spawn_vpcf plays them.", {
+        path: z
+            .string()
+            .describe("Asset path — project-relative (e.g. 'materials/foo.vmat') or absolute"),
+    }, async (params) => {
+        const res = await bridge.send("recompile_asset", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
 }
 //# sourceMappingURL=project.js.map

package/package.json

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