sbox-mcp-server 1.5.2 → 1.7.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 — **152 tools / 145 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: 145`. (That's the editor-side handler count; the server exposes 152 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 (151 / 145 editor handlers — v1.5.1)
+## Tools (v1.5.2)
 
-`get_bridge_status` reports `handlerCount: 145` — 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/index.js

@@ -40,6 +40,9 @@ import { registerObjectTools } from "./tools/objecttools.js";
 import { registerDiagnosticTools } from "./tools/diagnostics.js";
 import { registerDocsTools } from "./tools/docs.js";
 import { registerNavigationTools } from "./tools/navigation.js";
+import { registerSelfTestTools } from "./tools/selftest.js";
+import { registerGameplayTools } from "./tools/gameplay.js";
+import { registerNpcTools } from "./tools/npc.js";
 // ── CLI flags ──────────────────────────────────────────────────────
 const args = process.argv.slice(2);
 /** Read the package version from package.json, or return "unknown" on failure. */
@@ -183,6 +186,9 @@ registerObjectTools(server, bridge);
 registerDiagnosticTools(server, bridge);
 registerDocsTools(server, bridge);
 registerNavigationTools(server, bridge);
+registerSelfTestTools(server, bridge);
+registerGameplayTools(server, bridge);
+registerNpcTools(server, bridge);
 /** Start the MCP server on stdio and attempt initial Bridge connection. */
 async function main() {
     const transport = new StdioServerTransport();

package/dist/tools/characters.js

@@ -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/components.js

@@ -56,7 +56,7 @@ export function registerComponentTools(server, bridge) {
         };
     });
     // ── add_component_with_properties ────────────────────────────────
-    server.tool("add_component_with_properties", "Add a component to a GameObject and configure its properties in one call. Use list_available_components to find valid types", {
+    server.tool("add_component_with_properties", "Add a component to a GameObject and configure its properties in one call (properties PERSIST through save+reload). Use list_available_components to find valid types. Returns appliedProperties + failedProperties so you can see exactly what stuck", {
         id: z.string().describe("GUID of the GameObject"),
         component: z
             .string()
@@ -64,7 +64,7 @@ export function registerComponentTools(server, bridge) {
         properties: z
             .record(z.unknown())
             .optional()
-            .describe("Key-value map of property names to values. Values are auto-converted to the correct type"),
+            .describe("Key-value map of property names to values, each auto-converted to the property's real type. Primitives '5'/true; Color/Vector3 as comma strings '1,0,0,1'; enum member names; ASSET refs as a path ('Model':'models/dev/box.vmdl', 'MaterialOverride':'materials/x.vmat'); GameObject/Component refs as a target GUID. Best-effort per key — failures are reported in failedProperties, not silently dropped"),
     }, async (params) => {
         const res = await bridge.send("add_component_with_properties", params);
         if (!res.success) {

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,135 @@ 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) }] };
+    });
+    // ── 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() })
+            .optional()
+            .describe("Camera world position (temp camera; use instead of id)"),
+        lookAt: z
+            .object({ x: z.number(), y: z.number(), z: z.number() })
+            .optional()
+            .describe("World point to look at (pair with position)"),
+        rotation: z
+            .object({ pitch: z.number(), yaw: z.number(), roll: z.number() })
+            .optional()
+            .describe("Explicit camera rotation (pair with position)"),
+        fov: z.number().optional().describe("Field of view for the temp camera"),
+        renderUI: z.boolean().optional().describe("Include UI/HUD (default true). Renders world + world-space UI but NOT fullscreen screen-space panels (lobby/title overlays) — so capture_view sees 'through' menus; use take_screenshot for screen-space UI."),
+        width: z.number().int().optional().describe("Width (default 1280)"),
+        height: z.number().int().optional().describe("Height (default 720)"),
+    }, async (params) => {
+        const res = await bridge.send("capture_view", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
 }
 //# sourceMappingURL=diagnostics.js.map

package/dist/tools/gameplay.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+export declare function registerGameplayTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=gameplay.d.ts.map

package/dist/tools/gameplay.js

@@ -0,0 +1,227 @@
+import { z } from "zod";
+/**
+ * Gameplay scaffold tools — Phase 1 of "playable game in one ask".
+ *
+ * Two low-level capability gap-fillers:
+ *   - set_component_reference   wire a component property to a LIVE scene object
+ *   - add_component_to_new_object  atomic create-GO + add-component + props
+ *
+ * Three system scaffolds (generate a clean, self-contained .cs, optionally place it):
+ *   - create_objective_system   the win/lose primitive (ObjectiveManager)
+ *   - create_health_system      Health/damage component
+ *   - create_pickup             trigger-based collectible
+ *
+ * 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({
+    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 RotationSchema = z
+    .object({
+    pitch: z.number().describe("Pitch angle in degrees"),
+    yaw: z.number().describe("Yaw angle in degrees"),
+    roll: z.number().describe("Roll angle in degrees"),
+})
+    .describe("Euler rotation with pitch, yaw, roll in degrees");
+export function registerGameplayTools(server, bridge) {
+    // ── set_component_reference ───────────────────────────────────────
+    // Assign one scene GameObject (or a component on it) to a component property.
+    // set_property can now also set a GameObject/Component ref from a GUID, but this
+    // tool is the ergonomic choice for refs: it can pull a specific component type off
+    // the target (targetComponent) and validates the wiring. set_prefab_ref is for
+    // PREFAB assets. Wires live scene objects: Spawner.SpawnPoint = thatEmpty,
+    // Camera follows thatPlayer, Door.Hinge = thatPivot.
+    server.tool("set_component_reference", "Wire a component's GameObject/Component-typed property to ANOTHER live object in the scene by GUID (e.g. ObjectiveManager.Player = the player, a camera's follow target, a door's hinge). Preferred for object/component refs (can pick a specific component type off the target via targetComponent, and validates). set_property also accepts a GUID for ref props; set_prefab_ref is for prefab assets. Set clear:true to null the reference", {
+        id: z
+            .string()
+            .describe("GUID of the GameObject that HOLDS the component you're writing into"),
+        component: z
+            .string()
+            .describe("Component type name on that object (e.g. 'ObjectiveManager', 'CameraComponent')"),
+        property: z
+            .string()
+            .describe("The property to set (must be a GameObject- or Component-typed property)"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of the GameObject to reference. Required unless clear:true"),
+        targetComponent: z
+            .string()
+            .optional()
+            .describe("If the property is a Component subtype, the specific component type to pull off the target object. Omit to auto-match by the property's type"),
+        clear: z
+            .boolean()
+            .optional()
+            .describe("If true, set the reference to null instead of assigning a target"),
+    }, async (params) => {
+        const res = await bridge.send("set_component_reference", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── add_component_to_new_object ───────────────────────────────────
+    server.tool("add_component_to_new_object", "Create a new GameObject, add a component, set its properties, and optionally parent/position/tag it — all in one atomic call. Collapses the create_gameobject → add_component_with_properties → set_parent sequence. NOTE: a freshly GENERATED component type only resolves after a trigger_hotload; generate the script, hotload, THEN call this", {
+        name: z
+            .string()
+            .optional()
+            .describe("Display name for the new GameObject. Defaults to the component type name"),
+        component: z
+            .string()
+            .describe("Component type name to add (e.g. 'CameraComponent', 'ObjectiveManager'). Use list_available_components to find valid types"),
+        properties: z
+            .record(z.unknown())
+            .optional()
+            .describe("Key-value map of property names to values, auto-converted to the right type (same convention as add_component_with_properties)"),
+        position: Vector3Schema.optional().describe("World position"),
+        rotation: RotationSchema.optional().describe("World rotation"),
+        scale: Vector3Schema.optional().describe("World scale (per-axis)"),
+        parentId: z
+            .string()
+            .optional()
+            .describe("GUID of a parent GameObject. Omit for scene root"),
+        tags: z
+            .array(z.string())
+            .optional()
+            .describe("Tags to add to the new GameObject (e.g. ['player'])"),
+    }, async (params) => {
+        const res = await bridge.send("add_component_to_new_object", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── create_objective_system ───────────────────────────────────────
+    // The win/lose primitive — turns "objects in a scene" into "a game with a goal".
+    server.tool("create_objective_system", "Generate an ObjectiveManager component — the win/lose brain of a game. Tracks an objective (collect_all / reach_goal / survive_time / eliminate_all), fires a win, and handles a lose condition (fall below kill-Z / timer / out of lives). Self-contained C#; other systems call ObjectiveManager.Instance. Optionally placed as a scene singleton", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name. Defaults to 'ObjectiveManager'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the .cs file. Defaults to 'Code'"),
+        objective: z
+            .enum(["collect_all", "reach_goal", "survive_time", "eliminate_all"])
+            .optional()
+            .describe("Win condition. Defaults to 'reach_goal'"),
+        targetCount: z
+            .number()
+            .int()
+            .optional()
+            .describe("How many to collect/eliminate (for collect_all / eliminate_all). Defaults to 3"),
+        timeLimit: z
+            .number()
+            .optional()
+            .describe("Seconds — survive this long to win (survive_time) or before losing (loseOn=timer). Defaults to 60"),
+        loseOn: z
+            .enum(["fall", "timer", "lives", "none"])
+            .optional()
+            .describe("Lose condition. 'fall' = player drops below killZ. Defaults to 'fall'"),
+        killZ: z
+            .number()
+            .optional()
+            .describe("World Z below which the player is considered fallen out of the world. Defaults to -1000"),
+        lives: z
+            .number()
+            .int()
+            .optional()
+            .describe("Lives before game over (loseOn=lives). Defaults to 1"),
+        placeInScene: z
+            .boolean()
+            .optional()
+            .describe("Place the manager as a scene singleton. Defaults to true. (Only attaches if the type is already loaded — generate, hotload, then it places; otherwise add it after hotload.)"),
+    }, async (params) => {
+        const res = await bridge.send("create_objective_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_health_system ──────────────────────────────────────────
+    server.tool("create_health_system", "Generate a Health component: MaxHealth, [Sync] CurrentHealth, TakeDamage/Heal, an OnDeath event, optional regen and respawn. Host-authoritative damage when networked, single-player safe. Optionally attached to an existing GameObject by GUID", {
+        name: z.string().optional().describe("Class name. Defaults to 'Health'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the .cs file. Defaults to 'Code'"),
+        maxHealth: z
+            .number()
+            .optional()
+            .describe("Starting/maximum health. Defaults to 100"),
+        regen: z
+            .boolean()
+            .optional()
+            .describe("Include passive health regeneration after a delay. Defaults to false"),
+        respawn: z
+            .boolean()
+            .optional()
+            .describe("On death, respawn at a RespawnPoint (wire it with set_component_reference) instead of disabling. Defaults to false"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of an existing GameObject to attach the Health component to (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_health_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_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
+            .string()
+            .optional()
+            .describe("Subdirectory for the .cs file. Defaults to 'Code'"),
+        action: z
+            .enum(["score", "heal", "item", "custom"])
+            .optional()
+            .describe("Effect flavour (all self-contained; the heal/item branches show the typed call to a companion system in comments). Defaults to 'score'"),
+        amount: z
+            .number()
+            .optional()
+            .describe("Magnitude of the effect (score points, heal amount). Defaults to 1"),
+        filterTag: z
+            .string()
+            .optional()
+            .describe("Only collect for objects with this tag. Defaults to 'player'"),
+        placeInScene: z
+            .boolean()
+            .optional()
+            .describe("Also build a pickup GameObject (trigger SphereCollider + optional model). Defaults to false"),
+        position: Vector3Schema.optional().describe("World position when placeInScene is true"),
+        radius: z
+            .number()
+            .optional()
+            .describe("Trigger sphere radius when placed. Defaults to 24"),
+        model: z
+            .string()
+            .optional()
+            .describe("Optional model path for a visible pickup (e.g. 'models/dev/box.vmdl'). Cloud assets must be installed first"),
+    }, async (params) => {
+        const res = await bridge.send("create_pickup", 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/npc.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+export declare function registerNpcTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=npc.d.ts.map

package/dist/tools/npc.js

@@ -0,0 +1,195 @@
+import { z } from "zod";
+/**
+ * NPC Brains (Feature Wave #3) — give bridge-built NPCs actual behavior.
+ *
+ * create_npc_brain generates a finite-state-machine Component (idle/patrol/
+ * wander/chase/search/flee/ambush) driven by occlusion-aware perception (FOV
+ * cone + range + line-of-sight trace + hearing) with last-known-position
+ * memory — the decision layer on top of the existing movement substrate
+ * (bake_navmesh / get_navmesh_path / create_npc_controller). place_patrol_route
+ * + assign_patrol_route make a patrol authorable end-to-end; create_npc_spawner
+ * is the swarm/wave backbone. simulate_npc_perception is the keystone verifier:
+ * it runs the EXACT line-of-sight check the brain uses, in EDIT mode, without
+ * play — so "does the tree block the NPC's view" is checkable structurally
+ * (the bridge can't see a real chase in a single static screenshot).
+ *
+ * Mirrors the templates.ts / navigation.ts module shape: zod params, one
+ * bridge.send per tool, JSON.stringify(res.data) on success.
+ */
+const Vec3 = z
+    .object({
+    x: z.number().describe("X"),
+    y: z.number().describe("Y"),
+    z: z.number().describe("Z"),
+})
+    .describe("A world-space Vector3");
+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.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class/file name. Defaults to 'NpcBrain'. Sanitized to a valid C# identifier."),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory under the project root for the .cs file. Defaults to 'Code'."),
+        behavior: z
+            .enum(["patrol", "guard", "hunter", "swarm", "skittish"])
+            .optional()
+            .describe("Preset (sets StartState + flee toggle): 'patrol' (walk waypoints), 'guard' (Ambush near spawn until a target enters range), 'hunter' (patrol->chase->search, the Sasquatch), 'swarm' (wander/idle->chase nearest, RUN mobs), 'skittish' (chase but flee on low health). The generated file is the same shape; the preset just changes defaults. Defaults to 'hunter'."),
+        targetTag: z
+            .string()
+            .optional()
+            .describe("Tag the NPC hunts (its candidates are GameObjects with this tag). Defaults to 'player'."),
+        moveSpeed: z.number().optional().describe("Patrol/wander speed (NavMeshAgent MaxSpeed). Default 130."),
+        chaseSpeed: z.number().optional().describe("Chase/flee speed. Default 200."),
+        sightRange: z.number().optional().describe("Max sight distance. Default 1500."),
+        fovDegrees: z
+            .number()
+            .optional()
+            .describe("Full field-of-view cone angle in degrees. Default 110. (Baked into a cosine threshold for cheap, trig-free checks.)"),
+        eyeHeight: z.number().optional().describe("Trace origin height above the NPC's feet. Default 64."),
+        hearingRadius: z
+            .number()
+            .optional()
+            .describe("Proximity-hearing radius — a target within it is investigated (sets last-known-pos) but NOT instantly aggroed. Default 600."),
+        giveUpTime: z
+            .number()
+            .optional()
+            .describe("Seconds to search after losing line-of-sight before giving up and resuming the start state. Default 6."),
+        searchRadius: z.number().optional().describe("Wander radius around the last-known position while searching. Default 400."),
+        waypointStopDistance: z
+            .number()
+            .optional()
+            .describe("How close the NPC must get to a waypoint/target before it counts as reached. Default 80."),
+        canFlee: z.boolean().optional().describe("Enable the Flee state (else the NPC never flees). Defaults from the preset."),
+        fleeHealthFrac: z
+            .number()
+            .optional()
+            .describe("Flee when CurrentHealthFrac drops to/below this (the game sets CurrentHealthFrac 0..1). Default 0.25."),
+        networked: z
+            .boolean()
+            .optional()
+            .describe("When true (default), emit a host-authoritative brain: 'if (IsProxy) return;' + [Sync] CurrentState. NOTE: a no-session solo playtest makes everything a proxy, so a networked brain won't think until a host session exists — pass false to iterate solo in the edit scene."),
+    }, async (params) => {
+        const res = await bridge.send("create_npc_brain", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── place_patrol_route ────────────────────────────────────────────
+    server.tool("place_patrol_route", "Place a set of waypoint GameObjects (tagged empties) for a patrol route and group them under a parent route object — authorable in one call. Optionally snaps each point to the ground (raycast down) so waypoints sit on the navmesh, not floating. Returns the route parent GUID + ordered waypoint GUIDs to feed into assign_patrol_route. Validate connectivity afterward with get_navmesh_path between consecutive waypoints (catches a 'point in a wall').", {
+        points: z
+            .array(Vec3)
+            .min(2)
+            .describe("Ordered world positions for the route (at least 2)."),
+        name: z.string().optional().describe("Route name. Defaults to 'PatrolRoute'. Waypoints are named <route>_WP0, _WP1, ..."),
+        tag: z.string().optional().describe("Tag applied to each waypoint. Defaults to 'waypoint'."),
+        snapToGround: z
+            .boolean()
+            .optional()
+            .describe("Drop each point onto the surface below via a downward raycast. Default true."),
+        parentId: z
+            .string()
+            .optional()
+            .describe("Existing parent GameObject GUID to nest the waypoints under; otherwise a new route empty is created at the points' centroid."),
+    }, async (params) => {
+        const res = await bridge.send("place_patrol_route", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── assign_patrol_route ───────────────────────────────────────────
+    server.tool("assign_patrol_route", "Wire a placed route (or an arbitrary ordered GUID list) into an NpcBrain's Waypoints list on a target NPC. This is the list-of-GameObject-references case that plain set_property can't express. Pass either waypointIds (explicit order) or routeId (a route parent whose children become the waypoints in hierarchy order). The list count is returned; List<GameObject> refs may read back as handles/GUIDs via get_property, so trust the count or confirm patrol in play mode.", {
+        npcId: z
+            .string()
+            .describe("GUID of the GameObject holding the NpcBrain (or any component with a List<GameObject> waypoint property)."),
+        waypointIds: z
+            .array(z.string())
+            .optional()
+            .describe("Ordered waypoint GameObject GUIDs (e.g. from place_patrol_route). Takes precedence over routeId."),
+        routeId: z
+            .string()
+            .optional()
+            .describe("A route parent GUID whose children (in hierarchy order) become the waypoints."),
+        property: z
+            .string()
+            .optional()
+            .describe("The List<GameObject> property name to set. Defaults to 'Waypoints'. (Use 'SpawnPoints' to wire spawn points on a spawner.)"),
+    }, async (params) => {
+        const res = await bridge.send("assign_patrol_route", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── create_npc_spawner ────────────────────────────────────────────
+    server.tool("create_npc_spawner", "Generate a spawner Component that instantiates an NPC prefab over time / in escalating waves at spawn points, capped by maxAlive. RUN's swarm backbone and Sasquatched's round-start spawn. After generating: set NpcPrefab via set_prefab_ref, set SpawnPoints (reuse place_patrol_route to make a set of empties, then assign_patrol_route with property='SpawnPoints'), trigger_hotload + get_compile_errors. Verify by watching the GameObject count over time in play mode. Networked spawns use NetworkSpawn() and are host-only.", {
+        name: z.string().optional().describe("Class/file name. Defaults to 'NpcSpawner'."),
+        directory: z.string().optional().describe("Subdirectory under the project root. Defaults to 'Code'."),
+        mode: z
+            .enum(["continuous", "waves", "burst"])
+            .optional()
+            .describe("'continuous' (one every interval), 'waves' (a batch every interval, waveCount times), 'burst' (one batch then stop). Default 'waves'."),
+        count: z.number().optional().describe("NPCs per wave (waves) or per batch (burst/continuous batch). Default 5."),
+        interval: z.number().optional().describe("Seconds between spawns (continuous) or between waves (waves). Default 8."),
+        waveCount: z.number().optional().describe("Number of waves (waves mode). Default 3."),
+        waveGrowth: z
+            .number()
+            .optional()
+            .describe("Multiply count each wave (>1 = escalating). Default 1.0."),
+        radius: z.number().optional().describe("Random scatter radius around a spawn point. Default 200."),
+        maxAlive: z
+            .number()
+            .optional()
+            .describe("Cap on concurrent live NPCs (important so swarms don't melt the frame rate). Default 12."),
+        networked: z
+            .boolean()
+            .optional()
+            .describe("When true (default), spawn via NetworkSpawn() (host-only, try/catch solo-safe) so clients see the NPCs; false = a plain local Clone for solo/edit testing."),
+    }, async (params) => {
+        const res = await bridge.send("create_npc_spawner", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── simulate_npc_perception ───────────────────────────────────────
+    server.tool("simulate_npc_perception", "READ-ONLY edit-mode verifier: evaluate the NPC's perception math RIGHT NOW without entering play mode. Given an NPC (reads its NpcBrain SightRange/FovDegrees/EyeHeight/TargetTag + transform) and either a targetId or a point, it runs the SAME line-of-sight check the brain uses — FOV cone (dot vs the baked cosine), sight-range gate, and an occlusion trace from the eye to the target — and reports the result AND why. This is the keystone verifier: it makes the perception layer checkable in edit mode (no flaky screenshot timing) — e.g. place the Sasquatch, place a camper behind a tree, and confirm the tree blocks LOS. Call params override the brain's values, so it also works before/without an NpcBrain (uses defaults). Safe in play mode too (read-only, like raycast).", {
+        npcId: z
+            .string()
+            .describe("GUID of the NPC GameObject (ideally with an NpcBrain; its perception [Property] values are read)."),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of the target GameObject to test visibility to (e.g. a player). Provide this OR point."),
+        point: Vec3.optional().describe("A raw world point to test visibility to. Provide this OR targetId."),
+        sightRange: z.number().optional().describe("Override the sight range for this check (else read from the NpcBrain / default 1500)."),
+        fovDegrees: z.number().optional().describe("Override the FOV cone angle for this check (else read from the NpcBrain / default 110)."),
+        eyeHeight: z.number().optional().describe("Override the eye height for this check (else read from the NpcBrain / default 64)."),
+        targetTag: z
+            .string()
+            .optional()
+            .describe("Override the target tag (canSee also requires the target to carry this tag; else read from the NpcBrain / default 'player')."),
+    }, async (params) => {
+        const res = await bridge.send("simulate_npc_perception", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=npc.js.map

package/dist/tools/playmode.js

@@ -76,11 +76,13 @@ export function registerPlayModeTools(server, bridge) {
         };
     });
     // ── set_property ─────────────────────────────────────────────────
-    server.tool("set_property", "Set a property value on a component (editor mode). Reads the value back to confirm", {
+    server.tool("set_property", "Set a property value on a component (editor mode), and PERSIST it (survives save+reload). Handles primitives, enums, value types (Color/Vector3 as comma strings), AND references: pass an asset PATH for Model/Material/Texture/SoundEvent props, or a GameObject GUID for GameObject/Component-typed props (resolved like set_component_reference). Returns success=false with a clear error if a path/GUID can't be resolved (no more silent null). For wiring object refs prefer set_component_reference; for prefab refs use set_prefab_ref", {
         id: z.string().describe("GUID of the GameObject"),
         component: z.string().describe("Component type name"),
         property: z.string().describe("Property name to set"),
-        value: z.unknown().describe("New value — auto-converted to the correct type"),
+        value: z
+            .unknown()
+            .describe("New value as a string. Primitive: '5', 'true'. Color/Vector3: '1,0,0,1' / '0,0,200'. Enum: the member name. Asset ref (Model/Material/...): the asset path e.g. 'models/dev/box.vmdl'. GameObject/Component ref: the target GameObject's GUID. Empty/'null' clears the property"),
     }, async (params) => {
         const res = await bridge.send("set_property", params);
         if (!res.success) {

package/dist/tools/selftest.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+export declare function registerSelfTestTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=selftest.d.ts.map

package/dist/tools/selftest.js

@@ -0,0 +1,121 @@
+import { existsSync, unlinkSync } from "fs";
+import { join } from "path";
+function report(checks, override, runId) {
+    const pass = checks.filter((c) => c.ok).length;
+    const total = checks.length;
+    let verdict = override;
+    if (!verdict) {
+        verdict =
+            pass === total
+                ? `HEALTHY — ${pass}/${total} checks passed`
+                : pass >= total - 1
+                    ? `DEGRADED — ${pass}/${total} passed`
+                    : `BROKEN — only ${pass}/${total} passed`;
+    }
+    const lines = checks
+        .map((c) => `  ${c.ok ? "PASS" : "FAIL"}  ${c.name}${c.detail ? " — " + c.detail : ""}`)
+        .join("\n");
+    const json = JSON.stringify({ verdict, pass, total, runId: runId ?? null, checks }, null, 2);
+    return { content: [{ type: "text", text: `run_self_test: ${verdict}\n\n${lines}\n\n${json}` }] };
+}
+export function registerSelfTestTools(server, bridge) {
+    server.tool("run_self_test", "Run an end-to-end health check of the bridge: create a temp object, add a component, assign + measure a model, capture a screenshot, recompile a temp asset, remove the component — then clean it all up, reporting pass/fail per subsystem. Use it to confirm the install works or to catch regressions before a release. Safe and self-cleaning; refuses to run in play mode.", {}, async () => {
+        const runId = Date.now().toString(36);
+        const checks = [];
+        const add = (name, ok, detail = "") => checks.push({ name, ok, detail });
+        const send = (cmd, p = {}) => bridge.send(cmd, p, 15000);
+        let createdId = null;
+        let projectRoot = null;
+        let tempVmatAbs = null;
+        const tempVmatRel = `materials/__selftest_${runId}.vmat`;
+        try {
+            // 0. Connectivity
+            const pi = await send("get_project_info");
+            if (!pi.success) {
+                add("connectivity", false, pi.error ?? "no response");
+                return report(checks, "BROKEN — bridge not responding. Is s&box running with the Claude Bridge addon?");
+            }
+            projectRoot = pi.data?.path ?? null;
+            add("connectivity", true, "get_project_info round-trip OK");
+            // Pre-flight: refuse in play mode (the battery mutates the scene)
+            const ip = await send("is_playing");
+            if (ip.success && ip.data?.isPlaying) {
+                add("play-mode guard", false, "editor is in play mode");
+                return report(checks, "ABORTED — stop play mode first; the self-test mutates the scene.");
+            }
+            // 1. Create a temp object
+            const cg = await send("create_gameobject", { name: `__selftest_${runId}` });
+            const cgd = cg.data;
+            createdId = cgd?.id ?? cgd?.gameObject?.id ?? cgd?.guid ?? null;
+            if (!cg.success || !createdId) {
+                add("create_gameobject", false, cg.error ?? "no id returned");
+                return report(checks, "BROKEN — couldn't create a GameObject.");
+            }
+            add("create_gameobject", true, `id ${createdId}`);
+            // 2. Add a component
+            const ac = await send("add_component_with_properties", { id: createdId, component: "ModelRenderer" });
+            add("add_component", ac.success, ac.success ? "ModelRenderer added" : ac.error ?? "fail");
+            // 3. Assign a model
+            const am = await send("assign_model", { id: createdId, model: "models/dev/box.vmdl" });
+            add("assign_model", am.success, am.success ? "box.vmdl" : am.error ?? "fail");
+            // 4. Bounds round-trip — non-empty bounds prove the model write took effect
+            const gb = await send("get_bounds", { id: createdId });
+            const sz = gb.data?.size;
+            const nonEmpty = !!sz && Math.abs(sz.x ?? 0) + Math.abs(sz.y ?? 0) + Math.abs(sz.z ?? 0) > 0.001;
+            add("get_bounds", gb.success && nonEmpty, gb.success ? (nonEmpty ? "non-empty bounds" : "empty bounds (model not applied?)") : gb.error ?? "fail");
+            // 5. Capture (the new RenderToBitmap path)
+            const cv = await send("capture_view", { width: 640, height: 360 });
+            const cvPath = cv.data?.path;
+            const capOk = cv.success && !!cvPath && existsSync(cvPath);
+            add("capture_view", capOk, capOk ? "PNG written" : cv.error ?? "no PNG produced");
+            if (cvPath && existsSync(cvPath)) {
+                try {
+                    unlinkSync(cvPath);
+                }
+                catch {
+                    /* best effort */
+                }
+            }
+            // 6. Recompile a temp asset
+            const wf = await send("write_file", {
+                path: tempVmatRel,
+                content: `// selftest\n"Layer0"\n{\n\tshader "shaders/complex.shader"\n}\n`,
+            });
+            if (wf.success) {
+                if (projectRoot)
+                    tempVmatAbs = join(projectRoot, tempVmatRel.replace(/\//g, "\\"));
+                const rc = await send("recompile_asset", { path: tempVmatRel });
+                add("recompile_asset", rc.success, rc.success ? "compiled temp .vmat" : rc.error ?? "fail");
+            }
+            else {
+                add("recompile_asset", false, `write_file failed: ${wf.error ?? "?"}`);
+            }
+            // 7. Remove the component (symmetric with step 2)
+            const rm = await send("remove_component", { id: createdId, component: "ModelRenderer" });
+            add("remove_component", rm.success, rm.success ? "removed" : rm.error ?? "fail");
+            return report(checks, null, runId);
+        }
+        finally {
+            // Cleanup — runs on success, throw, or early-return.
+            if (createdId) {
+                try {
+                    await send("delete_gameobject", { id: createdId });
+                }
+                catch {
+                    /* best effort */
+                }
+            }
+            for (const f of [tempVmatAbs, tempVmatAbs ? tempVmatAbs + "_c" : null]) {
+                if (f && existsSync(f)) {
+                    try {
+                        unlinkSync(f);
+                    }
+                    catch {
+                        /* best effort */
+                    }
+                }
+            }
+        }
+    });
+}
+//# sourceMappingURL=selftest.js.map

