sbox-mcp-server 1.6.0 → 1.7.0

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/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

@@ -455,5 +455,31 @@ export function registerDiagnosticTools(server, bridge) {
         };
         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.6.0",
+  "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",