sbox-mcp-server 1.13.0 → 1.15.0

package/dist/index.js

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

package/dist/tools/debugdraw.d.ts

@@ -0,0 +1,18 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * debug_draw_* / debug_clear — visualize debug primitives in the scene
+ * (ported from the Claude Bridge for Unity's debug_draw family).
+ *
+ * Renders in BOTH modes via one ClaudeDebugDraw holder component:
+ *   • edit scene → Gizmo.Draw.* — visible in the live editor viewport, but NOT
+ *     in take_screenshot/screenshot_from (the editor gizmo pass isn't in that
+ *     camera render). Confirm edit-mode draws with your own eyes in the editor.
+ *   • play scene → Scene.DebugOverlay.* — visible in-game AND through the bridge
+ *     via capture_view (which renders the running scene).
+ *
+ * Coords are world-space "x,y,z" strings; colors are "r,g,b" or "r,g,b,a"
+ * floats 0–1. Primitives accumulate until debug_clear.
+ */
+export declare function registerDebugDrawTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=debugdraw.d.ts.map

package/dist/tools/debugdraw.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+/**
+ * debug_draw_* / debug_clear — visualize debug primitives in the scene
+ * (ported from the Claude Bridge for Unity's debug_draw family).
+ *
+ * Renders in BOTH modes via one ClaudeDebugDraw holder component:
+ *   • edit scene → Gizmo.Draw.* — visible in the live editor viewport, but NOT
+ *     in take_screenshot/screenshot_from (the editor gizmo pass isn't in that
+ *     camera render). Confirm edit-mode draws with your own eyes in the editor.
+ *   • play scene → Scene.DebugOverlay.* — visible in-game AND through the bridge
+ *     via capture_view (which renders the running scene).
+ *
+ * Coords are world-space "x,y,z" strings; colors are "r,g,b" or "r,g,b,a"
+ * floats 0–1. Primitives accumulate until debug_clear.
+ */
+export function registerDebugDrawTools(server, bridge) {
+    const reply = (res) => res.success
+        ? { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] }
+        : { content: [{ type: "text", text: `Error: ${res.error}` }] };
+    const color = z
+        .string()
+        .optional()
+        .describe('Color as "r,g,b" or "r,g,b,a" floats 0–1 (default varies per shape)');
+    const thickness = z.number().optional().describe("Line thickness for edit-mode gizmos (default 2)");
+    server.tool("debug_draw_line", "Draw a debug line between two world points. Renders in the editor viewport (Gizmo) AND in play mode (DebugOverlay), accumulating until debug_clear. NB: edit-mode gizmos show in the live editor but NOT in take_screenshot/screenshot_from — use capture_view in play mode to see debug draws through the bridge.", {
+        from: z.string().describe('Start point, world-space "x,y,z"'),
+        to: z.string().describe('End point, world-space "x,y,z"'),
+        color,
+        thickness,
+    }, async (p) => reply(await bridge.send("debug_draw_line", p)));
+    server.tool("debug_draw_ray", "Draw a debug ray (drawn as an arrow) from an origin along a direction for a given length. Renders in editor and play. Ideal for visualizing a raycast result or a facing/normal direction. Accumulates until debug_clear.", {
+        origin: z.string().describe('Ray origin, world-space "x,y,z"'),
+        direction: z.string().describe('Direction vector "x,y,z" (normalized internally)'),
+        length: z.number().optional().describe("Ray length in units (default 64)"),
+        color,
+        thickness,
+    }, async (p) => reply(await bridge.send("debug_draw_ray", p)));
+    server.tool("debug_draw_box", "Draw a wireframe debug box centered at a point. Renders in editor and play. Ideal for visualizing a trigger_zone's bounds or a physics_overlap box volume. Accumulates until debug_clear.", {
+        center: z.string().describe('Box center, world-space "x,y,z"'),
+        size: z.string().optional().describe('Full size "x,y,z" in units (default "32,32,32")'),
+        color,
+        thickness,
+    }, async (p) => reply(await bridge.send("debug_draw_box", p)));
+    server.tool("debug_draw_sphere", "Draw a wireframe debug sphere at a point. Renders in editor and play. Ideal for visualizing a physics_overlap radius or an NPC's hearing/sight range. Accumulates until debug_clear.", {
+        center: z.string().describe('Sphere center, world-space "x,y,z"'),
+        radius: z.number().optional().describe("Radius in units (default 32)"),
+        color,
+        thickness,
+    }, async (p) => reply(await bridge.send("debug_draw_sphere", p)));
+    server.tool("debug_clear", "Remove all debug-draw primitives by destroying the debug holder for the current scene (edit or play). Call before redrawing a fresh frame of debug shapes.", {}, async (p) => reply(await bridge.send("debug_clear", p)));
+}
+//# sourceMappingURL=debugdraw.js.map

