sbox-mcp-server 1.20.0 → 2.1.0

package/dist/tools/audit.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+/**
+ * Project audit & batch operation tools (v2 relaunch wave 1, Batch 51):
+ * find_broken_references, batch_set_property, describe_project.
+ */
+export function registerAuditTools(server, bridge) {
+    // ── find_broken_references ───────────────────────────────────────
+    server.tool("find_broken_references", "Scan the project for broken references, two layers in one call: (1) every GameObject in the open scene — renderers with no Model (missing_model), component properties pointing at DESTROYED GameObjects/Components (dead_gameobject_ref / dead_component_ref), null component entries whose type no longer exists (missing_component); (2) every .scene/.prefab FILE — prefab references to deleted/renamed files (missing_prefab_file). Returns { total, showing, truncated, objectsScanned, filesScanned, issues } — each issue has { id, name, component, kind, detail } (file-level issues carry the file path in name). Fix missing models with assign_model, dead refs with set_property/set_component_reference, missing prefab files by fixing the path or recreating via create_prefab. Read-only; safe any time. Results cap at `limit` (default 100, max 500)", {
+        limit: z
+            .number()
+            .int()
+            .optional()
+            .describe("Max issues to return (default 100, max 500). total still counts everything"),
+        scanFiles: z
+            .boolean()
+            .optional()
+            .describe("Include the .scene/.prefab file scan for missing prefab references. Default true"),
+    }, async (params) => {
+        const res = await bridge.send("find_broken_references", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── batch_set_property ───────────────────────────────────────────
+    server.tool("batch_set_property", "Set ONE component property to the same value across MANY GameObjects in a single call (e.g. Tint on 40 props, Enabled on every light). Pass dryRun:true first to validate — it reports each object's current value and what would change WITHOUT applying anything. Returns { total, succeeded, failed, dryRun, results } with per-object ok/error and the previous value on success. Get ids from find_objects or get_selected_objects. Scene-mutating: refused during play mode. Value coercion matches set_property (numbers, bools, enums, 'x,y,z' vectors, colors, asset paths)", {
+        ids: z
+            .array(z.string())
+            .describe("GUIDs of the GameObjects to modify (from find_objects, get_scene_hierarchy, or get_selected_objects)"),
+        component: z
+            .string()
+            .describe("Component type name present on each object, e.g. 'ModelRenderer', 'PointLight'"),
+        property: z
+            .string()
+            .describe("Property name to set, e.g. 'Tint', 'Enabled', 'LightColor' (see get_all_properties)"),
+        value: z
+            .any()
+            .describe("New value — number, bool, string, enum name, 'x,y,z' vector, color, or asset path"),
+        dryRun: z
+            .boolean()
+            .optional()
+            .describe("true = validate and report current values without changing anything. Default false"),
+    }, async (params) => {
+        const res = await bridge.send("batch_set_property", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── describe_project ─────────────────────────────────────────────
+    server.tool("describe_project", "One-call project orientation: identity (name/ident/org/type), the open scene with object count, scene and prefab file lists (capped at 50 each, Libraries/.sbox excluded), code footprint (.cs/.razor counts), custom Component types (up to 100, engine types excluded), and installed libraries. Returns a structured summary — orient here first, then get_scene_hierarchy for the scene, describe_type for components, find_broken_references for project health. Read-only", {}, async (params) => {
+        const res = await bridge.send("describe_project", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=audit.js.map

package/dist/tools/batch.d.ts

@@ -0,0 +1,8 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Batch operation tools (Batch 52): batch_delete, batch_add_component,
+ * batch_reparent. All follow the dryRun convention from batch_set_property.
+ */
+export declare function registerBatchTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=batch.d.ts.map

package/dist/tools/batch.js

@@ -0,0 +1,77 @@
+import { z } from "zod";
+/**
+ * Batch operation tools (Batch 52): batch_delete, batch_add_component,
+ * batch_reparent. All follow the dryRun convention from batch_set_property.
+ */
+export function registerBatchTools(server, bridge) {
+    // ── batch_delete ─────────────────────────────────────────────────
+    server.tool("batch_delete", "Delete MANY GameObjects (and their entire subtrees) in one call. ALWAYS pass dryRun:true first — it reports each object's name and child count WITHOUT deleting, so you can confirm the target list. Returns { total, succeeded, failed, dryRun, results } with per-object ok/error. Destructive and NOT undoable — get ids from find_objects or get_selected_objects and verify the dry-run before applying. Scene-mutating: refused during play mode", {
+        ids: z
+            .array(z.string())
+            .describe("GUIDs of the GameObjects to delete (subtrees included)"),
+        dryRun: z
+            .boolean()
+            .optional()
+            .describe("true = report names/child counts without deleting anything. Default false — but run a dry pass first"),
+    }, async (params) => {
+        const res = await bridge.send("batch_delete", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── batch_add_component ──────────────────────────────────────────
+    server.tool("batch_add_component", "Add one component type to MANY GameObjects in one call (e.g. BoxCollider on every crate). Skips objects that already have the component unless skipExisting:false. dryRun:true validates the type and reports per-object alreadyHas WITHOUT adding. Returns { total, succeeded, failed, skipped, dryRun, results }. Follow with batch_set_property to configure the new components. Scene-mutating: refused during play mode", {
+        ids: z
+            .array(z.string())
+            .describe("GUIDs of the target GameObjects (from find_objects or get_selected_objects)"),
+        component: z
+            .string()
+            .describe("Component type name to add, e.g. 'BoxCollider', 'PointLight' (search with list_available_components)"),
+        skipExisting: z
+            .boolean()
+            .optional()
+            .describe("Skip objects that already have this component type. Default true"),
+        dryRun: z
+            .boolean()
+            .optional()
+            .describe("true = validate and report without adding anything. Default false"),
+    }, async (params) => {
+        const res = await bridge.send("batch_add_component", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+    // ── batch_reparent ───────────────────────────────────────────────
+    server.tool("batch_reparent", "Move MANY GameObjects under a new parent (or to the scene root) in one call — organize scattered props into a folder object, or regroup a level section. dryRun:true reports each object's current parent and destination WITHOUT moving. Returns { total, succeeded, failed, dryRun, keepWorldPosition, results }. Errors if parent is among ids (no cycles). Scene-mutating: refused during play mode", {
+        ids: z
+            .array(z.string())
+            .describe("GUIDs of the GameObjects to move"),
+        parent: z
+            .string()
+            .optional()
+            .describe("GUID of the new parent GameObject. Omit (or empty) to move to the scene root"),
+        keepWorldPosition: z
+            .boolean()
+            .optional()
+            .describe("Preserve each object's world position while reparenting. Default true"),
+        dryRun: z
+            .boolean()
+            .optional()
+            .describe("true = report current parents and the destination without moving anything. Default false"),
+    }, async (params) => {
+        const res = await bridge.send("batch_reparent", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=batch.js.map

package/dist/tools/characters.js

@@ -56,7 +56,7 @@ export function registerCharacterTools(server, bridge) {
         };
     });
     // ── 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.", {
+    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). Returns { created, hasAnimator, gameObject:{ id, name, position, components, ... } } — pass gameObject.id to the follow-ups: dress_citizen, pose_citizen, set_expression, equip_model.", {
         name: z.string().optional().describe("GameObject name (default 'Citizen')"),
         model: z
             .string()
@@ -110,7 +110,7 @@ export function registerCharacterTools(server, bridge) {
         };
     });
     // ── 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).", {
+    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). Returns { set, bodygroup } on success (errors if the object has no SkinnedModelRenderer or neither value nor choice is given); take_screenshot to verify the visual change.", {
         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"),
@@ -125,7 +125,7 @@ export function registerCharacterTools(server, bridge) {
         };
     });
     // ── 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).", {
+    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). Returns { posed, changed:[...], gameObject } — changed lists which helper params were applied; take_screenshot to verify the pose.", {
         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"),
@@ -184,7 +184,7 @@ export function registerCharacterTools(server, bridge) {
         };
     });
     // ── 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.", {
+    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. Returns { ragdoll, note, gameObject } — check gameObject.components for ModelPhysics, then verify at runtime with start_play + capture_view.", {
         id: z.string().describe("GUID of the GameObject with a SkinnedModelRenderer"),
         motionEnabled: z
             .boolean()
@@ -200,7 +200,7 @@ export function registerCharacterTools(server, bridge) {
         };
     });
     // ── 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.", {
+    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. Returns { set, morph, weight, availableMorphs } — availableMorphs is included in every response, so a wrong name can be corrected without an extra listing call.", {
         id: z.string().describe("GUID of the GameObject with a SkinnedModelRenderer"),
         morph: z
             .string()
@@ -244,7 +244,7 @@ export function registerCharacterTools(server, bridge) {
         };
     });
     // ── set_animgraph_param ────────────────────────────────────────────
-    server.tool("set_animgraph_param", "Set an AnimationGraph parameter on a GameObject's SkinnedModelRenderer (calls Set). This drives Citizen/animgraph motion — e.g. 'move_x'/'move_y' (float), 'b_grounded'/'b_ducked' (bool), or a Vector3. Pose previews in-editor when PlayAnimationsInEditorScene is on; screenshot to verify. Param names are defined by the model's animation graph.", {
+    server.tool("set_animgraph_param", "Set an AnimationGraph parameter on a GameObject's SkinnedModelRenderer (calls Set). This drives Citizen/animgraph motion — e.g. 'move_x'/'move_y' (float), 'b_grounded'/'b_ducked' (bool), or a Vector3. Pose previews in-editor when PlayAnimationsInEditorScene is on; screenshot to verify. Param names are defined by the model's animation graph — use list_animations to check whether the model is animgraph-driven. Returns { set, param, kind, note } — kind is the type actually applied (float/int/bool/vector).", {
         id: z.string().describe("GUID of the GameObject with a SkinnedModelRenderer"),
         param: z.string().describe("Animgraph parameter name, e.g. 'move_x', 'b_grounded'"),
         value: z

package/dist/tools/cinematicrecording.d.ts

@@ -0,0 +1,31 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Cinematic Recording pair — scripted-run capture + killcam scaffold:
+ *
+ *   - record_playtest   one call = scripted playtest + gameplay recording of the
+ *                       SAME run. Composition of the playtest harness and the
+ *                       Batch 60 MovieRecorder stack: automated regression
+ *                       footage — a failing playtest comes with a replayable
+ *                       clip of exactly what happened.
+ *   - create_killcam    codegen scaffold (sealed Component): rolling-buffer
+ *                       recording + on-death replay via MoviePlayer + a
+ *                       chase-camera takeover of Scene.Camera.
+ *
+ * Live-verified (2026-07-13, Gravehold editor): sandboxed GAME code can
+ * construct + drive MovieRecorder/MoviePlayer at runtime, and
+ * MovieRecorderOptions.BufferDuration is a true rolling buffer — ~8.7s of
+ * recording with a 3s buffer compiled to a clip with Duration exactly 3.00s,
+ * re-based to start at 0. The official recording-api doc
+ * (Facepunch/sbox-docs docs/movie-maker/recording-api.md) confirms game-code
+ * recording is the supported use case and documents
+ * MovieRecorderOptions.Default (a static, invisible to describe_type) +
+ * record `with` syntax — the whole-scene idiom create_killcam's
+ * RecordWholeScene mode generates.
+ *
+ * record_playtest is NOT scene-mutating (it only exists in play mode — the
+ * Batch 60 recording precedent). create_killcam IS scene-mutating (writes a
+ * .cs scaffold to disk, like every create_* scaffold).
+ */
+export declare function registerCinematicRecordingTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=cinematicrecording.d.ts.map

package/dist/tools/cinematicrecording.js

@@ -0,0 +1,107 @@
+import { z } from "zod";
+/**
+ * Cinematic Recording pair — scripted-run capture + killcam scaffold:
+ *
+ *   - record_playtest   one call = scripted playtest + gameplay recording of the
+ *                       SAME run. Composition of the playtest harness and the
+ *                       Batch 60 MovieRecorder stack: automated regression
+ *                       footage — a failing playtest comes with a replayable
+ *                       clip of exactly what happened.
+ *   - create_killcam    codegen scaffold (sealed Component): rolling-buffer
+ *                       recording + on-death replay via MoviePlayer + a
+ *                       chase-camera takeover of Scene.Camera.
+ *
+ * Live-verified (2026-07-13, Gravehold editor): sandboxed GAME code can
+ * construct + drive MovieRecorder/MoviePlayer at runtime, and
+ * MovieRecorderOptions.BufferDuration is a true rolling buffer — ~8.7s of
+ * recording with a 3s buffer compiled to a clip with Duration exactly 3.00s,
+ * re-based to start at 0. The official recording-api doc
+ * (Facepunch/sbox-docs docs/movie-maker/recording-api.md) confirms game-code
+ * recording is the supported use case and documents
+ * MovieRecorderOptions.Default (a static, invisible to describe_type) +
+ * record `with` syntax — the whole-scene idiom create_killcam's
+ * RecordWholeScene mode generates.
+ *
+ * record_playtest is NOT scene-mutating (it only exists in play mode — the
+ * Batch 60 recording precedent). create_killcam IS scene-mutating (writes a
+ * .cs scaffold to disk, like every create_* scaffold).
+ */
+export function registerCinematicRecordingTools(server, bridge) {
+    const reply = (res) => res.success
+        ? { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] }
+        : { content: [{ type: "text", text: `Error: ${res.error}` }] };
+    // ── record_playtest ───────────────────────────────────────────────
+    server.tool("record_playtest", [
+        "Run a scripted playtest AND record the same run to a .movie clip in ONE call — automated regression footage: a failing playtest comes with a replayable clip of exactly what happened. REQUIRES play mode (start_play first).",
+        "steps uses the EXACT playtest schema (one verb per step: move / look / lookDelta / action / jump / set / wait / capture / assert — see the playtest tool for the full verb reference). The recording defaults to the playtest's resolved player hierarchy; pass ids to record other objects, or nothing resolvable falls back to whole-scene capture (heavy).",
+        "Returns { started, steps, recordingJobId, capture, sampleRate, clipName, folder, recorderCapSeconds, note } immediately; both jobs run ASYNC in the editor frame loop and the clip AUTO-SAVES the moment the playtest finishes (a failing or aborted run still saves its footage; play mode ending early is also saved).",
+        "THE POLL CHAIN: 1) playtest_status until finished:true → the per-step pass/fail transcript. 2) gameplay_recording_status → the saved clip summary { saved, assetPath, durationSeconds, trackCount } (if it still says pendingSave, the save is a frame away — poll again; a save error there means name collision: call stop_gameplay_recording yourself with a new name).",
+        "Replay the footage with add_movie_player + play_movie. Errors if a playtest or gameplay recording is already active. Only one at a time.",
+    ].join("\n"), {
+        steps: z
+            .array(z.record(z.string(), z.any()))
+            .describe("Ordered playtest step objects — identical schema to the playtest tool (move/look/lookDelta/action/jump/set/wait/capture/assert). Runs top-to-bottom in the frame loop."),
+        id: z
+            .string()
+            .optional()
+            .describe("GUID of the player/controller GameObject the playtest drives. Omit to auto-resolve the first PlayerController."),
+        component: z
+            .string()
+            .optional()
+            .describe("Controller component type to target (e.g. 'PlayerController'). Omit to auto-detect."),
+        ids: z
+            .array(z.string())
+            .optional()
+            .describe("GameObject GUIDs to RECORD (from get_scene_hierarchy WHILE PLAYING). Omit to record the playtest's player hierarchy (the default and usually what you want)."),
+        sampleRate: z
+            .number()
+            .int()
+            .optional()
+            .describe("Recording samples per second (default 30, clamped 1-120)"),
+        clipName: z
+            .string()
+            .optional()
+            .describe("Saved .movie asset name without extension (default playtest_<UTC timestamp>; sanitized to [A-Za-z0-9_-])"),
+        folder: z
+            .string()
+            .optional()
+            .describe('Assets subfolder to save the clip into (default "recordings")'),
+    }, async (params) => reply(await bridge.send("record_playtest", params)));
+    // ── create_killcam ────────────────────────────────────────────────
+    server.tool("create_killcam", [
+        "Generate a sealed killcam Component: a rolling-buffer MovieRecorder keeps ONLY the last MaxBufferSeconds of a target's gameplay (BufferDuration verified live: the compiled clip's Duration equals the buffer, re-based to 0), and TriggerReplay() plays that history back through a MoviePlayer while the main camera chase-follows the target (Scene.Camera takeover in OnPreRender, restored exactly afterwards; static OnReplayFinished event + IsReplaying flag).",
+        "Sandbox-safe: live-verified that GAME code can construct and drive MovieRecorder/MoviePlayer at runtime, and killcams/replays are the official recording-api use case — this is the real MovieMaker path, not a transform-history approximation. The replay REWINDS THE LIVE TARGET through its recorded past (classic killcam — the target is dead/inactive when it runs; disable a still-alive controller for the duration). wholeScene:true makes the generated component default to MovieRecorderOptions.Default (all renderers/cameras/sound points/particles — the replay rewinds everything, killer included; heavy in dense scenes), and it stays toggleable per-instance via the RecordWholeScene property.",
+        "Returns { created, path, className, bufferSeconds, sampleRate, cameraDistance, cameraHeight, nextSteps }. Then: trigger_hotload → attach to a MANAGER object → set_component_reference Target to the player → arm via WatchOnStart or StartWatching() from spawn code → call TriggerReplay() from death code (pairs with create_health_system). LOCAL/visual-only — wrap in an [Rpc.Broadcast] for all clients. Refuses if the file already exists.",
+    ].join("\n"), {
+        name: z
+            .string()
+            .optional()
+            .describe('Component class/file name (default "Killcam")'),
+        directory: z
+            .string()
+            .optional()
+            .describe('Project folder for the .cs file (default "Code")'),
+        bufferSeconds: z
+            .number()
+            .optional()
+            .describe("Rolling-buffer length in seconds — the replay shows at most this much history (default 10, clamped 2-120)"),
+        sampleRate: z
+            .number()
+            .int()
+            .optional()
+            .describe("Recorder samples per second (default 30, clamped 1-120)"),
+        cameraDistance: z
+            .number()
+            .optional()
+            .describe("Replay chase-camera distance behind the target (default 150, clamped 10-2000)"),
+        cameraHeight: z
+            .number()
+            .optional()
+            .describe("Replay chase-camera height above the target (default 60, clamped 0-2000)"),
+        wholeScene: z
+            .boolean()
+            .optional()
+            .describe("Generated default for RecordWholeScene: true = buffer the WHOLE scene via MovieRecorderOptions.Default (replay rewinds everything; heavy in dense scenes), false = only the Target hierarchy (default)"),
+    }, async (params) => reply(await bridge.send("create_killcam", params)));
+}
+//# sourceMappingURL=cinematicrecording.js.map

package/dist/tools/cinematics.js

@@ -16,7 +16,7 @@ import { z } from "zod";
  */
 export function registerCinematicsTools(server, bridge) {
     // ── create_cutscene_director ──────────────────────────────────────
-    server.tool("create_cutscene_director", "Generate a hand-authored cutscene player component that needs NO .movie asset — the zero-asset alternative to the MovieMaker family (add_movie_player/play_movie, which play keyframed .movie clips authored in the editor's Movie Maker dock). You author the shots directly in the inspector as parallel lists: ShotPositions (Vector3), ShotAngles (pitch/yaw/roll — Angles, not raw quaternions), ShotHoldSeconds, ShotBlendSeconds, and an optional per-shot ShotLookAt GameObject (aim at a target instead of using ShotAngles). At runtime it takes over the main camera (Scene.Camera) in OnPreRender ONLY while playing — smoothstep-eased Vector3.Lerp + Rotation.Slerp between shots — captures the camera's prior transform and restores it exactly when finished (same un-apply discipline as create_camera_shake). Play from any game code via the static <Name>.Play() (first director) or <Name>.Play(\"name\") (matches CutsceneName); subscribe the static <Name>.OnCutsceneFinished, or gate game logic on the static <Name>.IsCutscenePlaying. LockInput freezes player input each frame via Input.ClearActions() while still reading the SkipAction press first so the cutscene stays skippable. Optional letterbox generates a razor_lint-safe black-bars overlay panel (host under a ScreenPanel) shown while IsCutscenePlaying. LOCAL-only (each client renders its own view) — trigger inside an [Rpc.Broadcast] for all clients. Attach to ANY GameObject; it drives the camera itself and does not need to sit on the camera. Compile with trigger_hotload afterward.", {
+    server.tool("create_cutscene_director", "Generate a hand-authored cutscene player component that needs NO .movie asset — the zero-asset alternative to the MovieMaker family (add_movie_player/play_movie, which play keyframed .movie clips authored in the editor's Movie Maker dock). You author the shots directly in the inspector as parallel lists: ShotPositions (Vector3), ShotAngles (pitch/yaw/roll — Angles, not raw quaternions), ShotHoldSeconds, ShotBlendSeconds, and an optional per-shot ShotLookAt GameObject (aim at a target instead of using ShotAngles). At runtime it takes over the main camera (Scene.Camera) in OnPreRender ONLY while playing — smoothstep-eased Vector3.Lerp + Rotation.Slerp between shots — captures the camera's prior transform and restores it exactly when finished (same un-apply discipline as create_camera_shake). Play from any game code via the static <Name>.Play() (first director) or <Name>.Play(\"name\") (matches CutsceneName); subscribe the static <Name>.OnCutsceneFinished, or gate game logic on the static <Name>.IsCutscenePlaying. LockInput freezes player input each frame via Input.ClearActions() while still reading the SkipAction press first so the cutscene stays skippable. Optional letterbox generates a razor_lint-safe black-bars overlay panel (host under a ScreenPanel) shown while IsCutscenePlaying. LOCAL-only (each client renders its own view) — trigger inside an [Rpc.Broadcast] for all clients. Attach to ANY GameObject; it drives the camera itself and does not need to sit on the camera. Returns { created, path, className, skipAction, lockInput, letterbox, nextSteps } — path is the generated .cs (letterbox lists the overlay files when enabled). Follow with trigger_hotload, then get_compile_errors, then attach via add_component_with_properties (component=className).", {
         name: z
             .string()
             .optional()
@@ -45,7 +45,7 @@ export function registerCinematicsTools(server, bridge) {
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
     // ── create_dialogue_system ────────────────────────────────────────
-    server.tool("create_dialogue_system", "Generate an NPC/story dialogue system — a sealed state+data Component paired with a razor_lint-safe Razor HUD panel. Lines are authored in the inspector as a List<string> using the 'Speaker: text' convention (the part before the first colon is the speaker). The generated HUD panel binds to <Name>.Current automatically (no wiring) and renders the current line with a TimeSince-driven typewriter reveal at CharsPerSecond, folding the visible substring into BuildHash so it re-renders as characters appear. Press the AdvanceAction once to snap the whole line into view instantly, again to move to the next line; dismissing the last line ends the conversation. Start from any game code via the static <Name>.StartDialogue(string[] lines) or set Lines and call the instance Begin(). Static events for hooks: OnLineShown(index, speaker) — pair with add_lipsync to drive facial morphs / audio per line — and OnDialogueFinished when the conversation ends. Pairs with create_interactable to trigger dialogue on use. LOCAL-only (per-client HUD) — call StartDialogue inside an [Rpc.Broadcast] if every client should see it. Attach the panel under a ScreenPanel (add_screen_panel) so the HUD renders. Compile with trigger_hotload afterward.", {
+    server.tool("create_dialogue_system", "Generate an NPC/story dialogue system — a sealed state+data Component paired with a razor_lint-safe Razor HUD panel. Lines are authored in the inspector as a List<string> using the 'Speaker: text' convention (the part before the first colon is the speaker). The generated HUD panel binds to <Name>.Current automatically (no wiring) and renders the current line with a TimeSince-driven typewriter reveal at CharsPerSecond, folding the visible substring into BuildHash so it re-renders as characters appear. Press the AdvanceAction once to snap the whole line into view instantly, again to move to the next line; dismissing the last line ends the conversation. Start from any game code via the static <Name>.StartDialogue(string[] lines) or set Lines and call the instance Begin(). Static events for hooks: OnLineShown(index, speaker) — pair with add_lipsync to drive facial morphs / audio per line — and OnDialogueFinished when the conversation ends. Pairs with create_interactable to trigger dialogue on use. LOCAL-only (per-client HUD) — call StartDialogue inside an [Rpc.Broadcast] if every client should see it. Attach the panel under a ScreenPanel (add_screen_panel) so the HUD renders. Returns { created, path, className, charsPerSecond, advanceAction, panel, nextSteps } — panel lists the generated '<Name>Panel' HUD files. Follow with trigger_hotload, then get_compile_errors, then attach both components via add_component_with_properties.", {
         name: z
             .string()
             .optional()

package/dist/tools/components.js

@@ -24,7 +24,7 @@ export function registerComponentTools(server, bridge) {
         };
     });
     // ── get_all_properties ───────────────────────────────────────────
-    server.tool("get_all_properties", "Dump all public properties of every component on a GameObject as JSON -- names, types, and current values", {
+    server.tool("get_all_properties", "Dump all public properties of every component on a GameObject. Returns { id, components } where each entry is { component, properties: [{ name, type, value }] } — values are stringified (unreadable ones show '<error>'). Use the exact component/property names it reports with set_property or get_property; can be large on component-heavy objects.", {
         id: z.string().describe("GUID of the GameObject"),
     }, async (params) => {
         const res = await bridge.send("get_all_properties", params);
@@ -36,7 +36,7 @@ export function registerComponentTools(server, bridge) {
         };
     });
     // ── list_available_components ────────────────────────────────────
-    server.tool("list_available_components", "List all component types available in s&box (built-in and custom). Search by name or filter by category", {
+    server.tool("list_available_components", "List all instantiable component types in the TypeLibrary — built-in AND your project's custom components (abstract types excluded); filter does a substring match on the type name. Returns { count, components } with { name, title, description, fullName } per type, sorted by name — the unfiltered list is LARGE, so pass filter. Use the returned name with add_component_with_properties, and describe_type for a type's full property list.", {
         filter: z
             .string()
             .optional()

package/dist/tools/debugdraw.js

@@ -28,25 +28,25 @@ export function registerDebugDrawTools(server, bridge) {
         color,
         thickness,
     }, async (p) => reply(await bridge.send("debug_draw_line", p)));
-    server.tool("debug_draw_ray", "Draw a debug ray (drawn as an arrow) from an origin along a direction for a given length. Renders in editor and play. Ideal for visualizing a raycast result or a facing/normal direction. Accumulates until debug_clear.", {
+    server.tool("debug_draw_ray", "Draw a debug ray (drawn as an arrow) from an origin along a direction for a given length. Renders in editor and play. Ideal for visualizing a raycast result or a facing/normal direction. Accumulates until debug_clear. Returns { drawn: 'ray', count, mode } — count is the total accumulated primitives, mode is 'edit' or 'play' (edit-mode gizmos are NOT in take_screenshot; use capture_view in play mode).", {
         origin: z.string().describe('Ray origin, world-space "x,y,z"'),
         direction: z.string().describe('Direction vector "x,y,z" (normalized internally)'),
         length: z.number().optional().describe("Ray length in units (default 64)"),
         color,
         thickness,
     }, async (p) => reply(await bridge.send("debug_draw_ray", p)));
-    server.tool("debug_draw_box", "Draw a wireframe debug box centered at a point. Renders in editor and play. Ideal for visualizing a trigger_zone's bounds or a physics_overlap box volume. Accumulates until debug_clear.", {
+    server.tool("debug_draw_box", "Draw a wireframe debug box centered at a point. Renders in editor and play. Ideal for visualizing a trigger_zone's bounds or a physics_overlap box volume. Accumulates until debug_clear. Returns { drawn: 'box', count, mode } — count is the total accumulated primitives, mode is 'edit' or 'play' (edit-mode gizmos are NOT in take_screenshot; use capture_view in play mode).", {
         center: z.string().describe('Box center, world-space "x,y,z"'),
         size: z.string().optional().describe('Full size "x,y,z" in units (default "32,32,32")'),
         color,
         thickness,
     }, async (p) => reply(await bridge.send("debug_draw_box", p)));
-    server.tool("debug_draw_sphere", "Draw a wireframe debug sphere at a point. Renders in editor and play. Ideal for visualizing a physics_overlap radius or an NPC's hearing/sight range. Accumulates until debug_clear.", {
+    server.tool("debug_draw_sphere", "Draw a wireframe debug sphere at a point. Renders in editor and play. Ideal for visualizing a physics_overlap radius or an NPC's hearing/sight range. Accumulates until debug_clear. Returns { drawn: 'sphere', count, mode } — count is the total accumulated primitives, mode is 'edit' or 'play' (edit-mode gizmos are NOT in take_screenshot; use capture_view in play mode).", {
         center: z.string().describe('Sphere center, world-space "x,y,z"'),
         radius: z.number().optional().describe("Radius in units (default 32)"),
         color,
         thickness,
     }, async (p) => reply(await bridge.send("debug_draw_sphere", p)));
-    server.tool("debug_clear", "Remove all debug-draw primitives by destroying the debug holder for the current scene (edit or play). Call before redrawing a fresh frame of debug shapes.", {}, async (p) => reply(await bridge.send("debug_clear", p)));
+    server.tool("debug_clear", "Remove ALL debug-draw primitives at once by destroying the debug holder for the current scene (edit or play) — there is no way to remove a single shape. Call before redrawing a fresh frame of debug shapes. Returns { cleared, removed } where removed is how many primitives were destroyed.", {}, async (p) => reply(await bridge.send("debug_clear", p)));
 }
 //# sourceMappingURL=debugdraw.js.map

package/dist/tools/diagnostics.js

@@ -281,7 +281,7 @@ export function registerDiagnosticTools(server, bridge) {
         };
     });
     // ── console_run ──────────────────────────────────────────────────── (bridge)
-    server.tool("console_run", "Run an s&box console command / ConCmd via Sandbox.ConsoleSystem.Run — e.g. a cvar ('sv_cheats 1') or a registered command. Also the invocation primitive behind execute_csharp.", {
+    server.tool("console_run", "Run an s&box console command / ConCmd via Sandbox.ConsoleSystem.Run — e.g. a cvar ('sv_cheats 1') or a registered command. Also the invocation primitive behind execute_csharp. Fire-and-forget: returns only { ran, command } and does NOT capture console output — follow with read_log to see what the command printed.", {
         command: z.string().describe("The console command line to run"),
     }, async (params) => {
         const res = await bridge.send("console_run", params);
@@ -310,14 +310,16 @@ export function registerDiagnosticTools(server, bridge) {
         const cmd = `claude_exec_${id}`;
         const filePath = `Editor/__Exec_${id}.cs`;
         const marker = `[EXEC ${id}]`;
+        // Bare `Log` (via `using Sandbox;`), NOT `Sandbox.Log` — the latter stopped
+        // resolving in project editor assemblies on engine 26.07.08b and broke every call.
         const inner = params.expression
-            ? `var __r = (${params.code});\n\t\t\tSandbox.Log.Info( "${marker} RESULT=" + System.Text.Json.JsonSerializer.Serialize( __r ) );`
-            : `${params.code}\n\t\t\tSandbox.Log.Info( "${marker} DONE" );`;
+            ? `var __r = (${params.code});\n\t\t\tLog.Info( "${marker} RESULT=" + System.Text.Json.JsonSerializer.Serialize( __r ) );`
+            : `${params.code}\n\t\t\tLog.Info( "${marker} DONE" );`;
         const cs = `using Editor;\nusing Sandbox;\nusing System;\n\n` +
             `public static class __Exec_${id}\n{\n` +
             `\t[ConCmd( "${cmd}" )]\n\tpublic static void Run()\n\t{\n` +
             `\t\ttry\n\t\t{\n\t\t\t${inner}\n\t\t}\n` +
-            `\t\tcatch ( System.Exception __e ) { Sandbox.Log.Error( "${marker} ERROR=" + __e.Message ); }\n` +
+            `\t\tcatch ( System.Exception __e ) { Log.Error( "${marker} ERROR=" + __e.Message ); }\n` +
             `\t}\n}\n`;
         const timeout = params.timeoutMs ?? 20000;
         const wr = await bridge.send("write_file", { path: filePath, content: cs });
@@ -390,7 +392,7 @@ export function registerDiagnosticTools(server, bridge) {
         };
     });
     // ── get_bounds ─────────────────────────────────────────────────────── (bridge, Batch 33)
-    server.tool("get_bounds", "Get a GameObject's world-space bounding box — center, size, extents, mins/maxs, and a radius. Useful for placing/framing objects and sizing camera moves. Reads GameObject.GetBounds(); objects with no renderer report empty:true with their world position.", {
+    server.tool("get_bounds", "Get a GameObject's world-space bounding box. Returns { id, name, center, size, extents, mins, maxs, radius, position, empty } — objects with no renderer report empty:true (bounds collapse to the world position) plus an explanatory note. Feed center/radius into screenshot_from or frame_camera to frame the object, or use mins/maxs for placement math (screenshot_orbit calls this internally).", {
         id: z.string().describe("GUID of the GameObject to measure"),
     }, async (params) => {
         const res = await bridge.send("get_bounds", params);

package/dist/tools/dialoguefx.d.ts

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