sbox-mcp-server 1.3.1 → 1.4.0

package/dist/tools/leveltools.js

@@ -0,0 +1,148 @@
+import { z } from "zod";
+/**
+ * Scene & level-building tools (Batch 21): snap-to-ground, align, distribute,
+ * grid-duplicate, and measure. Transform-level operations for arranging a
+ * scene — all verifiable via the editor (screenshot or hierarchy/state).
+ */
+const Vector3Schema = z
+    .object({ x: z.number(), y: z.number(), z: z.number() })
+    .describe("Vector {x,y,z}");
+export function registerLevelTools(server, bridge) {
+    // ── snap_to_ground ─────────────────────────────────────────────────
+    server.tool("snap_to_ground", "Drop a GameObject straight down onto the surface below it (physics raycast). Works best on collider-less props (an object with its own collider may self-hit). Optional offset lifts it off the surface.", {
+        id: z.string().describe("GUID of the GameObject to snap"),
+        offset: z.number().optional().describe("Height above the surface to place it (default 0)"),
+        startHeight: z.number().optional().describe("How far above the object to start the trace (default 2000)"),
+        maxDistance: z.number().optional().describe("Max trace distance downward (default 20000)"),
+    }, async (params) => {
+        const res = await bridge.send("snap_to_ground", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── align_objects ──────────────────────────────────────────────────
+    server.tool("align_objects", "Align several GameObjects on one axis so they share a coordinate. mode = first (match the first object), min, max, or average.", {
+        ids: z.array(z.string()).describe("GUIDs of the GameObjects to align (>= 2)"),
+        axis: z.enum(["x", "y", "z"]).describe("Axis to align on"),
+        mode: z
+            .enum(["first", "min", "max", "average"])
+            .optional()
+            .describe("Target coordinate to align to (default first)"),
+    }, async (params) => {
+        const res = await bridge.send("align_objects", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── distribute_objects ─────────────────────────────────────────────
+    server.tool("distribute_objects", "Evenly space GameObjects along an axis between the lowest and highest (keeps the two ends fixed, spreads the rest evenly).", {
+        ids: z.array(z.string()).describe("GUIDs of the GameObjects to distribute (>= 3)"),
+        axis: z.enum(["x", "y", "z"]).describe("Axis to distribute along"),
+    }, async (params) => {
+        const res = await bridge.send("distribute_objects", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── grid_duplicate ─────────────────────────────────────────────────
+    server.tool("grid_duplicate", "Clone a GameObject into an X/Y/Z grid with fixed spacing (the original stays in place). Each count is clamped to 50 and total clones to 500. Great for fences, crates, pillars, foliage rows.", {
+        id: z.string().describe("GUID of the GameObject to clone"),
+        countX: z.number().int().optional().describe("Copies along X (default 1)"),
+        countY: z.number().int().optional().describe("Copies along Y (default 1)"),
+        countZ: z.number().int().optional().describe("Copies along Z (default 1)"),
+        spacing: Vector3Schema.optional().describe("Spacing between copies per axis (default 100,100,100)"),
+    }, async (params) => {
+        const res = await bridge.send("grid_duplicate", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── measure_distance ───────────────────────────────────────────────
+    server.tool("measure_distance", "Measure the distance between two points or two GameObjects. Provide a/b as {x,y,z} or idA/idB as GUIDs. Returns straight-line distance, horizontal (ground) distance, and the delta vector. Read-only (works during play).", {
+        a: Vector3Schema.optional().describe("First point {x,y,z}"),
+        b: Vector3Schema.optional().describe("Second point {x,y,z}"),
+        idA: z.string().optional().describe("First GameObject GUID (overrides a)"),
+        idB: z.string().optional().describe("Second GameObject GUID (overrides b)"),
+    }, async (params) => {
+        const res = await bridge.send("measure_distance", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── scatter_props ──────────────────────────────────────────────────
+    server.tool("scatter_props", "Scatter N copies of a model randomly within a radius around a center point — instant foliage, rocks, debris. Each copy gets a random yaw and (by default) is snapped to the ground. Seeded for reproducibility; copies are grouped under one parent by default. Count capped at 300.", {
+        model: z.string().describe("Model path to scatter, e.g. 'models/dev/box.vmdl'"),
+        center: Vector3Schema.optional().describe("Centre of the scatter area (default origin)"),
+        radius: z.number().optional().describe("Scatter radius in units (default 256)"),
+        count: z.number().int().optional().describe("How many to place (default 10, max 300)"),
+        randomYaw: z.boolean().optional().describe("Randomly rotate each around Z (default true)"),
+        snapToGround: z.boolean().optional().describe("Raycast each onto the surface below (default true)"),
+        scaleMin: z.number().optional().describe("Min uniform scale (default 1)"),
+        scaleMax: z.number().optional().describe("Max uniform scale (default 1; set >min for size variation)"),
+        tint: z
+            .object({
+            r: z.number().min(0),
+            g: z.number().min(0),
+            b: z.number().min(0),
+            a: z.number().min(0).max(1).optional(),
+        })
+            .optional()
+            .describe("Tint applied to every copy"),
+        seed: z.number().int().optional().describe("PRNG seed for a reproducible layout (default 1)"),
+        group: z.boolean().optional().describe("Parent all copies under one group object (default true)"),
+        name: z.string().optional().describe("Base name for the props/group (default 'Prop')"),
+    }, async (params) => {
+        const res = await bridge.send("scatter_props", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── randomize_transforms ───────────────────────────────────────────
+    server.tool("randomize_transforms", "Add natural variation to existing objects: random yaw and/or random uniform scale within a range. Great for breaking up repetition in placed foliage/rocks/crates. Seeded.", {
+        ids: z.array(z.string()).describe("GUIDs of the GameObjects to randomize"),
+        randomYaw: z.boolean().optional().describe("Randomize Z rotation (default true)"),
+        scaleMin: z.number().optional().describe("Min uniform scale (default 1)"),
+        scaleMax: z.number().optional().describe("Max uniform scale (default 1; set >min to vary)"),
+        seed: z.number().int().optional().describe("PRNG seed (default 1)"),
+    }, async (params) => {
+        const res = await bridge.send("randomize_transforms", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── group_objects ──────────────────────────────────────────────────
+    server.tool("group_objects", "Parent a set of GameObjects under a new empty group object (placed at their centroid) — tidies the hierarchy and lets you move/rotate them together.", {
+        ids: z.array(z.string()).describe("GUIDs of the GameObjects to group"),
+        name: z.string().optional().describe("Name for the group object (default 'Group')"),
+    }, async (params) => {
+        const res = await bridge.send("group_objects", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=leveltools.js.map

package/dist/tools/objecttools.d.ts

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

package/dist/tools/objecttools.js

@@ -0,0 +1,80 @@
+import { z } from "zod";
+/**
+ * Object utility & query tools (Batch 23): find objects in the scene, and
+ * bulk-edit tint / model / tags across one or many objects. find_objects is
+ * the composable workhorse — query GUIDs, then feed them to align/distribute/
+ * set_tint/group/etc.
+ */
+const ColorSchema = z
+    .object({
+    r: z.number().min(0).describe("Red, 0-1"),
+    g: z.number().min(0).describe("Green, 0-1"),
+    b: z.number().min(0).describe("Blue, 0-1"),
+    a: z.number().min(0).max(1).optional().describe("Alpha, 0-1 (default 1)"),
+})
+    .describe("RGBA colour as 0-1 floats");
+export function registerObjectTools(server, bridge) {
+    // ── find_objects ───────────────────────────────────────────────────
+    server.tool("find_objects", "Query the scene for GameObjects by name (case-insensitive substring), component type name, and/or tag — combine filters (AND). Returns {id,name} for matches (limit default 50, max 500). Read-only; works during play. Use it to get GUIDs to feed into align/distribute/set_tint/group/delete/etc.", {
+        name: z.string().optional().describe("Name substring (case-insensitive)"),
+        component: z
+            .string()
+            .optional()
+            .describe("Component type name, e.g. 'PointLight', 'SkinnedModelRenderer'"),
+        tag: z.string().optional().describe("Tag the object must have"),
+        limit: z.number().int().optional().describe("Max results (default 50, max 500)"),
+    }, async (params) => {
+        const res = await bridge.send("find_objects", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── set_tint ───────────────────────────────────────────────────────
+    server.tool("set_tint", "Set the renderer tint colour on one object (id) or many (ids) at once. Works on any ModelRenderer/SkinnedModelRenderer.", {
+        id: z.string().optional().describe("Single GameObject GUID"),
+        ids: z.array(z.string()).optional().describe("Multiple GameObject GUIDs"),
+        tint: ColorSchema.describe("Tint colour to apply"),
+    }, async (params) => {
+        const res = await bridge.send("set_tint", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── replace_model ──────────────────────────────────────────────────
+    server.tool("replace_model", "Swap the model on one object (id) or many (ids) — e.g. retheme a row of props in one call.", {
+        id: z.string().optional().describe("Single GameObject GUID"),
+        ids: z.array(z.string()).optional().describe("Multiple GameObject GUIDs"),
+        model: z.string().describe("New model path, e.g. 'models/dev/sphere.vmdl'"),
+    }, async (params) => {
+        const res = await bridge.send("replace_model", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── set_tags ───────────────────────────────────────────────────────
+    server.tool("set_tags", "Add, remove, and/or clear gameplay tags on one object (id) or many (ids). Tags drive collision groups, queries, and triggers.", {
+        id: z.string().optional().describe("Single GameObject GUID"),
+        ids: z.array(z.string()).optional().describe("Multiple GameObject GUIDs"),
+        add: z.array(z.string()).optional().describe("Tags to add"),
+        remove: z.array(z.string()).optional().describe("Tags to remove"),
+        clear: z.boolean().optional().describe("Remove all existing tags first"),
+    }, async (params) => {
+        const res = await bridge.send("set_tags", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=objecttools.js.map

package/dist/tools/status.js

@@ -6,14 +6,18 @@ export function registerStatusTools(server, bridge) {
     // ── get_bridge_status ────────────────────────────────────────────
     server.tool("get_bridge_status", "Check the connection status to the s&box Bridge — whether it's connected, latency, host/port, and editor info. Useful for debugging", {}, async () => {
         const connected = bridge.isConnected();
-        let latencyMs = -1;
+        const ipcDir = bridge.getIpcDir();
+        const heartbeatAgeMs = bridge.getHeartbeatAgeMs();
+        let latencyMs = null;
         let editorVersion = null;
+        let roundTripOk = false;
         if (connected) {
-            // Measure round-trip ping
             latencyMs = await bridge.ping();
-            // Try to get editor version via project info
+            // A real round-trip — distinguishes a live editor from one whose
+            // heartbeat is fresh but whose request loop is stalled.
             try {
                 const res = await bridge.send("get_project_info", {}, 5000);
+                roundTripOk = res.success;
                 if (res.success && res.data) {
                     const data = res.data;
                     editorVersion = data.editorVersion ?? null;
@@ -25,17 +29,28 @@ export function registerStatusTools(server, bridge) {
         }
         const status = {
             connected,
-            host: bridge.getHost(),
-            port: bridge.getPort(),
+            ipcDir,
+            heartbeatAgeMs,
+            roundTripOk,
             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(),
         };
-        const text = connected
-            ? `Bridge connected (${bridge.getHost()}:${bridge.getPort()}, ${latencyMs}ms latency)`
-            : `Bridge NOT connected (${bridge.getHost()}:${bridge.getPort()}). Is s&box running?`;
+        let text;
+        if (!connected) {
+            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).`;
+        }
+        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.`;
+        }
         return {
             content: [
                 {

package/dist/tools/visuals.d.ts

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

package/dist/tools/visuals.js

@@ -0,0 +1,259 @@
+import { z } from "zod";
+/**
+ * Visual & atmosphere tools (Batch 17): lighting, post-processing, fog, sky,
+ * reflection probes, and compose-it-all presets.
+ *
+ * These wrap s&box's visual components with sensible parameters so Claude can
+ * author scene mood directly, instead of hand-driving add_component_with_properties
+ * (which can't even set a Color). After any change, screenshot the scene and read
+ * the result — this layer is where the screenshot loop matters most.
+ */
+const ColorSchema = z
+    .object({
+    r: z.number().min(0).describe("Red, 0-1"),
+    g: z.number().min(0).describe("Green, 0-1"),
+    b: z.number().min(0).describe("Blue, 0-1"),
+    a: z.number().min(0).max(1).optional().describe("Alpha, 0-1 (default 1)"),
+})
+    .describe("RGBA colour as 0-1 floats");
+const Vector3Schema = z
+    .object({ x: z.number(), y: z.number(), z: z.number() })
+    .describe("World position {x,y,z}");
+const RotationSchema = z
+    .object({ pitch: z.number(), yaw: z.number(), roll: z.number() })
+    .describe("Rotation {pitch,yaw,roll} in degrees");
+export function registerVisualTools(server, bridge) {
+    // ── add_light ──────────────────────────────────────────────────────
+    server.tool("add_light", "Add a light to the active scene. NOTE: s&box lights have no separate brightness field — intensity is the colour magnitude, so 'brightness' scales the colour (use >1 for bright/HDR). Types: directional = sun (aim it with rotation), point = omni-directional (range), spot = cone (range + coneInner/coneOuter degrees), ambient = global fill light.", {
+        type: z
+            .enum(["directional", "point", "spot", "ambient"])
+            .describe("Light type"),
+        name: z.string().optional().describe("GameObject name"),
+        color: ColorSchema.optional().describe("Light colour (default white)"),
+        brightness: z
+            .number()
+            .optional()
+            .describe("Intensity multiplier on the colour (default 1; try 2-10 for point/spot)"),
+        range: z
+            .number()
+            .optional()
+            .describe("point/spot only: falloff radius in units (maps to Radius)"),
+        coneInner: z
+            .number()
+            .optional()
+            .describe("spot only: inner cone angle in degrees"),
+        coneOuter: z
+            .number()
+            .optional()
+            .describe("spot only: outer cone angle in degrees"),
+        shadows: z.boolean().optional().describe("Cast shadows (default true)"),
+        skyColor: ColorSchema.optional().describe("directional only: ambient sky colour for the upper hemisphere"),
+        position: Vector3Schema.optional().describe("World position"),
+        rotation: RotationSchema.optional().describe("World rotation — sets the aim direction for directional/spot lights"),
+        parentId: z.string().optional().describe("GUID of a parent GameObject"),
+    }, async (params) => {
+        const res = await bridge.send("add_light", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── set_fog ────────────────────────────────────────────────────────
+    server.tool("set_fog", "Add or update distance fog in the active scene. v1 supports gradient fog (atmospheric distance haze — great for mood/horror). Re-running on the same target updates it rather than duplicating.", {
+        type: z
+            .enum(["gradient"])
+            .optional()
+            .describe("Fog type (default gradient; cubemap/volumetric coming later)"),
+        name: z.string().optional().describe("GameObject name when creating a new fog object"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of an existing GameObject to host the fog (else a new 'Gradient Fog' object is created)"),
+        color: ColorSchema.optional().describe("Fog colour"),
+        startDistance: z
+            .number()
+            .optional()
+            .describe("Distance (units) where fog begins"),
+        endDistance: z
+            .number()
+            .optional()
+            .describe("Distance (units) where fog reaches full density"),
+        height: z.number().optional().describe("World height the fog settles around"),
+        falloff: z
+            .number()
+            .optional()
+            .describe("Distance falloff exponent (higher = sharper onset)"),
+    }, async (params) => {
+        const res = await bridge.send("set_fog", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── add_post_process ─────────────────────────────────────────────────
+    server.tool("add_post_process", "Add (or update) a post-processing effect on the scene's main camera (auto-enables post-processing). Generic: pass the effect component name + any of its properties. Examples — Bloom {Strength, Threshold, Tint}, Tonemapping, ColorAdjustments {Saturation, Brightness, Contrast}, Vignette {Intensity, Color}, FilmGrain, DepthOfField, ChromaticAberration, MotionBlur, Sharpen, AmbientOcclusion. Call describe_type <Effect> to discover a given effect's properties.", {
+        effect: z
+            .string()
+            .describe("Post-process component type name, e.g. 'Bloom', 'Vignette', 'ColorAdjustments'"),
+        properties: z
+            .record(z.any())
+            .optional()
+            .describe("Property name -> value. Floats/ints/bools as numbers/bools, colours as {r,g,b,a}, enums as their string name."),
+        cameraId: z
+            .string()
+            .optional()
+            .describe("GUID of a specific camera GameObject (default: the scene's main camera)"),
+    }, async (params) => {
+        const res = await bridge.send("add_post_process", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── set_skybox ───────────────────────────────────────────────────────
+    server.tool("set_skybox", "Set the scene's 2D skybox tint / indirect lighting (re-uses an existing SkyBox2D or creates one). Darken the tint for night/dusk. Optionally point it at a .vmat sky material.", {
+        tint: ColorSchema.optional().describe("Sky tint colour"),
+        indirectLighting: z
+            .boolean()
+            .optional()
+            .describe("Whether the sky contributes indirect/ambient light"),
+        material: z.string().optional().describe("Path to a .vmat sky material (optional)"),
+        name: z.string().optional().describe("Name for the sky GameObject if one is created"),
+    }, async (params) => {
+        const res = await bridge.send("set_skybox", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── apply_atmosphere (preset) ─────────────────────────────────────────
+    server.tool("apply_atmosphere", "One-call scene mood: composes ambient + directional light, gradient fog, and a camera post-fx stack (tonemap + colour grade + vignette) tuned for the chosen mood. Idempotent — re-runs update the same 'Atmosphere *' objects.", {
+        mood: z
+            .enum(["horror-night", "foggy-dawn", "overcast", "warm-interior"])
+            .describe("Atmosphere preset"),
+    }, async (params) => {
+        const res = await bridge.send("apply_atmosphere", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── apply_post_fx_look (preset) ───────────────────────────────────────
+    server.tool("apply_post_fx_look", "Apply just a camera post-processing look (no lights/fog): cinematic (tonemap + bloom + soft vignette), filmic-horror (desaturated, high-contrast, heavy vignette, film grain), or clean (tonemap only).", {
+        look: z
+            .enum(["cinematic", "filmic-horror", "clean"])
+            .describe("Post-fx look preset"),
+    }, async (params) => {
+        const res = await bridge.send("apply_post_fx_look", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── add_envmap_probe ─────────────────────────────────────────────────
+    server.tool("add_envmap_probe", "Add an environment reflection/ambient probe (EnvmapProbe) at a position with a cubic influence volume — captures local reflections and indirect light for nearby surfaces.", {
+        name: z.string().optional().describe("GameObject name"),
+        position: Vector3Schema.optional().describe("World position (centre of the probe)"),
+        size: z.number().optional().describe("Cubic influence size in units (default 1024)"),
+        tint: ColorSchema.optional().describe("Tint applied to the captured environment"),
+        feathering: z
+            .number()
+            .optional()
+            .describe("Edge feathering 0-1 for blending between overlapping probes"),
+    }, async (params) => {
+        const res = await bridge.send("add_envmap_probe", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── spawn_particle (Batch 18: VFX) ───────────────────────────────────
+    server.tool("spawn_particle", "Spawn an additive particle effect (no texture asset needed): kind = fire (rising flame), embers (slow drifting glow), or sparks (a one-shot burst). Renders as tinted glowing dots — great for campfires, torches, and impacts. (smoke needs a soft sprite; not in v1.)", {
+        kind: z
+            .enum(["fire", "embers", "sparks", "magic", "dust", "blood", "snow"])
+            .describe("Particle preset"),
+        position: Vector3Schema.optional().describe("World position"),
+        color: ColorSchema.optional().describe("Override the particle tint"),
+        name: z.string().optional().describe("GameObject name"),
+    }, async (params) => {
+        const res = await bridge.send("spawn_particle", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── add_trail ────────────────────────────────────────────────────────
+    server.tool("add_trail", "Attach a motion trail (TrailRenderer) to an existing GameObject (via targetId) so it leaves a trail as it moves — or create a standalone trail object. Only visible while the object is moving.", {
+        targetId: z.string().optional().describe("GUID of the GameObject to attach the trail to (else a new 'Trail' object is made)"),
+        position: Vector3Schema.optional().describe("World position when creating a standalone trail"),
+        lifetime: z.number().optional().describe("How long (seconds) trail points persist"),
+        maxPoints: z.number().optional().describe("Max points in the trail"),
+        pointDistance: z.number().optional().describe("Min distance between trail points"),
+        name: z.string().optional().describe("GameObject name when creating a new one"),
+    }, async (params) => {
+        const res = await bridge.send("add_trail", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── add_beam ─────────────────────────────────────────────────────────
+    server.tool("add_beam", "Create an energy/laser beam (BeamEffect) from a position to a target point — additive, tintable. Good for lasers, tracers, magic beams.", {
+        position: Vector3Schema.optional().describe("Beam start (world position of the beam object)"),
+        target: Vector3Schema.optional().describe("Beam end point in world space (default: 128u up)"),
+        width: z.number().optional().describe("Beam width/scale (default 4)"),
+        color: ColorSchema.optional().describe("Beam colour (default white)"),
+        name: z.string().optional().describe("GameObject name"),
+    }, async (params) => {
+        const res = await bridge.send("add_beam", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── create_particle_effect (generic / raw params) ────────────────────
+    server.tool("create_particle_effect", "Build a custom additive particle effect from raw params (ParticleEffect + cone emitter + sprite renderer). Use this when the spawn_particle presets aren't what you want. Texture-free (additive Texture.White glow).", {
+        position: Vector3Schema.optional().describe("World position"),
+        color: ColorSchema.optional().describe("Particle tint (default white)"),
+        rate: z.number().optional().describe("Particles per second when looping (default 30)"),
+        burst: z.number().optional().describe("Particle count for a one-shot burst when loop=false (default 30)"),
+        loop: z.boolean().optional().describe("Continuous emission (default true) vs a single burst"),
+        lifetime: z.number().optional().describe("Particle lifetime in seconds (default 2)"),
+        size: z.number().optional().describe("Particle size (default 4)"),
+        speed: z.number().optional().describe("Emission speed along the cone (default 100)"),
+        coneAngle: z.number().optional().describe("Cone half-angle in degrees; ~85 ≈ hemisphere (default 40)"),
+        gravity: z.number().optional().describe("Downward force (default 0 = none)"),
+        additive: z.boolean().optional().describe("Additive (glow) blending (default true)"),
+        maxParticles: z.number().optional().describe("Max live particles (default 500)"),
+        name: z.string().optional().describe("GameObject name"),
+    }, async (params) => {
+        const res = await bridge.send("create_particle_effect", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=visuals.js.map

package/dist/transport/bridge-client.d.ts

@@ -1,11 +1,40 @@
 /**
- * File-based IPC transport for communicating with the s&box Bridge Addon.
+ * Max age of the editor's status heartbeat before we consider the bridge dead.
+ * The addon refreshes the heartbeat roughly once per second from its frame
+ * loop, so this gives generous margin for GC pauses / frame hitches while still
+ * catching a closed, crashed, or frame-stalled editor within a few seconds.
+ */
+export declare const STATUS_STALE_MS = 5000;
+/** Resolve the IPC directory, honoring an explicit override. */
+export declare function resolveIpcDir(): string;
+/** Result of inspecting the editor's status.json heartbeat. */
+export interface StatusClassification {
+    /** The editor reported `running: true`. */
+    running: boolean;
+    /** The heartbeat is recent enough to trust (or the addon predates heartbeats). */
+    fresh: boolean;
+    /** Age of the heartbeat in ms, or null if the addon doesn't emit one. */
+    heartbeatMs: number | null;
+}
+/**
+ * Decide whether a parsed status.json means the bridge is live.
  *
- * Instead of WebSocket, this uses a shared temp directory where:
- * - MCP server writes request files (req_*.json)
- * - s&box addon polls for them, processes, and writes response files (res_*.json)
- * - MCP server polls for response files
+ * A recent heartbeat → fresh. A stale heartbeat → not fresh (editor closed,
+ * crashed, or frame loop stalled). No heartbeat field at all → treated as fresh
+ * for backward compatibility with addons built before v1.3.2 (so upgrading the
+ * MCP server alone never regresses a working setup to "disconnected").
  */
+export declare function classifyStatus(status: unknown, nowMs: number, staleMs: number): StatusClassification;
+/**
+ * Build a timeout error that names WHICH side of the IPC broke, so a 30s hang
+ * is actionable instead of opaque.
+ */
+export declare function describeTimeout(opts: {
+    reqConsumed: boolean;
+    ipcDir: string;
+    timeoutMs: number;
+    command: string;
+}): string;
 /** A single command request sent to the s&box Bridge. */
 export interface BridgeRequest {
     id: string;
@@ -32,8 +61,16 @@ export declare class BridgeClient {
     static readonly POLL_INTERVAL_MS = 50;
     static readonly STATUS_CHECK_INTERVAL_MS = 5000;
     constructor(host?: string, port?: number);
+    /** The directory this client reads/writes IPC files in. */
+    getIpcDir(): string;
+    private statusPath;
+    /** Read + classify the editor's status heartbeat. Never throws. */
+    readStatus(): StatusClassification;
+    /** Age of the editor's last heartbeat in ms, or null if unavailable. */
+    getHeartbeatAgeMs(): number | null;
     /**
-     * Check if the s&box Bridge is running by looking for the status file.
+     * Verify the s&box Bridge is live (recent heartbeat), throwing a specific
+     * error if it is missing or stale.
      */
     connect(): Promise<void>;
     /**
@@ -48,7 +85,7 @@ export declare class BridgeClient {
         params?: Record<string, unknown>;
     }>, timeoutMs?: number): Promise<BridgeResponse>;
     /**
-     * Check if bridge is alive by looking for status file.
+     * Liveness check. Returns elapsed ms if the heartbeat is recent, else -1.
      */
     ping(): Promise<number>;
     isConnected(): boolean;