package/dist/tools/debugviz.d.ts

@@ -0,0 +1,12 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Debug-visualization & playtest meta-tools ported from the Unity bridge's
+ * engine/workflow layer (see docs/plans/2026-06-17-unity-carryover-meta-tools.md).
+ *
+ * Currently: set_time_scale + get_profiler_stats (Unity carry-over wave, 2 of 4).
+ * Planned next: debug_draw_* + debug_clear (Gizmo.Draw edit-mode + DebugOverlay
+ * play-mode) and run_tests (dotnet test spike).
+ */
+export declare function registerDebugVizTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=debugviz.d.ts.map

package/dist/tools/debugviz.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+/**
+ * Debug-visualization & playtest meta-tools ported from the Unity bridge's
+ * engine/workflow layer (see docs/plans/2026-06-17-unity-carryover-meta-tools.md).
+ *
+ * Currently: set_time_scale + get_profiler_stats (Unity carry-over wave, 2 of 4).
+ * Planned next: debug_draw_* + debug_clear (Gizmo.Draw edit-mode + DebugOverlay
+ * play-mode) and run_tests (dotnet test spike).
+ */
+export function registerDebugVizTools(server, bridge) {
+    // ── set_time_scale ───────────────────────────────────────────────
+    server.tool("set_time_scale", "Set the running game's time scale DURING PLAY MODE (ported from Unity's playtest_set_time_scale). 0 = pause, 1 = normal, 0.1 = slow-mo to watch a fast interaction frame-by-frame, 2+ = fast-forward idle/economy ticks. Requires start_play first — the edit scene doesn't tick, so this no-ops outside play mode and returns an error. Sets Game.ActiveScene.TimeScale (clamped to 0–100). Returns the applied and previous values.", {
+        scale: z
+            .number()
+            .min(0)
+            .describe("Time multiplier: 0 = pause, 1 = normal speed, 0.1 = slow-mo, 2 = double speed. Clamped to 0–100"),
+    }, async (params) => {
+        const res = await bridge.send("set_time_scale", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── get_profiler_stats ───────────────────────────────────────────
+    server.tool("get_profiler_stats", "Read live engine performance counters (ported from Unity's get_profiler_stats): FPS, frame ms, GPU ms, bytes allocated, process memory, exception count, and per-category timings (update/physics/ui/render/network/gcPause) averaged over `frames`. Reads Sandbox.Diagnostics.PerformanceStats. Most meaningful during play (call start_play first) but populated in the editor too. Read-only.", {
+        frames: z
+            .number()
+            .int()
+            .min(1)
+            .max(1000)
+            .optional()
+            .describe("Averaging window (frames) for the per-category timings. Default 60"),
+    }, async (params) => {
+        const res = await bridge.send("get_profiler_stats", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=debugviz.js.map

package/package.json

@@ -1,55 +1,55 @@
-{
-  "name": "sbox-mcp-server",
-  "version": "1.13.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.15.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"
+}