sbox-mcp-server 1.12.0 → 1.14.0

package/dist/index.js

@@ -45,6 +45,7 @@ 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";
 // ── CLI flags ──────────────────────────────────────────────────────
 const args = process.argv.slice(2);
 /** Read the package version from package.json, or return "unknown" on failure. */
@@ -193,6 +194,7 @@ registerGameplayTools(server, bridge);
 registerNpcTools(server, bridge);
 registerInspectionTools(server, bridge);
 registerInputTools(server, bridge);
+registerDebugVizTools(server, bridge);
 /** Start the MCP server on stdio and attempt initial Bridge connection. */
 async function main() {
     const transport = new StdioServerTransport();

package/dist/tools/components.js

@@ -24,9 +24,8 @@ export function registerComponentTools(server, bridge) {
         };
     });
     // ── get_all_properties ───────────────────────────────────────────
-    server.tool("get_all_properties", "Dump all public properties of a component as JSON — names, types, and current values", {
+    server.tool("get_all_properties", "Dump all public properties of every component on a GameObject as JSON -- names, types, and current values", {
         id: z.string().describe("GUID of the GameObject"),
-        component: z.string().describe("Component type name"),
     }, async (params) => {
         const res = await bridge.send("get_all_properties", params);
         if (!res.success) {

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/dist/tools/gameplay.js

@@ -378,5 +378,59 @@ export function registerGameplayTools(server, bridge) {
         }
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
+    // -- create_leaderboard_panel ------------------------------------------
+    server.tool("create_leaderboard_panel", "Generate a Razor PanelComponent that fetches and displays a Sandbox.Services leaderboard derived from a stat name. Produces TWO files: {name}.razor and {name}.razor.scss. The panel auto-refreshes every 30 s, shows rank/displayName/value rows, handles loading state, and includes a BuildHash() override (razor-lint clean). Must be hosted under a ScreenPanel or WorldPanel. Stats must be configured for the project ident on sbox.game. Uses Leaderboards.Get(statName) + board.Refresh() -- the exact API from ServicesQueryHandler.", {
+        name: z.string().optional().describe("Class name for the panel component. Defaults to 'LeaderboardPanel'"),
+        directory: z.string().optional().describe("Subdirectory for the generated files. Defaults to 'Code/UI'"),
+        statName: z.string().optional().describe("Sandbox.Services stat name the leaderboard is derived from. Defaults to 'score'"),
+        title: z.string().optional().describe("Display title shown at the top of the panel. Defaults to 'Leaderboard'"),
+        maxRows: z.number().int().optional().describe("Maximum leaderboard rows to fetch and display. Defaults to 10"),
+    }, async (params) => {
+        const res = await bridge.send("create_leaderboard_panel", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // -- create_inventory --------------------------------------------------
+    server.tool("create_inventory", "Generate a slot-based inventory component using parallel List<string> ItemIds / List<int> Counts (serialization-safe, inspector-editable). Includes TryAdd (stack-first, partial-add rejected), TryRemove, CountOf, Move (swap or merge same-id slots), and Clear. Static OnChanged event fires after every successful mutation. Host-authoritative usage note: mutate on the host in multiplayer, replicate via your own [Sync]/RPC. Pairs with create_pickup.", {
+        name: z.string().optional().describe("Class name. Defaults to 'Inventory'"),
+        directory: z.string().optional().describe("Subdirectory for the .cs file. Defaults to 'Code'"),
+        capacity: z.number().int().optional().describe("Total slot count. Defaults to 24"),
+        maxStack: z.number().int().optional().describe("Maximum items per slot (stack cap). Defaults to 99"),
+        targetId: z.string().optional().describe("GUID of an existing GameObject to attach to (hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_inventory", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // -- create_stat_modifier_system ---------------------------------------
+    server.tool("create_stat_modifier_system", "Generate an enum-keyed stat modifier system with three modifier layers: SET (highest-priority-wins hard override), ADD (summed bonuses), MULT (multiplied factors applied last). Modifier storage uses parallel private Lists of primitive types (serialization-safe). RemoveModifiersFrom(source) cleans up all mods from a buff/debuff source by reference. Static OnStatChanged(stat, value) event fires after every add/remove. Mined from RPG/buff/debuff patterns across shipped s&box games.", {
+        name: z.string().optional().describe("Class name prefix -- generates {name}Stat enum + {name} Component. Defaults to 'StatSystem'"),
+        directory: z.string().optional().describe("Subdirectory for the .cs file. Defaults to 'Code'"),
+        stats: z.union([z.array(z.string()), z.string()]).optional().describe("Stat names as a JSON array or comma-separated string. Defaults to 'Health,Speed,Damage'"),
+        targetId: z.string().optional().describe("GUID of an existing GameObject to attach to (hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_stat_modifier_system", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // -- create_placement_mode ---------------------------------------------
+    server.tool("create_placement_mode", "Generate a ghost-preview + commit placement component (single class). StartPlacing() clones GhostPrefab as a NetworkMode.Never preview with colliders disabled and ModelRenderers tinted semi-transparent. Each frame while placing: ray from Scene.Camera.GetMouseRay(), IgnoreGameObjectHierarchy(ghost), snap hit position to GridSize (0 = freeform), move ghost. On Input.Pressed('attack1') TryPlace() re-validates distance and commits a real clone. StopPlacing() destroys the ghost. Static OnPlaced(GameObject, Vector3) event. Includes a multiplayer RPC note. API grounded in building-placement cookbook (enifun.shop_manager pattern).", {
+        name: z.string().optional().describe("Class name. Defaults to 'PlacementMode'"),
+        directory: z.string().optional().describe("Subdirectory for the .cs file. Defaults to 'Code'"),
+        gridSize: z.number().optional().describe("Snap grid size in world units (0 = freeform placement). Defaults to 0"),
+        targetId: z.string().optional().describe("GUID of an existing GameObject to attach to (hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_placement_mode", 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/package.json

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