sbox-mcp-server 1.3.2 → 1.4.0

package/README.md

@@ -1,113 +1,119 @@
-# sbox-mcp-server
-
-MCP Server for the s&box game engine. Lets Claude Code build s&box games through conversation — 99 working tools for scenes, scripts, GameObjects, components, assets, materials, audio, physics, UI, networking, publishing, world-gen, and type discovery.
-
-## Fastest install — the Claude Code plugin
-
-If you use Claude Code, the easiest install is the companion plugin. It registers this MCP server automatically, ships a workflow skill, and includes the `sbox-game-dev` specialist agent.
-
-```
-/plugin marketplace add LouSputthole/Sbox-Claude
-/plugin install sbox-claude
-```
-
-You still need to install the s&box-side **bridge addon** into your project's `Libraries/` folder (see step 1 below). The plugin handles the Claude side; the addon handles the s&box side.
-
-## Manual install — three steps
-
-### 1. Install the bridge addon in s&box
-
-The bridge addon runs inside the s&box editor and receives commands from this MCP server. It MUST live inside a project's `Libraries/` folder — putting it in s&box's global `addons/` will silently fail to compile.
-
-```powershell
-git clone https://github.com/LouSputthole/Sbox-Claude.git
-cd Sbox-Claude
-.\install.ps1 -RemoveStaleAddons      # Windows, auto-detects your s&box project
-./install.sh --remove-stale            # Linux/Mac/WSL
-```
-
-See [INSTALL.md](https://github.com/LouSputthole/Sbox-Claude/blob/main/INSTALL.md) for the full guide and manual fallback.
-
-### 2. Register the MCP server with Claude Code
-
-```bash
-claude mcp add sbox -- npx sbox-mcp-server
-```
-
-This is the bare command — equivalent to what the plugin's `.mcp.json` does for you.
-
-### 3. Open s&box
-
-Open your project. The bridge starts automatically. Verify with:
-
-```
-Check the bridge status.
-```
-
-You should see `connected: true, handlerCount: 99`.
-
-## How it works
-
-```
-Claude Code → (stdio) → sbox-mcp-server → (file IPC) → bridge addon → s&box editor
-```
-
-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 (99 working)
-
-| Category | Tools |
-|----------|-------|
-| **Project** | get_project_info, list_project_files, read_file, write_file |
-| **Scripts** | create_script, edit_script, delete_script, trigger_hotload |
-| **Scenes** | list_scenes, load_scene, save_scene, create_scene |
-| **GameObjects** | create/delete/duplicate/rename, set_parent/enabled/transform |
-| **Components** | get/set_property, get_all_properties, list_available, add_component, set_prefab_ref |
-| **Hierarchy** | get_scene_hierarchy (with `maxDepth` + `rootId`), get/select/focus_object |
-| **Assets** | search_assets, list_asset_library, install_asset, get_asset_info |
-| **Materials** | assign_model, create/assign_material, set_material_property |
-| **Audio** | list_sounds, create_sound_event, assign_sound, play_sound_preview |
-| **Play Mode** | start/stop_play, is_playing |
-| **Runtime** | get/set_runtime_property, take_screenshot |
-| **Editor** | undo, redo |
-| **Prefabs** | create/instantiate_prefab, list_prefabs, get_prefab_info |
-| **Physics** | add_physics, add_collider, add_joint, raycast |
-| **UI** | create_razor_ui, add_screen_panel, add_world_panel |
-| **Templates** | create_player/npc_controller, create_game_manager, create_trigger_zone |
-| **Networking** | network_helper, configure/status, spawn, ownership, sync, RPCs, lobby/event templates |
-| **Publishing** | project_config, validate, thumbnail, package_details |
-| **World gen** | invoke_button, list_component_buttons, raycast_terrain, build_terrain_mesh |
-| **Map edit** | add_terrain_hill/clearing/trail, clear_terrain_features, sculpt_terrain |
-| **Caves / Forest** | add_cave_waypoint, clear_cave_path, add_forest_poi/trail, set_forest_seed, clear_forest_pois, paint_forest_density |
-| **Placement** | place_along_path |
-| **Discovery** | describe_type, search_types, get_method_signature, find_in_project |
-| **Status** | get_bridge_status |
-
-## Working with Claude effectively
-
-Two disciplines prevent the iteration-loop trap:
-
-1. **After visual changes, call `take_screenshot` and read the PNG.** Claude is a multimodal model — it can see the result. Guessing about visual outcomes from code alone produces long iteration loops.
-2. **Before writing code that touches an unfamiliar s&box type, call `describe_type` or `search_types`.** Reflection is the source of truth; training data goes stale across SDK versions.
-
-The companion plugin's `sbox-build-feature` skill encodes this workflow plus the common gotchas. If you're not using the plugin, the same rules apply manually.
-
-## Requirements
-
-- **Node.js 18+**
-- **s&box** with the bridge addon installed in your project's `Libraries/` folder
-- **Claude Code**
-
-## Documentation
-
-- [Main README](https://github.com/LouSputthole/Sbox-Claude/blob/main/README.md) — full project overview
-- [INSTALL.md](https://github.com/LouSputthole/Sbox-Claude/blob/main/INSTALL.md) — install + manual fallback
-- [TROUBLESHOOTING.md](https://github.com/LouSputthole/Sbox-Claude/blob/main/TROUBLESHOOTING.md) — 10 most common failures
-- [CHANGELOG.md](https://github.com/LouSputthole/Sbox-Claude/blob/main/CHANGELOG.md) — release history
-- [Plugin README](https://github.com/LouSputthole/Sbox-Claude/blob/main/plugins/sbox-claude/README.md) — Claude Code plugin docs
-
-## License
-
-**GPL-3.0** — see [LICENSE](../LICENSE) for details.
-
-Copyright (c) 2026 [sboxskins.gg](https://sboxskins.gg)
+# sbox-mcp-server
+
+MCP Server for the s&box game engine. Lets Claude Code build s&box games through conversation — 131 working tools for scenes, scripts, GameObjects, components, assets, materials, audio, physics, UI, networking, publishing, world-gen, lighting & atmosphere, characters, scene layout, and type discovery.
+
+## Fastest install — the Claude Code plugin
+
+If you use Claude Code, the easiest install is the companion plugin. It registers this MCP server automatically, ships a workflow skill, and includes the `sbox-game-dev` specialist agent.
+
+```
+/plugin marketplace add LouSputthole/Sbox-Claude
+/plugin install sbox-claude
+```
+
+You still need to install the s&box-side **bridge addon** into your project's `Libraries/` folder (see step 1 below). The plugin handles the Claude side; the addon handles the s&box side.
+
+## Manual install — three steps
+
+### 1. Install the bridge addon in s&box
+
+The bridge addon runs inside the s&box editor and receives commands from this MCP server. It MUST live inside a project's `Libraries/` folder — putting it in s&box's global `addons/` will silently fail to compile.
+
+```powershell
+git clone https://github.com/LouSputthole/Sbox-Claude.git
+cd Sbox-Claude
+.\install.ps1 -RemoveStaleAddons      # Windows, auto-detects your s&box project
+./install.sh --remove-stale            # Linux/Mac/WSL
+```
+
+See [INSTALL.md](https://github.com/LouSputthole/Sbox-Claude/blob/main/INSTALL.md) for the full guide and manual fallback.
+
+### 2. Register the MCP server with Claude Code
+
+```bash
+claude mcp add sbox -- npx sbox-mcp-server
+```
+
+This is the bare command — equivalent to what the plugin's `.mcp.json` does for you.
+
+### 3. Open s&box
+
+Open your project. The bridge starts automatically. Verify with:
+
+```
+Check the bridge status.
+```
+
+You should see `connected: true, handlerCount: 99`.
+
+## How it works
+
+```
+Claude Code → (stdio) → sbox-mcp-server → (file IPC) → bridge addon → s&box editor
+```
+
+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 (131 — v1.4.0)
+
+| Category | Tools |
+|----------|-------|
+| **Project** | get_project_info, list_project_files, read_file, write_file |
+| **Scripts** | create_script, edit_script, delete_script, trigger_hotload |
+| **Scenes** | list_scenes, load_scene, save_scene, create_scene |
+| **GameObjects** | create/delete/duplicate/rename, set_parent/enabled/transform |
+| **Components** | get/set_property, get_all_properties, list_available, add_component, set_prefab_ref |
+| **Hierarchy** | get_scene_hierarchy (with `maxDepth` + `rootId`), get/select/focus_object |
+| **Assets** | search_assets, list_asset_library, install_asset, get_asset_info |
+| **Materials** | assign_model, create/assign_material, set_material_property |
+| **Audio** | list_sounds, create_sound_event, assign_sound, play_sound_preview |
+| **Play Mode** | start/stop_play, is_playing |
+| **Runtime** | get/set_runtime_property, take_screenshot |
+| **Editor** | undo, redo |
+| **Prefabs** | create/instantiate_prefab, list_prefabs, get_prefab_info |
+| **Physics** | add_physics, add_collider, add_joint, raycast |
+| **UI** | create_razor_ui, add_screen_panel, add_world_panel |
+| **Templates** | create_player/npc_controller, create_game_manager, create_trigger_zone |
+| **Networking** | network_helper, configure/status, spawn, ownership, sync, RPCs, lobby/event templates |
+| **Publishing** | project_config, validate, thumbnail, package_details |
+| **World gen** | invoke_button, list_component_buttons, raycast_terrain, build_terrain_mesh |
+| **Map edit** | add_terrain_hill/clearing/trail, clear_terrain_features, sculpt_terrain |
+| **Caves / Forest** | add_cave_waypoint, clear_cave_path, add_forest_poi/trail, set_forest_seed, clear_forest_pois, paint_forest_density |
+| **Placement** | place_along_path |
+| **Discovery** | describe_type, search_types, get_method_signature, find_in_project |
+| **Status** | get_bridge_status |
+| **Visual & atmosphere** *(v1.4.0)* | add_light, set_fog, add_post_process, set_skybox, add_envmap_probe, apply_atmosphere, apply_post_fx_look |
+| **Characters** *(v1.4.0)* | spawn_model, spawn_citizen, dress_citizen, set_bodygroup, pose_citizen, equip_model, set_look_at, add_ragdoll, set_expression |
+| **Scene & level** *(v1.4.0)* | snap_to_ground, align_objects, distribute_objects, grid_duplicate, measure_distance |
+| **Environment** *(v1.4.0)* | scatter_props, randomize_transforms, group_objects |
+| **Object utilities** *(v1.4.0)* | find_objects, set_tint, replace_model, set_tags |
+| **VFX** *(v1.4.0, experimental)* | spawn_particle, create_particle_effect, add_trail, add_beam — compile but runtime rendering unverified through the bridge; use a legacy `.vpcf` for visible particles |
+
+## Working with Claude effectively
+
+Two disciplines prevent the iteration-loop trap:
+
+1. **After visual changes, call `take_screenshot` and read the PNG.** Claude is a multimodal model — it can see the result. Guessing about visual outcomes from code alone produces long iteration loops.
+2. **Before writing code that touches an unfamiliar s&box type, call `describe_type` or `search_types`.** Reflection is the source of truth; training data goes stale across SDK versions.
+
+The companion plugin's `sbox-build-feature` skill encodes this workflow plus the common gotchas. If you're not using the plugin, the same rules apply manually.
+
+## Requirements
+
+- **Node.js 18+**
+- **s&box** with the bridge addon installed in your project's `Libraries/` folder
+- **Claude Code**
+
+## Documentation
+
+- [Main README](https://github.com/LouSputthole/Sbox-Claude/blob/main/README.md) — full project overview
+- [INSTALL.md](https://github.com/LouSputthole/Sbox-Claude/blob/main/INSTALL.md) — install + manual fallback
+- [TROUBLESHOOTING.md](https://github.com/LouSputthole/Sbox-Claude/blob/main/TROUBLESHOOTING.md) — 10 most common failures
+- [CHANGELOG.md](https://github.com/LouSputthole/Sbox-Claude/blob/main/CHANGELOG.md) — release history
+- [Plugin README](https://github.com/LouSputthole/Sbox-Claude/blob/main/plugins/sbox-claude/README.md) — Claude Code plugin docs
+
+## License
+
+**GPL-3.0** — see [LICENSE](../LICENSE) for details.
+
+Copyright (c) 2026 [sboxskins.gg](https://sboxskins.gg)

package/dist/index.js

@@ -33,6 +33,10 @@ import { registerNetworkingTools } from "./tools/networking.js";
 import { registerPublishingTools } from "./tools/publishing.js";
 import { registerWorldTools } from "./tools/world.js";
 import { registerDiscoveryTools } from "./tools/discovery.js";
+import { registerVisualTools } from "./tools/visuals.js";
+import { registerCharacterTools } from "./tools/characters.js";
+import { registerLevelTools } from "./tools/leveltools.js";
+import { registerObjectTools } from "./tools/objecttools.js";
 // ── CLI flags ──────────────────────────────────────────────────────
 const args = process.argv.slice(2);
 /** Read the package version from package.json, or return "unknown" on failure. */
@@ -68,7 +72,7 @@ ENVIRONMENT VARIABLES
 CONNECT TO CLAUDE CODE
   claude mcp add sbox -- node /path/to/sbox-mcp-server/dist/index.js
 
-TOOLS (99 working — was 109; 10 unimplementable tools removed in v1.3.0)
+TOOLS (131 — +32 in v1.4.0: visual, characters, scene, environment, utilities)
   Project:     get_project_info, list_project_files, read_file, write_file
   Scripts:     create_script, edit_script, delete_script, trigger_hotload
   Scenes:      list_scenes, load_scene, save_scene, create_scene
@@ -95,6 +99,14 @@ TOOLS (99 working — was 109; 10 unimplementable tools removed in v1.3.0)
   Placement:   place_along_path
   Discovery:   describe_type, search_types, get_method_signature, find_in_project
   Status:      get_bridge_status
+
+  ── New in v1.4.0 ───────────────────────────────────
+  Visual:      add_light, set_fog, add_post_process, set_skybox, add_envmap_probe, apply_atmosphere, apply_post_fx_look
+  Characters:  spawn_model, spawn_citizen, dress_citizen, set_bodygroup, pose_citizen, equip_model, set_look_at, add_ragdoll, set_expression
+  Scene:       snap_to_ground, align_objects, distribute_objects, grid_duplicate, measure_distance
+  Environment: scatter_props, randomize_transforms, group_objects
+  Utilities:   find_objects, set_tint, replace_model, set_tags
+  VFX (exp):   spawn_particle, create_particle_effect, add_trail, add_beam
 `);
     process.exit(0);
 }
@@ -148,6 +160,10 @@ registerNetworkingTools(server, bridge);
 registerPublishingTools(server, bridge);
 registerWorldTools(server, bridge);
 registerDiscoveryTools(server, bridge);
+registerVisualTools(server, bridge);
+registerCharacterTools(server, bridge);
+registerLevelTools(server, bridge);
+registerObjectTools(server, bridge);
 /** Start the MCP server on stdio and attempt initial Bridge connection. */
 async function main() {
     const transport = new StdioServerTransport();

package/dist/tools/characters.d.ts

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

package/dist/tools/characters.js

@@ -0,0 +1,209 @@
+import { z } from "zod";
+/**
+ * Character & model tools (Batch 19): spawn world models, spawn animated
+ * Citizen characters, dress them with clothing, toggle bodygroups, and pose
+ * them via CitizenAnimationHelper.
+ *
+ * Unlike particles (Batch 18), everything here is a STATIC mesh/pose that
+ * renders in the editor viewport — so the screenshot loop works: after a
+ * change, take_screenshot and read the result. Animation *playback* is
+ * runtime, but poses preview in-editor via PlayAnimationsInEditorScene.
+ */
+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 (model tint)");
+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 registerCharacterTools(server, bridge) {
+    // ── spawn_model ────────────────────────────────────────────────────
+    server.tool("spawn_model", "Spawn a GameObject with a ModelRenderer showing a model — the quick way to place a prop. Pass an engine/project model path (e.g. 'models/citizen/citizen.vmdl', 'models/dev/box.vmdl'). Cloud (sbox.game) models must be installed first via install_asset, then pass the resulting path. Add physics separately with add_collider/add_physics if needed.", {
+        model: z
+            .string()
+            .describe("Model path, e.g. 'models/dev/box.vmdl' or an installed model path"),
+        name: z.string().optional().describe("GameObject name"),
+        position: Vector3Schema.optional().describe("World position"),
+        rotation: RotationSchema.optional().describe("World rotation"),
+        scale: Vector3Schema.optional().describe("World scale (default 1,1,1)"),
+        tint: ColorSchema.optional().describe("Model tint colour"),
+        parentId: z.string().optional().describe("GUID of a parent GameObject"),
+    }, async (params) => {
+        const res = await bridge.send("spawn_model", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── spawn_citizen ──────────────────────────────────────────────────
+    server.tool("spawn_citizen", "Spawn an animated Citizen character: a SkinnedModelRenderer with the Citizen model, plus (by default) a CitizenAnimationHelper so it idles. PlayAnimationsInEditorScene is enabled so the idle pose shows in the editor view (screenshot-verifiable). Dress it afterward with dress_citizen, pose it with pose_citizen.", {
+        name: z.string().optional().describe("GameObject name (default 'Citizen')"),
+        model: z
+            .string()
+            .optional()
+            .describe("Override the skinned model (default 'models/citizen/citizen.vmdl')"),
+        position: Vector3Schema.optional().describe("World position"),
+        rotation: RotationSchema.optional().describe("World rotation"),
+        scale: Vector3Schema.optional().describe("World scale (default 1,1,1)"),
+        tint: ColorSchema.optional().describe("Body tint colour"),
+        animator: z
+            .boolean()
+            .optional()
+            .describe("Add a CitizenAnimationHelper for idle/pose (default true)"),
+        holdType: z
+            .string()
+            .optional()
+            .describe("Initial hold pose, e.g. None, Pistol, Rifle, Shotgun, HoldItem, Punch, Swing"),
+        moveStyle: z
+            .string()
+            .optional()
+            .describe("Movement style, e.g. Auto, Walk, Run"),
+        parentId: z.string().optional().describe("GUID of a parent GameObject"),
+    }, async (params) => {
+        const res = await bridge.send("spawn_citizen", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── dress_citizen ──────────────────────────────────────────────────
+    server.tool("dress_citizen", "Dress a spawned Citizen (or any GameObject with a SkinnedModelRenderer) by applying .clothing resources. Pass an array of clothing resource paths; they're loaded, added to a ClothingContainer, and applied to the body. Returns which paths applied vs were not found.", {
+        id: z.string().describe("GUID of the Citizen GameObject"),
+        clothing: z
+            .array(z.string())
+            .describe("Clothing resource paths, e.g. ['models/citizen_clothes/jacket/jacket.clothing']"),
+        tint: z
+            .number()
+            .min(0)
+            .max(1)
+            .optional()
+            .describe("ClothingContainer tint position 0-1 (skin/clothing colour variation)"),
+    }, async (params) => {
+        const res = await bridge.send("dress_citizen", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── set_bodygroup ──────────────────────────────────────────────────
+    server.tool("set_bodygroup", "Show/hide a bodygroup on a SkinnedModelRenderer (e.g. hide hands when holding a tool, swap head variants). Provide value (int index) or choice (string name).", {
+        id: z.string().describe("GUID of the GameObject with a SkinnedModelRenderer"),
+        name: z.string().describe("Bodygroup name"),
+        value: z.number().int().optional().describe("Bodygroup choice index"),
+        choice: z.string().optional().describe("Bodygroup choice by name (alternative to value)"),
+    }, async (params) => {
+        const res = await bridge.send("set_bodygroup", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── pose_citizen ───────────────────────────────────────────────────
+    server.tool("pose_citizen", "Pose a Citizen by setting CitizenAnimationHelper params (enables PlayAnimationsInEditorScene so the pose shows in-editor). Set holdType (None/Pistol/Rifle/Shotgun/HoldItem/Punch/Swing), moveStyle (Auto/Walk/Run), specialMove, sitting (bool), and/or duckLevel (0-1).", {
+        id: z.string().describe("GUID of the Citizen GameObject (must have a CitizenAnimationHelper)"),
+        holdType: z.string().optional().describe("Hold pose, e.g. None, Pistol, Rifle, Shotgun, HoldItem"),
+        moveStyle: z.string().optional().describe("Movement style, e.g. Auto, Walk, Run"),
+        specialMove: z.string().optional().describe("Special move style, e.g. None, LedgeGrab, Roll"),
+        sitting: z.boolean().optional().describe("Sit the character (IsSitting)"),
+        duckLevel: z.number().min(0).max(1).optional().describe("Crouch amount, 0-1"),
+    }, async (params) => {
+        const res = await bridge.send("pose_citizen", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── equip_model ────────────────────────────────────────────────────
+    server.tool("equip_model", "Attach a prop model (weapon, hat, tool) to a Citizen's bone or attachment point — the prop is parented so it follows that point. Tries the point as an attachment (hand_R, hand_L, eyes, hat) then as a bone. Great for arming NPCs or adding accessories.", {
+        id: z.string().describe("GUID of the GameObject with a SkinnedModelRenderer"),
+        model: z.string().describe("Prop model path, e.g. 'models/dev/box.vmdl'"),
+        point: z
+            .string()
+            .optional()
+            .describe("Attachment or bone name (default 'hand_R'; try hand_L, eyes, hat, head)"),
+        offset: Vector3Schema.optional().describe("Local position offset from the point"),
+        rotation: RotationSchema.optional().describe("Local rotation offset"),
+        tint: ColorSchema.optional().describe("Prop tint colour"),
+        name: z.string().optional().describe("Name for the prop GameObject"),
+    }, async (params) => {
+        const res = await bridge.send("equip_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_look_at ────────────────────────────────────────────────────
+    server.tool("set_look_at", "Aim a Citizen's gaze. Pass target {x,y,z} (spawns a LookTarget) or targetId (existing GameObject) and the head/eyes track it. Pass enabled:false to turn gaze tracking off. Tune eyesWeight/headWeight/bodyWeight (0-1).", {
+        id: z.string().describe("GUID of the Citizen (must have a CitizenAnimationHelper)"),
+        target: Vector3Schema.optional().describe("World point to look at"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of a GameObject to look at (overrides target)"),
+        enabled: z.boolean().optional().describe("false to disable gaze tracking"),
+        eyesWeight: z.number().min(0).max(1).optional().describe("Eye look weight 0-1"),
+        headWeight: z.number().min(0).max(1).optional().describe("Head turn weight 0-1"),
+        bodyWeight: z.number().min(0).max(1).optional().describe("Body turn weight 0-1"),
+    }, async (params) => {
+        const res = await bridge.send("set_look_at", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── add_ragdoll ────────────────────────────────────────────────────
+    server.tool("add_ragdoll", "Add ModelPhysics to a skinned model so it becomes a ragdoll (physics-driven bones). NOTE: the ragdoll only flops in PLAY mode — it won't move in the static editor view, so this one is verified structurally, not by screenshot.", {
+        id: z.string().describe("GUID of the GameObject with a SkinnedModelRenderer"),
+        motionEnabled: z
+            .boolean()
+            .optional()
+            .describe("Whether physics bodies start with motion enabled"),
+    }, async (params) => {
+        const res = await bridge.send("add_ragdoll", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── set_expression ─────────────────────────────────────────────────
+    server.tool("set_expression", "Set a facial morph (blendshape) on a skinned model — e.g. smile, frown, blink. Call with NO morph to list the model's available morph names (returned as availableMorphs). weight is typically 0-1.", {
+        id: z.string().describe("GUID of the GameObject with a SkinnedModelRenderer"),
+        morph: z
+            .string()
+            .optional()
+            .describe("Morph/blendshape name (omit to list available morphs)"),
+        weight: z.number().optional().describe("Morph weight, typically 0-1 (default 1)"),
+    }, async (params) => {
+        const res = await bridge.send("set_expression", 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/leveltools.d.ts

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

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/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/package.json

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