package/dist/tools/status.js

@@ -1,4 +1,18 @@
 import { z } from "zod";
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join } from "path";
+// The running MCP server's own version (from package.json) — compared against the
+// addon's reported BridgeVersion to catch a stale server vs. a newer addon (or vice
+// versa), the #1 source of "the new tools aren't showing up" confusion.
+let SERVER_VERSION = "unknown";
+try {
+    const pkg = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "..", "package.json"), "utf-8"));
+    SERVER_VERSION = pkg.version ?? "unknown";
+}
+catch {
+    /* best-effort */
+}
 /**
  * Diagnostic and health-check tool (get_bridge_status).
  * Reports connection state, latency, host/port, and editor version.
@@ -10,34 +24,41 @@ export function registerStatusTools(server, bridge) {
         const ipcDir = bridge.getIpcDir();
         const heartbeatAgeMs = bridge.getHeartbeatAgeMs();
         let latencyMs = null;
-        let editorVersion = null;
+        let bridgeVersion = null;
+        let handlerCount = null;
         let roundTripOk = false;
         if (connected) {
             latencyMs = await bridge.ping();
-            // A real round-trip — distinguishes a live editor from one whose
-            // heartbeat is fresh but whose request loop is stalled.
+            // A real round-trip via the addon's get_bridge_status command — distinguishes
+            // a live editor from one whose heartbeat is fresh but whose request loop is
+            // stalled, and surfaces the bridge version + handler count.
             try {
-                const res = await bridge.send("get_project_info", {}, 5000);
+                const res = await bridge.send("get_bridge_status", {}, 5000);
                 roundTripOk = res.success;
                 if (res.success && res.data) {
                     const data = res.data;
-                    editorVersion = data.editorVersion ?? null;
+                    bridgeVersion = data.version ?? null;
+                    handlerCount = data.handlerCount ?? null;
                 }
             }
             catch {
                 // Non-fatal
             }
         }
+        const versionsAligned = bridgeVersion == null || bridgeVersion === SERVER_VERSION;
         const status = {
             connected,
             ipcDir,
             heartbeatAgeMs,
             roundTripOk,
+            bridgeVersion,
+            mcpServerVersion: SERVER_VERSION,
+            versionsAligned,
+            handlerCount,
             latencyMs: connected ? latencyMs : null,
             lastPong: connected
                 ? new Date(bridge.getLastPongTime()).toISOString()
                 : null,
-            editorVersion,
             // legacy/cosmetic — there is no socket; transport is file IPC
             host: bridge.getHost(),
             port: bridge.getPort(),
@@ -47,7 +68,7 @@ export function registerStatusTools(server, bridge) {
             text = `Bridge NOT connected — no recent heartbeat in ${ipcDir}. Is s&box running with the Claude Bridge addon?`;
         }
         else if (roundTripOk) {
-            text = `Bridge connected and responding (IPC: ${ipcDir}, heartbeat ${heartbeatAgeMs ?? "?"}ms ago).`;
+            text = `Bridge connected and responding — addon v${bridgeVersion ?? "?"} / server v${SERVER_VERSION}, ${handlerCount ?? "?"} handlers (IPC: ${ipcDir}, heartbeat ${heartbeatAgeMs ?? "?"}ms ago).${versionsAligned ? "" : ` ⚠️ Version mismatch — restart Claude Code (and/or republish the addon) so the MCP server and addon match.`}`;
         }
         else {
             text = `Bridge heartbeat is live but a test round-trip FAILED — the editor isn't draining requests. IPC: ${ipcDir}. Check the s&box editor console for [SboxBridge] lines.`;

package/dist/tools/templates.js

@@ -8,7 +8,7 @@ import { z } from "zod";
  */
 export function registerTemplateTools(server, bridge) {
     // ── create_player_controller ──────────────────────────────────────
-    server.tool("create_player_controller", "Generate a player controller script with WASD movement, mouse look, jumping, and sprint. Supports first-person and third-person camera modes", {
+    server.tool("create_player_controller", "Generate a player controller script with WASD movement, mouse look, jumping, and sprint. Supports first-person, third-person, and top-down movement modes. Optionally places a player rig (GameObject + CharacterController + Camera) in the scene — note the generated component is attached AFTER a trigger_hotload (it isn't in the TypeLibrary until a recompile)", {
         name: z
             .string()
             .optional()
@@ -18,9 +18,9 @@ export function registerTemplateTools(server, bridge) {
             .optional()
             .describe("Subdirectory under code/ for the file"),
         type: z
-            .enum(["first_person", "third_person"])
+            .enum(["first_person", "third_person", "top_down"])
             .optional()
-            .describe("Camera mode: 'first_person' or 'third_person'. Defaults to 'first_person'"),
+            .describe("Movement mode: 'first_person' (mouse-look body+camera, WASD relative to facing), 'third_person' (mouse yaw, WASD relative to facing, boom camera), or 'top_down' (screen-relative WASD, fixed overhead camera, no jump). Defaults to 'first_person'"),
         moveSpeed: z
             .number()
             .optional()
@@ -28,11 +28,23 @@ export function registerTemplateTools(server, bridge) {
         jumpForce: z
             .number()
             .optional()
-            .describe("Jump force. Defaults to 350"),
+            .describe("Jump force (ignored for top_down). Defaults to 350"),
         sprintMultiplier: z
             .number()
             .optional()
-            .describe("Sprint speed multiplier. Defaults to 1.5"),
+            .describe("Sprint speed multiplier (held 'run' action). Defaults to 1.5"),
+        placeInScene: z
+            .boolean()
+            .optional()
+            .describe("If true, build a player rig in the scene: a GameObject (tagged 'player') with a CharacterController and (unless createCamera=false) a Camera. The generated controller component is NOT attached in this call — trigger_hotload then add_component_with_properties on the returned GameObject. Defaults to false (file-only)."),
+        createCamera: z
+            .boolean()
+            .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() })
+            .optional()
+            .describe("When placeInScene is true, the world position to spawn the player rig at. Defaults to the origin."),
     }, async (params) => {
         const res = await bridge.send("create_player_controller", params);
         if (!res.success) {

package/dist/tools/world.js

@@ -17,13 +17,13 @@ import { z } from "zod";
  */
 export function registerWorldTools(server, bridge) {
     // ── invoke_button ────────────────────────────────────────────────
-    server.tool("invoke_button", "Press a [Button] on a component (e.g. 'Build Terrain' on MapBuilder). Matches by attribute label, then method name. The keystone for driving any component-with-buttons workflow.", {
+    server.tool("invoke_button", "Call a no-argument public method on a component. Matching is tried in order: (1) a [Button] attribute label, (2) the exact method NAME, (3) case-insensitive name with spaces stripped. So this calls ANY parameterless public method, not only [Button]-attributed ones (e.g. 'StartGame' works even without a [Button]). This is the general 'call a component method to drive game state' tool. LIMITATION: parameterless methods only — methods that take arguments are skipped. (list_component_buttons only lists [Button] methods, so a plain method may be invokable yet not appear there.)", {
         component: z
             .string()
-            .describe("Component type name (e.g. 'MapBuilder', 'CaveBuilder')"),
+            .describe("Component type name (e.g. 'MapBuilder', 'SasquatchedGame')"),
         button: z
             .string()
-            .describe("Button label or method name (e.g. 'Build Terrain', 'Generate Forest')"),
+            .describe("A [Button] label OR a public no-arg method name (e.g. 'Build Terrain', 'StartGame'); case- and space-insensitive"),
         id: z
             .string()
             .optional()
@@ -35,7 +35,7 @@ export function registerWorldTools(server, bridge) {
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
     // ── list_component_buttons ───────────────────────────────────────
-    server.tool("list_component_buttons", "List all [Button]s available on a component. Use before invoke_button to discover what's there.", {
+    server.tool("list_component_buttons", "List the [Button]-attributed methods on a component. NOTE: this only finds methods decorated with [Button]; invoke_button can ALSO call any plain public no-arg method by name, so a method missing here may still be invokable. Use describe_type / get_method_signature to find non-button methods.", {
         component: z.string().describe("Component type name"),
         id: z.string().optional().describe("Optional GameObject GUID"),
     }, async (params) => {

package/package.json

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