sbox-mcp-server 1.20.0 → 2.0.0

package/dist/tools/physics.js

@@ -14,7 +14,7 @@ const Vector3Schema = z
     .describe('3D vector — object {x,y,z} OR comma string "x,y,z"');
 export function registerPhysicsTools(server, bridge) {
     // ── add_physics ───────────────────────────────────────────────────
-    server.tool("add_physics", "Add a Rigidbody and collider to a GameObject, making it a dynamic physics object. Auto-selects BoxCollider if no collider type specified", {
+    server.tool("add_physics", "Add a Rigidbody and collider to a GameObject, making it a dynamic physics object. Auto-selects BoxCollider if no collider type specified. Returns { physicsAdded, id, components } listing exactly which components were added (e.g. Rigidbody + BoxCollider) — enter play mode (start_play) to see it simulate.", {
         id: z.string().describe("GUID of the GameObject"),
         collider: z
             .enum(["box", "sphere", "capsule", "mesh"])
@@ -38,7 +38,7 @@ export function registerPhysicsTools(server, bridge) {
         };
     });
     // ── add_collider ──────────────────────────────────────────────────
-    server.tool("add_collider", "Add a specific collider component to a GameObject. Supports box, sphere, capsule, mesh, and hull types. Can be configured as trigger", {
+    server.tool("add_collider", "Add a specific collider component to a GameObject (no Rigidbody — use add_physics for a dynamic body). Can be configured as a trigger. Returns { added, id, collider, isTrigger } where collider is the actual component type added — note 'mesh' maps to HullCollider (s&box has no MeshCollider) and unrecognized types fall back to BoxCollider.", {
         id: z.string().describe("GUID of the GameObject"),
         type: z
             .enum(["box", "sphere", "capsule", "mesh", "hull"])
@@ -68,7 +68,7 @@ export function registerPhysicsTools(server, bridge) {
         };
     });
     // ── add_joint ─────────────────────────────────────────────────────
-    server.tool("add_joint", "Add a physics joint/constraint between two GameObjects. Supports fixed, spring, and slider joint types", {
+    server.tool("add_joint", "Add a physics joint/constraint component to a GameObject, optionally connected to a target body (targetId). Returns { added, id, joint, targetId } — joint is the component type added (FixedJoint/SpringJoint/SliderJoint). If targetId is omitted the joint is added unconnected; wire it later via set_property. Both objects need physics (add_physics) for the constraint to simulate in play mode.", {
         id: z
             .string()
             .describe("GUID of the GameObject to add the joint to"),
@@ -97,7 +97,7 @@ export function registerPhysicsTools(server, bridge) {
         };
     });
     // ── raycast ───────────────────────────────────────────────────────
-    server.tool("raycast", "Perform a physics raycast (Scene.Trace.Ray) and return hit results. Useful for line-of-sight checks, object placement, and collision detection", {
+    server.tool("raycast", "Perform a physics raycast (Scene.Trace.Ray) from start to end — pass both; the handler traces the start→end segment. Useful for line-of-sight checks, object placement, and collision detection. Returns { hit, hitPosition, normal, distance, gameObjectId, gameObjectName } — feed gameObjectId into get_all_properties/set_transform, or visualize the result with debug_draw_ray. A 'Default Surface not found' error is a known transient; call restart_editor and retry.", {
         start: Vector3Schema
             .describe('Ray start position (world space) — object {x,y,z} or comma string "x,y,z"'),
         end: Vector3Schema

package/dist/tools/playmode.js

@@ -8,7 +8,7 @@ import { z } from "zod";
  */
 export function registerPlayModeTools(server, bridge) {
     // ── start_play ───────────────────────────────────────────────────
-    server.tool("start_play", "Enter play mode — starts running the game in the editor. Scripts execute, physics simulate, everything goes live", {}, async () => {
+    server.tool("start_play", "Enter play mode — starts running the game in the editor. Scripts execute, physics simulate, everything goes live. Returns { started, method } (method 'EditorScene.Play', or 'SetPlaying (fallback)' with editorErrorSkipped when the safe path failed). While playing, scene-mutating tools refuse — use get/set_runtime_property, capture_view, and playtest, then stop_play to edit again.", {}, async () => {
         const res = await bridge.send("start_play");
         if (!res.success) {
             return { content: [{ type: "text", text: `Error: ${res.error}` }] };
@@ -41,7 +41,7 @@ export function registerPlayModeTools(server, bridge) {
         };
     });
     // ── take_screenshot ──────────────────────────────────────────────
-    server.tool("take_screenshot", "Capture the current editor viewport as a PNG screenshot", {
+    server.tool("take_screenshot", "Capture a 1920x1080 PNG from the scene's Main Camera (ONE fixed angle — the camera may not face what you changed; use screenshot_from to aim at a target object/point). Returns { taken, note, path }, but the engine saves to its default screenshots folder regardless of the path param (<sbox install>/screenshots/sbox.<timestamp>.png) — list the newest file there and READ the image to verify.", {
         path: z
             .string()
             .optional()
@@ -56,7 +56,7 @@ export function registerPlayModeTools(server, bridge) {
         };
     });
     // ── undo ─────────────────────────────────────────────────────────
-    server.tool("undo", "Undo the last editor action. Safety net for when a change goes wrong", {}, async () => {
+    server.tool("undo", "Undo the last editor action via the editor's UndoSystem. Safety net for when a change goes wrong. Returns { undone: true } — it does not report WHAT was undone, so re-check state with get_scene_hierarchy or get_all_properties. Reverse it with redo. Note: file writes (write_file/create_script) are not editor undo steps.", {}, async () => {
         const res = await bridge.send("undo");
         if (!res.success) {
             return { content: [{ type: "text", text: `Error: ${res.error}` }] };
@@ -66,7 +66,7 @@ export function registerPlayModeTools(server, bridge) {
         };
     });
     // ── redo ─────────────────────────────────────────────────────────
-    server.tool("redo", "Redo the last undone editor action", {}, async () => {
+    server.tool("redo", "Re-apply the editor action most recently reverted by undo (editor UndoSystem redo — the counterpart to the undo tool). Returns { redone: true } without details of what was redone, so verify the resulting state with get_scene_hierarchy or get_all_properties.", {}, async () => {
         const res = await bridge.send("redo");
         if (!res.success) {
             return { content: [{ type: "text", text: `Error: ${res.error}` }] };
@@ -107,7 +107,7 @@ export function registerPlayModeTools(server, bridge) {
         };
     });
     // ── set_runtime_property ─────────────────────────────────────────
-    server.tool("set_runtime_property", "Set a component property value during play mode — tweak values live while the game runs", {
+    server.tool("set_runtime_property", "Set a component property value during play mode — tweak values live while the game runs. Errors if the game is not playing (start_play first). Returns { set, id, component, property, value } like set_property; read it back with get_runtime_property. Runtime changes are DISCARDED when play mode stops — use set_property in edit mode to persist.", {
         id: z.string().describe("GUID of the GameObject"),
         component: z.string().describe("Component type name"),
         property: z.string().describe("Property name to set"),

package/dist/tools/playtest.js

@@ -34,6 +34,7 @@ export function registerPlaytestTools(server, bridge) {
         id: z.string().optional().describe("GUID of the player/controller GameObject. Omit to auto-resolve the first PlayerController."),
         component: z.string().optional().describe("Controller component type to target (e.g. 'PlayerController'). Omit to auto-detect."),
     }, async (p) => reply(await bridge.send("playtest", p)));
-    server.tool("playtest_status", "Poll the running/finished playtest. While running: { active:true, step, totalSteps, passed, failed }. When done: { finished:true, verdict:'PASS'|'FAIL', passed, failed, transcript:[...] } — the full per-step pass/fail record.", {}, async () => reply(await bridge.send("playtest_status", {})));
+    server.tool("playtest_status", "Poll the playtest started by the playtest tool. While running: { active:true, step, totalSteps, passed, failed }. When done: { finished:true, reason, verdict:'PASS'|'FAIL', passed, failed, stepsRun, totalSteps, controller, controllerResolved, transcript:[...] } — the full per-step pass/fail record, including any capture PNG paths; the finished summary stays readable until the next playtest starts. If none has run yet: { active:false, finished:false }. Stop a stuck/wrong run early with playtest_abort.", {}, async () => reply(await bridge.send("playtest_status", {})));
+    server.tool("playtest_abort", "Stop the RUNNING playtest immediately: releases held input actions, restores UseInputControls, and finalizes the partial transcript (reason 'aborted'). Returns { aborted, stepsRun, passed, failed } — or aborted:false if no job is running. The partial transcript stays readable via playtest_status. Use when a step list is clearly stuck or targeting the wrong object", {}, async () => reply(await bridge.send("playtest_abort", {})));
 }
 //# sourceMappingURL=playtest.js.map

package/dist/tools/prefabs.js

@@ -5,7 +5,7 @@ import { z } from "zod";
  */
 export function registerPrefabTools(server, bridge) {
     // ── create_prefab ─────────────────────────────────────────────────
-    server.tool("create_prefab", "Save an existing GameObject as a reusable .prefab file. The prefab can be instantiated later", {
+    server.tool("create_prefab", "Save an existing GameObject as a real .prefab file — FULL engine serialization: every component with its property values, and all children, in the same JSON format the editor writes. Returns { created, path, sourceId, components, children } — pass path to instantiate_prefab to spawn copies or get_prefab_info to inspect. Errors if the source GameObject is missing; overwrites an existing file at path.", {
         id: z.string().describe("GUID of the GameObject to save as prefab"),
         path: z
             .string()
@@ -20,10 +20,14 @@ export function registerPrefabTools(server, bridge) {
         };
     });
     // ── instantiate_prefab ────────────────────────────────────────────
-    server.tool("instantiate_prefab", "Spawn a prefab instance into the active scene at an optional position and rotation", {
+    server.tool("instantiate_prefab", "Spawn a FULL prefab instance into the active scene — components and children recreated. Uses the engine's GameObject.Clone for registered prefabs, with a guid-remapped deserialize fallback for freshly-written files (repeat instantiations never collide). Returns { instantiated, prefab, method, gameObject, components, childCount } — gameObject.id is the new GUID for set_transform/set_property follow-ups. Optional name/position/rotation override the spawned root.", {
         path: z
             .string()
             .describe("Path to the .prefab file (e.g. 'prefabs/enemies/grunt.prefab')"),
+        name: z
+            .string()
+            .optional()
+            .describe("Rename the spawned root (defaults to the prefab's root name)"),
         position: z
             .union([
             z.object({
@@ -80,7 +84,7 @@ export function registerPrefabTools(server, bridge) {
         };
     });
     // ── get_prefab_info ───────────────────────────────────────────────
-    server.tool("get_prefab_info", "Get detailed information about a prefab file including its JSON contents and metadata", {
+    server.tool("get_prefab_info", "Inspect a prefab file as a structured summary: { path, name, size, modified, totalObjects, maxDepth, referencedPrefabs, tree } — tree is the object hierarchy with per-node component type lists (children capped at 8 per node with a truncation count). referencedPrefabs lists other .prefab files this one links to. Use before instantiate_prefab; find prefabs with list_prefabs; raw JSON via read_file if needed.", {
         path: z
             .string()
             .describe("Path to the .prefab file (e.g. 'prefabs/enemies/grunt.prefab')"),

package/dist/tools/project.js

@@ -21,7 +21,7 @@ export function registerProjectTools(server, bridge) {
         };
     });
     // ── list_project_files ───────────────────────────────────────────
-    server.tool("list_project_files", "Browse the project file tree. Optionally filter by directory path and/or file extension (e.g. '.cs', '.scene')", {
+    server.tool("list_project_files", "Browse the project file tree. Optionally filter by directory path and/or file extension (e.g. '.cs', '.scene'). Returns { path, count, files } as project-root-relative paths — CAPPED AT 500 files (count reflects the truncated list, with no marker that more exist), so on large projects narrow with path/extension or use find_in_project. Recursive by default.", {
         path: z
             .string()
             .optional()
@@ -67,7 +67,7 @@ export function registerProjectTools(server, bridge) {
         };
     });
     // ── write_file ───────────────────────────────────────────────────
-    server.tool("write_file", "Write or overwrite a file in the s&box project. Creates parent directories as needed", {
+    server.tool("write_file", "Write or overwrite a file in the s&box project (SILENTLY replaces existing content — read_file first if you need to preserve it). Creates parent directories as needed; paths are confined to the project root (traversal outside it is denied). Returns a confirmation with the path — for C# follow with trigger_hotload so it compiles; for assets (.vmat etc.) follow with recompile_asset.", {
         path: z
             .string()
             .describe("Relative path for the file (e.g. 'code/Components/Health.cs')"),

package/dist/tools/publishing.js

@@ -22,7 +22,7 @@ export function registerPublishingTools(server, bridge) {
         };
     });
     // ── set_project_config ───────────────────────────────────────────
-    server.tool("set_project_config", "Update project configuration fields for publishing: title, description, version, type, package ident, summary, visibility. Only provided fields are changed", {
+    server.tool("set_project_config", "Update project configuration fields for publishing: title, description, version, type, package ident, summary, visibility. Only provided fields are changed — edits string values in the .sbproj file in place. Returns { updated, path } (the .sbproj path); read the result back with get_project_config to confirm what actually changed.", {
         title: z.string().optional().describe("Project display title"),
         description: z
             .string()
@@ -58,7 +58,7 @@ export function registerPublishingTools(server, bridge) {
         };
     });
     // ── validate_project ─────────────────────────────────────────────
-    server.tool("validate_project", "Validate that the project is ready for publishing. Checks: compile errors, metadata completeness, scenes, scripts, thumbnail, and project type", {}, async (params) => {
+    server.tool("validate_project", "Validate that the project is ready for publishing. Runs four checks: .sbproj exists, at least one scene, project Ident set, project Title set. Returns { valid, issueCount, issues, checks } — issues are human-readable problems and each checks entry has { check, pass, detail }; fix metadata gaps with set_project_config (it does NOT check compile errors — use get_compile_errors for that).", {}, async (params) => {
         const res = await bridge.send("validate_project", params);
         if (!res.success) {
             return { content: [{ type: "text", text: `Error: ${res.error}` }] };
@@ -93,7 +93,7 @@ export function registerPublishingTools(server, bridge) {
         };
     });
     // ── get_package_details ──────────────────────────────────────────
-    server.tool("get_package_details", "Fetch detailed package information from the s&box asset library (asset.party) including title, author, version, downloads, ratings, and dependencies", {
+    server.tool("get_package_details", "Fetch package information from the s&box package backend (Package.FetchAsync) by ident. Returns { fullIdent, title, summary, description, org } — no download/rating/dependency data is included. Use it to confirm a package exists and what it is before install_asset.", {
         ident: z
             .string()
             .describe("Package identifier (e.g. 'facepunch.flatgrass', 'myorg.mygame')"),

package/dist/tools/scenes.js

@@ -33,7 +33,7 @@ export function registerSceneTools(server, bridge) {
         };
     });
     // ── save_scene ───────────────────────────────────────────────────
-    server.tool("save_scene", "Save the currently open scene in the s&box editor", {
+    server.tool("save_scene", "Save the currently open scene in the s&box editor (EditorScene.SaveSession) to its existing .scene file — a provided path does NOT redirect the save. Returns a plain 'Scene saved' confirmation. Call after a batch of scene edits so work survives an editor restart.", {
         path: z
             .string()
             .optional()
@@ -48,7 +48,7 @@ export function registerSceneTools(server, bridge) {
         };
     });
     // ── create_scene ─────────────────────────────────────────────────
-    server.tool("create_scene", "Create a new empty scene file. Optionally include basic objects like a camera, directional light, and ground plane", {
+    server.tool("create_scene", "Create a new EMPTY .scene file under the project's Assets folder and register it with the AssetSystem so load_scene works immediately. Errors if the scene already exists. NOTE: includeDefaults is not yet honored — the scene is always created empty, so after load_scene add a camera/light/ground yourself (create_gameobject, add_light). Returns a confirmation with the path — pass it to load_scene next.", {
         path: z
             .string()
             .describe("Relative path for the new scene (e.g. 'scenes/level_01.scene')"),

package/dist/tools/scripts.js

@@ -6,7 +6,7 @@ import { z } from "zod";
  */
 export function registerScriptTools(server, bridge) {
     // ── create_script ────────────────────────────────────────────────
-    server.tool("create_script", "Create a new C# component script in the project. Generates proper s&box component boilerplate with the specified class name, namespace, and optional properties", {
+    server.tool("create_script", "Create a new C# component script in the project — a minimal s&box Component class (name is sanitized to a valid identifier), or your exact code when content is provided. Errors if the file already exists. Returns { path, created, className } — the new type is NOT live until a recompile, so call trigger_hotload, then attach it with add_component_with_properties (component=className).", {
         name: z
             .string()
             .describe("Class name for the component (e.g. 'PlayerController'). Will also be the filename"),
@@ -52,7 +52,7 @@ export function registerScriptTools(server, bridge) {
         };
     });
     // ── edit_script ──────────────────────────────────────────────────
-    server.tool("edit_script", "Edit an existing C# script. Supports find/replace, inserting code at a line number, or appending code to the class body", {
+    server.tool("edit_script", "Edit an existing C# script in place via exact-text find/replace or a full-content overwrite. Errors if the file or the find text isn't found (find/replace replaces ALL occurrences). Returns { path, edited, operation } where operation is 'find_replace' or 'overwrite' — follow with trigger_hotload so the change compiles, then get_compile_errors if in doubt.", {
         path: z
             .string()
             .describe("Relative path to the script file (e.g. 'code/PlayerController.cs')"),
@@ -98,7 +98,7 @@ export function registerScriptTools(server, bridge) {
         };
     });
     // ── delete_script ────────────────────────────────────────────────
-    server.tool("delete_script", "Delete a C# script from the project", {
+    server.tool("delete_script", "Permanently delete a file from the project by its project-relative path (built for C# scripts, but removes any file; no recycle bin, and editor undo cannot restore it). Errors if the file doesn't exist. Returns a confirmation with the path — follow with trigger_hotload so the removed class actually leaves the compiled assembly.", {
         path: z
             .string()
             .describe("Relative path to the script file to delete"),

package/dist/tools/status.js

@@ -19,7 +19,7 @@ catch {
  */
 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 () => {
+    server.tool("get_bridge_status", "Check the s&box Bridge connection — call this FIRST in a session. Returns a human summary plus JSON: connected, roundTripOk (heartbeat can be fresh while the editor's request loop is stalled — trust roundTripOk), bridgeVersion vs mcpServerVersion + versionsAligned (a mismatch means restart Claude Code / republish the addon), handlerCount, heartbeatAgeMs, latencyMs, and ipcDir (transport is file IPC; host/port are legacy fields).", {}, async () => {
         const connected = bridge.isConnected();
         const ipcDir = bridge.getIpcDir();
         const heartbeatAgeMs = bridge.getHeartbeatAgeMs();

package/dist/tools/templates.js

@@ -89,7 +89,7 @@ export function registerTemplateTools(server, bridge) {
         };
     });
     // ── create_game_manager ───────────────────────────────────────────
-    server.tool("create_game_manager", "Generate a game manager script with configurable game loop features: score tracking, round timer, player spawning, and game state machine", {
+    server.tool("create_game_manager", "Generate a minimal game-manager Component: a static Instance singleton, [Property] MaxPlayers / GameState, and a Component.INetworkListener OnActive hook that logs player connects. Writes <name>.cs and returns { created, path, className }. NOTE: the includeScore/includeTimer/includeSpawning params are not currently applied — the same minimal manager is always generated (for richer game-loop scaffolds see create_round_phase_machine / create_objective_system / create_economy_wallet). Follow with trigger_hotload, then get_compile_errors, then place via add_component_to_new_object", {
         name: z
             .string()
             .optional()
@@ -101,15 +101,15 @@ export function registerTemplateTools(server, bridge) {
         includeScore: z
             .boolean()
             .optional()
-            .describe("Include score tracking. Defaults to true"),
+            .describe("Include score tracking (currently not applied by the handler)"),
         includeTimer: z
             .boolean()
             .optional()
-            .describe("Include round timer with countdown. Defaults to false"),
+            .describe("Include round timer with countdown (currently not applied by the handler)"),
         includeSpawning: z
             .boolean()
             .optional()
-            .describe("Include player spawning from prefab at spawn point. Defaults to false"),
+            .describe("Include player spawning from prefab at spawn point (currently not applied by the handler)"),
     }, async (params) => {
         const res = await bridge.send("create_game_manager", params);
         if (!res.success) {
@@ -120,7 +120,7 @@ export function registerTemplateTools(server, bridge) {
         };
     });
     // ── create_trigger_zone ───────────────────────────────────────────
-    server.tool("create_trigger_zone", "Generate a trigger zone script that detects when GameObjects enter/exit a collider volume. Supports teleport, damage, spawn, and log actions", {
+    server.tool("create_trigger_zone", "Generate a trigger-zone Component (Component.ITriggerListener): auto-adds a trigger BoxCollider on start, filters entrants by a TriggerTag [Property] (default 'player'), and logs enter/exit via private OnPlayerEnter/OnPlayerExit extension points you fill in. Writes <name>.cs and returns { created, path, className }. NOTE: the action/filterTag params are not currently applied at generation time — the zone always logs; implement teleport/damage/spawn in the generated methods (edit_script). Follow with trigger_hotload, then get_compile_errors", {
         name: z
             .string()
             .optional()
@@ -132,11 +132,11 @@ export function registerTemplateTools(server, bridge) {
         action: z
             .enum(["log", "teleport", "damage", "spawn"])
             .optional()
-            .describe("What happens on trigger: 'log' (print message), 'teleport' (move to destination), 'damage' (apply damage), 'spawn' (create prefab). Defaults to 'log'"),
+            .describe("What happens on trigger (currently not applied by the handler — the generated zone always logs; implement the effect in OnPlayerEnter yourself)"),
         filterTag: z
             .string()
             .optional()
-            .describe("Only trigger for objects with this tag. Defaults to 'player'"),
+            .describe("Only trigger for objects with this tag (currently not applied at generation — the generated TriggerTag [Property] defaults to 'player'; change it per-instance with set_property)"),
     }, async (params) => {
         const res = await bridge.send("create_trigger_zone", params);
         if (!res.success) {

package/dist/tools/ui.js

@@ -5,7 +5,7 @@ import { z } from "zod";
  */
 export function registerUITools(server, bridge) {
     // ── create_razor_ui ───────────────────────────────────────────────
-    server.tool("create_razor_ui", "Create a Razor UI component file (.razor) with optional SCSS stylesheet. Generates boilerplate for HUD, menu, or basic panel types", {
+    server.tool("create_razor_ui", "Create a Razor UI component file (.razor). Returns { created, path, componentName }; errors if the file already exists. NOTE: the current handler generates one fixed basic panel (a root div + label bound to a Title [Property]) from name+directory only — panelType/content/styles/includeStyles are not applied and no .scss is written; for custom markup or a PanelComponent you can host via add_screen_panel, write the files with write_file and check them with razor_lint. Follow with trigger_hotload, then get_compile_errors", {
         name: z
             .string()
             .describe("Component name (e.g. 'GameHud', 'MainMenu')"),
@@ -43,11 +43,11 @@ export function registerUITools(server, bridge) {
         };
     });
     // ── add_screen_panel ──────────────────────────────────────────────
-    server.tool("add_screen_panel", "Create a new GameObject with a ScreenPanel component for full-screen UI overlay (HUD, menus, etc.)", {
+    server.tool("add_screen_panel", "Create a new GameObject with a ScreenPanel component for full-screen UI overlay (HUD, menus, etc.). Returns { created, gameObject:{ id, name, components, ... } }. NOTE: panelComponent is looked up in the TypeLibrary and SILENTLY skipped if the type isn't loaded (freshly generated panels need trigger_hotload first) — check gameObject.components to confirm it attached", {
         name: z
             .string()
             .optional()
-            .describe("Name for the UI GameObject. Defaults to 'Screen UI'"),
+            .describe("Name for the UI GameObject. Defaults to 'Screen Panel'"),
         zIndex: z
             .number()
             .optional()
@@ -70,11 +70,11 @@ export function registerUITools(server, bridge) {
         };
     });
     // ── add_world_panel ───────────────────────────────────────────────
-    server.tool("add_world_panel", "Create a new GameObject with a WorldPanel component for in-world 3D UI (health bars, signs, nameplates)", {
+    server.tool("add_world_panel", "Create a new GameObject with a WorldPanel component for in-world 3D UI (health bars, signs, nameplates). Returns { created, gameObject:{ id, name, components, ... } }. As with add_screen_panel, panelComponent is SILENTLY skipped if the type isn't in the TypeLibrary (trigger_hotload first, then verify via gameObject.components). For CLICKABLE world UI the scene also needs a Sandbox.WorldInput (see create_worldpanel_ui)", {
         name: z
             .string()
             .optional()
-            .describe("Name for the UI GameObject. Defaults to 'World UI'"),
+            .describe("Name for the UI GameObject. Defaults to 'World Panel'"),
         position: z
             .union([
             z.object({ x: z.number(), y: z.number(), z: z.number() }),

package/dist/tools/uifeedback.js

@@ -34,7 +34,7 @@ export function registerUiFeedbackTools(server, bridge) {
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
     // ── create_proxy_nametag ──────────────────────────────────────────
-    server.tool("create_proxy_nametag", "Generate a sealed Component that floats the OWNER'S display name above a networked player. TextRenderer-based (not WorldPanel): a nametag is one short string with a distance fade, so a TextRenderer on a managed child object is far simpler than a WorldPanel + Razor + WorldInput stack — no UI assets, no panel host, per-frame alpha is a one-liner (mirrors create_floating_combat_text). Reads GameObject.Network.Owner.DisplayName (Owner and OwnerConnection are the same Connection on this SDK; falls back to the object name offline). Visibility is the INVERSE of the usual proxy guard: it renders only when GameObject.Network.IsProxy is true — i.e. on OTHER clients' copies of the player — so you never see a tag over your own head (offline / no networking => IsProxy false everywhere => no tags, expected). Spawns a CHILD GameObject for the text so billboarding never rotates the player model; cleaned up on disable. [Property] MaxDistance fades the tag out with distance, HeightOffset floats it above the head, FontSize sizes it. Attach to the ROOT of your networked player object. Pairs with create_networked_player (add it to the generated player prefab so every remote player is labeled).", {
+    server.tool("create_proxy_nametag", "Generate a sealed Component that floats the OWNER'S display name above a networked player. TextRenderer-based (not WorldPanel): a nametag is one short string with a distance fade, so a TextRenderer on a managed child object is far simpler than a WorldPanel + Razor + WorldInput stack — no UI assets, no panel host, per-frame alpha is a one-liner (mirrors create_floating_combat_text). Reads GameObject.Network.Owner.DisplayName (Owner and OwnerConnection are the same Connection on this SDK; falls back to the object name offline). Visibility is the INVERSE of the usual proxy guard: it renders only when GameObject.Network.IsProxy is true — i.e. on OTHER clients' copies of the player — so you never see a tag over your own head (offline / no networking => IsProxy false everywhere => no tags, expected). Spawns a CHILD GameObject for the text so billboarding never rotates the player model; cleaned up on disable. [Property] MaxDistance fades the tag out with distance, HeightOffset floats it above the head, FontSize sizes it. Attach to the ROOT of your networked player object. Pairs with create_networked_player (add it to the generated player prefab so every remote player is labeled). Returns { created, path, className, maxDistance, heightOffset, note, nextSteps }. Follow with trigger_hotload, then get_compile_errors, then attach via add_component_with_properties (component=className).", {
         name: z
             .string()
             .optional()

package/dist/tools/vehicles.d.ts

@@ -0,0 +1,8 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Vehicle tools (Batch 54): create_vehicle_controller, create_seat_system,
+ * tune_vehicle, create_physics_grab_tool — the corpus vehicles theme.
+ */
+export declare function registerVehicleTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=vehicles.d.ts.map

package/dist/tools/vehicles.js

@@ -0,0 +1,98 @@
+import { z } from "zod";
+/**
+ * Vehicle tools (Batch 54): create_vehicle_controller, create_seat_system,
+ * tune_vehicle, create_physics_grab_tool — the corpus vehicles theme.
+ */
+export function registerVehicleTools(server, bridge) {
+    // ── create_vehicle_controller ────────────────────────────────────
+    server.tool("create_vehicle_controller", "Generate a drivable raycast-car component: 4-corner spring/damper suspension, mass-scaled engine force, speed-scaled yaw steering, lateral grip (lower = drift), and a BUILT-IN driver seat (press E to enter — the driver is hidden while driving so their controller can't fight the vehicle transform, the host assigns them ownership, and a chase camera follows the car — E to exit). Attach it plus a Rigidbody and collider to any prop and it drives. Returns { created, path, className, nextSteps } — follow with trigger_hotload + compile_status, then batch_add_component the parts. Apply handling presets with tune_vehicle. HONEST LIMIT: compiles + runs is verified; driving FEEL needs a human playtest — tune from the inspector while playing", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class/file name (default 'VehicleController' -> Code/VehicleController.cs). Errors if the file exists"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Directory for the .cs file. Default 'Code'"),
+        engineForce: z
+            .number()
+            .optional()
+            .describe("Engine force (mass-scaled). Default 900"),
+        steerStrength: z
+            .number()
+            .optional()
+            .describe("Yaw rate in rad/s at full speed factor. Default 2.0"),
+        grip: z
+            .number()
+            .optional()
+            .describe("Lateral grip 0-1 — fraction of sideways velocity killed per tick; lower = drift. Default 0.85"),
+    }, async (params) => {
+        const res = await bridge.send("create_vehicle_controller", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── create_seat_system ───────────────────────────────────────────
+    server.tool("create_seat_system", "Generate a standalone networked one-occupant seat component: press E (use) to sit — claims route through the host so seats can't be shared — E to stand; the occupant parents to the seat with their controller input disabled and restored on exit, which tries each ExitOffsets entry and takes the first spot with clearance. Static OnOccupantChanged event for camera/UI. For chairs, benches, turret mounts; vehicles get a seat built into create_vehicle_controller. Returns { created, path, className, nextSteps } — trigger_hotload + compile_status, then attach to any prop", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class/file name (default 'Seat' -> Code/Seat.cs). Errors if the file exists"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Directory for the .cs file. Default 'Code'"),
+    }, async (params) => {
+        const res = await bridge.send("create_seat_system", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── tune_vehicle ─────────────────────────────────────────────────
+    server.tool("tune_vehicle", "Apply a handling preset to a vehicle component on a GameObject: arcade (forgiving), drift (low grip, sharp steering), offroad (soft long-travel suspension), or race (fast, planted). Sets EngineForce/MaxSpeed/SteerStrength/GripFactor/SuspensionStrength/SuspensionDamping by name via reflection — targets create_vehicle_controller scaffolds out of the box, partially tunes anything exposing those property names. Returns { tuned, preset, component, applied, missing } — missing lists properties the component lacks. Auto-finds the first component with 'Vehicle' in its type name; pass component to target explicitly. Scene-mutating: refused during play mode (use set_property on runtime objects while playing)", {
+        id: z
+            .string()
+            .describe("GUID of the GameObject carrying the vehicle component (from find_objects)"),
+        preset: z
+            .enum(["arcade", "drift", "offroad", "race"])
+            .describe("Handling preset to apply"),
+        component: z
+            .string()
+            .optional()
+            .describe("Component type name to tune. Default: first component with 'Vehicle' in its name"),
+    }, async (params) => {
+        const res = await bridge.send("tune_vehicle", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── create_physics_grab_tool ─────────────────────────────────────
+    server.tool("create_physics_grab_tool", "Generate a physgun-lite player component: hold attack2 while looking at a Rigidbody prop within Range to grab it — it spring-follows a point in front of your view with physics LIVE (collides and swings, unlike the parented create_carry_system) — attack1 throws it, release lets go. Grab requests route through the host, which assigns the grabber network ownership. Returns { created, path, className, nextSteps } — trigger_hotload + compile_status, attach to the player object; ensure_input_action if attack1/attack2 aren't bound", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class/file name (default 'PhysicsGrabTool' -> Code/PhysicsGrabTool.cs). Errors if the file exists"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Directory for the .cs file. Default 'Code'"),
+    }, async (params) => {
+        const res = await bridge.send("create_physics_grab_tool", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=vehicles.js.map

package/dist/tools/visuals.js

@@ -72,7 +72,7 @@ export function registerVisualTools(server, bridge) {
         };
     });
     // ── set_fog ────────────────────────────────────────────────────────
-    server.tool("set_fog", "Add or update fog in the active scene. Types: 'gradient' (distance haze — great for mood/horror), 'cubemap' (sky-tinted distance fog), 'volumetric' (a localized fog volume). Re-running on the same target updates it rather than duplicating.", {
+    server.tool("set_fog", "Add or update fog in the active scene. Types: 'gradient' (distance haze — great for mood/horror), 'cubemap' (sky-tinted distance fog), 'volumetric' (a localized fog volume). Re-running with the same targetId updates it rather than duplicating; without targetId each call creates a new fog object. Returns { created, type, gameObject } — gameObject.id addresses the fog object for later set_property/delete_gameobject; screenshot to verify the look.", {
         type: z
             .enum(["gradient", "cubemap", "volumetric"])
             .optional()
@@ -127,7 +127,7 @@ export function registerVisualTools(server, bridge) {
         };
     });
     // ── 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.", {
+    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 (silently kept as-is if the material fails to load). Returns { created, gameObject } — gameObject.id is the sky object; screenshot to verify the change.", {
         tint: ColorSchema.optional().describe("Sky tint colour"),
         indirectLighting: z
             .boolean()
@@ -145,7 +145,7 @@ export function registerVisualTools(server, bridge) {
         };
     });
     // ── 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.", {
+    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. Returns { applied, mood, components, postFxCamera } — the post-fx stack is only applied when a camera exists (postFxCamera is null otherwise; add a camera and re-run). Screenshot to verify.", {
         mood: z
             .enum(["horror-night", "foggy-dawn", "overcast", "warm-interior"])
             .describe("Atmosphere preset"),
@@ -159,7 +159,7 @@ export function registerVisualTools(server, bridge) {
         };
     });
     // ── 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).", {
+    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). Errors if the scene has no CameraComponent. Returns { applied, look, components, camera } listing the effect components added to the main camera — tune them individually afterwards with add_post_process.", {
         look: z
             .enum(["cinematic", "filmic-horror", "clean"])
             .describe("Post-fx look preset"),
@@ -173,7 +173,7 @@ export function registerVisualTools(server, bridge) {
         };
     });
     // ── 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.", {
+    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. IMPORTANT: a placed probe captures NOTHING until baked — follow with bake_reflections. Returns { created, gameObject } — gameObject.id is the probe object's GUID.", {
         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)"),
@@ -192,7 +192,7 @@ export function registerVisualTools(server, bridge) {
         };
     });
     // ── 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.)", {
+    server.tool("spawn_particle", "EXPERIMENTAL — build an additive runtime ParticleEffect (no texture asset needed): kind = fire, embers, sparks, magic, dust, blood, or snow ('smoke' returns an error). Returns { created, kind, gameObject } — the component graph is created, but this runtime particle path has NOT been verified to render through the bridge; for particles you can actually see, prefer spawn_vpcf.", {
         kind: z
             .enum(["fire", "embers", "sparks", "magic", "dust", "blood", "snow"])
             .describe("Particle preset"),
@@ -226,7 +226,7 @@ export function registerVisualTools(server, bridge) {
         };
     });
     // ── 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.", {
+    server.tool("add_beam", "EXPERIMENTAL — create an energy/laser beam (BeamEffect) from a position to a target point (default: 128u straight up) — additive, tintable. Returns { created, gameObject } — gameObject.id is the beam object's GUID. Like the other runtime particle tools, rendering through the bridge is unverified; use spawn_vpcf when you need a guaranteed-visible effect.", {
         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)"),
@@ -286,7 +286,7 @@ export function registerVisualTools(server, bridge) {
         };
     });
     // ── bake_reflections ────────────────────────────────────────────────
-    server.tool("bake_reflections", "Bake all EnvmapProbe reflection probes in the scene (EnvmapProbe.BakeAll) so they actually capture their surroundings — placing a probe with add_envmap_probe does nothing visible until it's baked. This is a real editor compute step, not a component setter. Runs async; re-screenshot after a moment to see reflections appear on shiny surfaces.", {}, async (params) => {
+    server.tool("bake_reflections", "Bake all EnvmapProbe reflection probes in the scene (EnvmapProbe.BakeAll) so they actually capture their surroundings — placing a probe with add_envmap_probe does nothing visible until it's baked. This is a real editor compute step, not a component setter. Runs async — returns { baking, count, note, probes } immediately (each probe: id, name, mode, hasBaked), or { baked: false, count: 0 } when the scene has no probes; re-screenshot after a moment to see reflections appear.", {}, async (params) => {
         const res = await bridge.send("bake_reflections", params);
         if (!res.success) {
             return { content: [{ type: "text", text: `Error: ${res.error}` }] };

package/dist/tools/workflow.d.ts

@@ -0,0 +1,8 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Workflow tools (Batch 53): scene checkpoints (the agent-side undo safety net),
+ * describe_scene orientation, and the team-assigner / idle-income scaffolds.
+ */
+export declare function registerWorkflowTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=workflow.d.ts.map