sbox-mcp-server 1.20.0 → 2.1.0

package/dist/tools/gameplayrecorder.js

@@ -0,0 +1,73 @@
+import { z } from "zod";
+/**
+ * Gameplay Recording family — record live PLAY-MODE gameplay to a .movie clip
+ * via Sandbox.MovieMaker.MovieRecorder (shipped in the current editor build,
+ * verified live 2026-07-12; closes engine-watch #2 in docs/TOOL_BACKLOG.md):
+ *
+ *   - record_gameplay_clip       start an async frame-loop recording job
+ *   - stop_gameplay_recording    stop → persist as a project .movie asset
+ *   - gameplay_recording_status  poll the job
+ *
+ * The counterpart to the MovieMaker playback family (list_movies /
+ * add_movie_player / play_movie / stop_movie): those play clips, this CREATES
+ * them from live gameplay. None of the three are scene-mutating — they must
+ * stay callable during play mode, where recording lives.
+ */
+export function registerGameplayRecorderTools(server, bridge) {
+    // ── record_gameplay_clip ──────────────────────────────────────────
+    server.tool("record_gameplay_clip", "Start recording live play-mode gameplay into a Sandbox.MovieMaker clip — REQUIRES play mode (start_play first; errors otherwise). Captures the given GameObjects (ids — recommended: small focused clips) or, when ids is omitted, the WHOLE scene (heavy: every object becomes tracks). Returns { started, jobId, sampleRate, maxSeconds, capture, discarded, note } immediately; recording runs ASYNC in the editor frame loop until stop_gameplay_recording or the maxSeconds safety cap (default 60s of clip time, max 600s). Only one recording at a time (a second call errors while active; a stopped-but-unsaved clip is discarded by a new start, reported in 'discarded'). Combine with playtest or drive_player to record a SCRIPTED run, then stop_gameplay_recording to save the .movie and play_movie to replay it.", {
+        ids: z
+            .array(z.string())
+            .optional()
+            .describe("GameObject GUIDs to capture (from get_scene_hierarchy WHILE PLAYING — play-mode ids can differ from editor ids). Omit to capture the whole scene (heavy)"),
+        sampleRate: z
+            .number()
+            .int()
+            .optional()
+            .describe("Samples per second (default 30, clamped 1-120)"),
+        maxSeconds: z
+            .number()
+            .optional()
+            .describe("Safety cap — auto-stops the recording once the clip timeline reaches this many seconds (default 60, clamped 1-600). The clip stays in memory until stop_gameplay_recording saves it"),
+    }, async (params) => {
+        const res = await bridge.send("record_gameplay_clip", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── stop_gameplay_recording ───────────────────────────────────────
+    server.tool("stop_gameplay_recording", "Stop the active gameplay recording and persist it as a project .movie asset the editor can load (written to Assets/<folder>/<name>.movie, registered + compiled — list_movies then shows it with hasCompiledClip). Also saves a job that already auto-stopped (maxSeconds cap, or play mode ended). Returns { saved, assetPath, durationSeconds, trackCount, sampleRate, compiled, stopReason, wired, note } — a trackCount of 0 means nothing was captured and the response warns about it. Pass wireToId to auto-wire a MoviePlayer on that GameObject pointed at the new clip (during play mode that wiring is RUNTIME-ONLY and discarded on stop_play; the .movie asset itself always persists). Errors if the target file already exists (the clip stays in memory — retry with another name). discard:true throws the recording away instead. Replay: add_movie_player + play_movie in play mode.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Asset name without extension (default recording_<UTC timestamp>; sanitized to [A-Za-z0-9_-])"),
+        folder: z
+            .string()
+            .optional()
+            .describe('Assets subfolder to save into (default "recordings")'),
+        wireToId: z
+            .string()
+            .optional()
+            .describe("GameObject GUID to auto-wire a MoviePlayer at the new clip (runtime-only if done during play mode)"),
+        discard: z
+            .boolean()
+            .optional()
+            .describe("Throw the recording away instead of saving it"),
+    }, async (params) => {
+        const res = await bridge.send("stop_gameplay_recording", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── gameplay_recording_status ─────────────────────────────────────
+    server.tool("gameplay_recording_status", "Poll the gameplay recording job. While recording returns { recording:true, jobId, elapsedSeconds (clip-timeline seconds), framesWithData, maxSeconds, sampleRate, capture, trackedObjectCount } (trackedObjectCount is -1 for whole-scene capture). After an auto-stop (maxSeconds cap / play mode ended) returns { stopped:true, pendingSave:true, reason } — the clip is in memory awaiting stop_gameplay_recording. After a save/discard returns that last summary (assetPath etc.). Read-only; works during play. No params.", {}, async () => {
+        const res = await bridge.send("gameplay_recording_status", {});
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+}
+//# sourceMappingURL=gameplayrecorder.js.map

package/dist/tools/inspection.js

@@ -14,7 +14,7 @@ import { z } from "zod";
  */
 export function registerInspectionTools(server, bridge) {
     // ── inspect_networked_object ──────────────────────────────────────
-    server.tool("inspect_networked_object", "Inspect the live networking contract of a GameObject: Network.Owner/IsProxy/IsOwner/Active, OwnerTransfer + OrphanedMode, and every component's [Sync] property names, SyncFlags, and current values (host vs proxy). Unlike get_network_status (session-only), this is per-object — the way to verify a host-authoritative or ownership change actually replicated. Works in edit or play mode.", {
+    server.tool("inspect_networked_object", "Inspect the live networking contract of a GameObject. Returns {id, name, network: {active, isProxy, isOwner, isCreator, ownerId, ownerSteamId, ownerTransfer, orphaned, flags}, components: [{component, fields: [{name, type, isSync, syncFlags, value}]}]} — by default only [Sync]-marked fields are listed (components with none are omitted). Unlike get_network_status (session-only), this is per-object — the way to verify a host-authoritative or ownership change actually replicated; works in edit or play mode. Follow up with set_ownership to change the owner, or networking_lint to find the code-level cause of a bad [Sync] value.", {
         id: z.string().describe("GUID of the GameObject to inspect"),
         allProps: z
             .boolean()
@@ -70,8 +70,8 @@ export function registerInspectionTools(server, bridge) {
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
     // ── save_inspect ──────────────────────────────────────────────────
-    server.tool("save_inspect", "Inspect the game's FileSystem.Data save files — the assistant is otherwise blind to persisted state. action='list' enumerates files under a folder (with size/mtime); action='read' dumps a save file's JSON; action='diff' compares two save files key-by-key. Use to verify a save actually wrote, debug a load/migration, or confirm a sanitize/clamp ran.", {
-        action: z.enum(["list", "read", "diff"]).default("list"),
+    server.tool("save_inspect", "Inspect the game's FileSystem.Data save files — the assistant is otherwise blind to persisted state. action='list' (default) returns `directories` and `files` [{name, path, size}] under `path` (omit path for the Data root); action='read' returns {path, length, content}, truncating content at 60,000 chars; action='diff' compares two save files key-by-key, returning `diffCount` and up to 200 `diffs` [{key, change: added|removed|changed}]. Use to verify a save actually wrote, debug a load/migration, or confirm a sanitize/clamp ran.", {
+        action: z.enum(["list", "read", "diff"]).default("list").describe("'list' (default) enumerates a folder; 'read' dumps one file's JSON; 'diff' compares `path` vs `pathB`"),
         path: z
             .string()
             .optional()
@@ -87,8 +87,8 @@ export function registerInspectionTools(server, bridge) {
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
     // ── services_query ────────────────────────────────────────────────
-    server.tool("services_query", "Read from Sandbox.Services — the cloud stats/leaderboard layer many games use as their real DB. action='stats' lists/reads the project's stat definitions and the local player's values; action='leaderboard' fetches a leaderboard board's top entries. Read-only. Use to verify a Stats.Increment/SetValue path or a leaderboard wired correctly.", {
-        action: z.enum(["stats", "leaderboard"]).default("stats"),
+    server.tool("services_query", "Read from Sandbox.Services — the cloud stats/leaderboard layer many games use as their real DB. action='stats' with `name` returns the local player's stat {ident, value, sum, min, max, lastValue, valueString}; without `name` it returns only the package ident plus a usage note (it does NOT list stat definitions). action='leaderboard' (name required) returns {board, displayName, totalEntries, count, entries} with at most `limit` entries (default 10). Read-only; use to verify a Stats.Increment/SetValue path or a leaderboard wired correctly.", {
+        action: z.enum(["stats", "leaderboard"]).default("stats").describe("'stats' (default) reads a local-player stat by `name`; 'leaderboard' fetches a board's top entries"),
         name: z
             .string()
             .optional()
@@ -101,7 +101,7 @@ export function registerInspectionTools(server, bridge) {
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
     // ── simulate_input ────────────────────────────────────────────────
-    server.tool("simulate_input", "Synthesize player input during PLAY mode so behavior can be verified without a human at the keyboard: press/hold/release a named input action (e.g. 'jump','attack1','use','reload') and/or set AnalogMove / AnalogLook for a duration. Drives movement, IPressable interactions, weapon fire/cooldown/reload, vehicle controls, and HUD advance-on-click. Requires play mode.", {
+    server.tool("simulate_input", "Press or release a named input action during PLAY mode (via Sandbox.Input.SetAction) so input-driven behavior — jump, attack1, use, reload, IPressable, weapon fire — can be verified without a human at the keyboard. REQUIRES play mode and a named `action`; returns {action, state: 'down'|'up', note}. Caveats: SetAction applies to the current input frame ('press' and 'hold' both set the action down; 'release' clears it), and analogMove/analogLook/durationMs are accepted but IGNORED — Sandbox.Input has no analog injection API, so for movement use drive_player or the playtest harness instead.", {
         action: z
             .string()
             .optional()

package/dist/tools/leveltools.js

@@ -28,7 +28,7 @@ const ColorSchema = z
     .describe('RGBA colour — object {r,g,b,a} (0-1) OR comma string "r,g,b,a"');
 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.", {
+    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. Returns { snapped, groundZ, gameObject } with the object's updated transform — or { snapped: false, reason } (not an error) when no ground was hit below.", {
         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)"),
@@ -43,7 +43,7 @@ export function registerLevelTools(server, bridge) {
         };
     });
     // ── 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.", {
+    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; defaults to first. Returns { aligned, axis, mode, target } — aligned is the object count and target the shared coordinate; verify positions with get_scene_hierarchy or a screenshot.", {
         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
@@ -60,7 +60,7 @@ export function registerLevelTools(server, bridge) {
         };
     });
     // ── 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).", {
+    server.tool("distribute_objects", "Evenly space GameObjects along an axis between the lowest and highest (keeps the two ends fixed, spreads the rest evenly). Returns { distributed, axis, from, to } — the object count and the fixed end coordinates the rest were spread between.", {
         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) => {
@@ -104,7 +104,7 @@ export function registerLevelTools(server, bridge) {
         };
     });
     // ── 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.", {
+    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. Returns { scattered, groupId, seed } — individual prop GUIDs are not returned, so use groupId with get_scene_hierarchy (rootId) to enumerate them, or with set_transform/delete_gameobject to move/remove the whole batch.", {
         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)"),
@@ -129,7 +129,7 @@ export function registerLevelTools(server, bridge) {
         };
     });
     // ── 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.", {
+    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 — the same seed reproduces the same layout. Returns { randomized, seed } (the count of objects changed); scale only varies when scaleMax > scaleMin.", {
         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)"),

package/dist/tools/materials.js

@@ -5,7 +5,7 @@ import { z } from "zod";
  */
 export function registerMaterialTools(server, bridge) {
     // ── assign_model ─────────────────────────────────────────────────
-    server.tool("assign_model", "Set a 3D model on a GameObject's ModelRenderer. Creates the renderer component if it doesn't exist", {
+    server.tool("assign_model", "Set a 3D model on a GameObject's ModelRenderer. Creates the renderer component if it doesn't exist; errors if the model path can't be loaded. Returns { assigned, id, model } — follow with assign_material / set_material_property to style it, or take a screenshot to verify.", {
         id: z.string().describe("GUID of the GameObject"),
         model: z
             .string()
@@ -20,7 +20,7 @@ export function registerMaterialTools(server, bridge) {
         };
     });
     // ── create_material ──────────────────────────────────────────────
-    server.tool("create_material", "Create a new material file (.vmat) with a shader and properties like color, roughness, metallic, texture", {
+    server.tool("create_material", "Create a new material file (.vmat, KV1 format) with a shader and properties like color, roughness, metallic, texture. Errors if the file already exists; when no properties are given it writes sensible PBR defaults (g_flMetalness 0, g_flRoughness 1). Returns { created, path, shader, propertiesWritten } — pass the returned path to recompile_asset (so the editor compiles it) and then assign_material.", {
         path: z
             .string()
             .describe("Relative path for the material (e.g. 'materials/walls/brick.vmat')"),
@@ -42,7 +42,7 @@ export function registerMaterialTools(server, bridge) {
         };
     });
     // ── assign_material ──────────────────────────────────────────────
-    server.tool("assign_material", "Apply a material to a ModelRenderer on a GameObject. Optionally target a specific material slot", {
+    server.tool("assign_material", "Apply a material to a GameObject by setting its ModelRenderer's MaterialOverride (overrides the whole model's material). Requires an existing ModelRenderer (assign_model first) and errors if the material path can't be loaded. Returns { assigned, id, material } — tweak values afterwards with set_material_property.", {
         id: z.string().describe("GUID of the GameObject"),
         material: z
             .string()
@@ -61,7 +61,7 @@ export function registerMaterialTools(server, bridge) {
         };
     });
     // ── set_material_property ────────────────────────────────────────
-    server.tool("set_material_property", "Change a property on the material assigned to a GameObject — color, roughness, metallic, texture, etc.", {
+    server.tool("set_material_property", "Change a property on the material assigned to a GameObject — color, roughness, metallic, texture, etc. Operates on the ModelRenderer's MaterialOverride; if none is assigned it auto-creates one from the default complex shader (no separate assign_material step needed). Returns { set, id, property, autoCreatedMaterial } — screenshot to verify the visual change.", {
         id: z.string().describe("GUID of the GameObject"),
         property: z
             .string()

package/dist/tools/movieauthoring.d.ts

@@ -0,0 +1,31 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Movie Authoring family — author a .movie cutscene clip from a declarative
+ * shot list, deterministically, in EDIT mode. No Movie Maker dock, no play
+ * mode, no real-time waiting: the whole clip bakes inside one handler call.
+ *
+ *   - author_movie_clip   shot list → keyframe timeline → baked .movie asset
+ *
+ * The mechanism (docs/BRIDGE_GOTCHAS.md §13, flipped around): in EDIT mode
+ * MovieRecorder does NOT auto-advance, so manual Advance(1/sampleRate) +
+ * Capture() per synthetic frame produces EXACT manual durations. This is the
+ * OFFICIAL in-editor recording idiom (sbox-docs movie-maker/recording-api.md:
+ * "Instead of Start and Stop, call Advance ... and Capture to record a
+ * frame"). The handler steps a camera (temp or borrowed) through hold+blend
+ * segments and pumps the recorder one frame at a time. Proven live
+ * 2026-07-13: positions decode back exactly (x = 100·t), and FOV IS captured
+ * when the CameraComponent is explicitly targeted (WithCaptureComponent) —
+ * so fovDegrees is real. E2E: a 3-shot 3.5s bake took 6ms, listed loadable,
+ * played to positionSeconds=3.5 in play mode, and add_movie_player
+ * createTargets:true recreated the destroyed temp camera.
+ *
+ * Completes the MovieMaker triangle: list/add_movie_player/play/stop PLAY
+ * clips, record_gameplay_clip CAPTURES live play-mode gameplay, and this
+ * AUTHORS clips from data. Scene-mutating (creates/borrows-and-moves a camera
+ * and writes a project asset) — registered in _sceneMutatingCommands; it also
+ * refuses play mode itself, because the recorder auto-advances there and a
+ * manual bake would double-count.
+ */
+export declare function registerMovieAuthoringTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=movieauthoring.d.ts.map

package/dist/tools/movieauthoring.js

@@ -0,0 +1,84 @@
+import { z } from "zod";
+/**
+ * Movie Authoring family — author a .movie cutscene clip from a declarative
+ * shot list, deterministically, in EDIT mode. No Movie Maker dock, no play
+ * mode, no real-time waiting: the whole clip bakes inside one handler call.
+ *
+ *   - author_movie_clip   shot list → keyframe timeline → baked .movie asset
+ *
+ * The mechanism (docs/BRIDGE_GOTCHAS.md §13, flipped around): in EDIT mode
+ * MovieRecorder does NOT auto-advance, so manual Advance(1/sampleRate) +
+ * Capture() per synthetic frame produces EXACT manual durations. This is the
+ * OFFICIAL in-editor recording idiom (sbox-docs movie-maker/recording-api.md:
+ * "Instead of Start and Stop, call Advance ... and Capture to record a
+ * frame"). The handler steps a camera (temp or borrowed) through hold+blend
+ * segments and pumps the recorder one frame at a time. Proven live
+ * 2026-07-13: positions decode back exactly (x = 100·t), and FOV IS captured
+ * when the CameraComponent is explicitly targeted (WithCaptureComponent) —
+ * so fovDegrees is real. E2E: a 3-shot 3.5s bake took 6ms, listed loadable,
+ * played to positionSeconds=3.5 in play mode, and add_movie_player
+ * createTargets:true recreated the destroyed temp camera.
+ *
+ * Completes the MovieMaker triangle: list/add_movie_player/play/stop PLAY
+ * clips, record_gameplay_clip CAPTURES live play-mode gameplay, and this
+ * AUTHORS clips from data. Scene-mutating (creates/borrows-and-moves a camera
+ * and writes a project asset) — registered in _sceneMutatingCommands; it also
+ * refuses play mode itself, because the recorder auto-advances there and a
+ * manual bake would double-count.
+ */
+export function registerMovieAuthoringTools(server, bridge) {
+    // ── author_movie_clip ─────────────────────────────────────────────
+    server.tool("author_movie_clip", "Author a MovieMaker .movie cutscene clip from a declarative shot list — EDIT MODE ONLY, no Movie Maker dock, no play mode, no real-time waiting (a 30s clip bakes in one call, typically <1s). Builds a hold+blend keyframe timeline from the shots (smoothstep ease by default), steps a camera through it, and hand-pumps MovieRecorder Advance/Capture per synthetic frame, then saves Assets/<folder>/<clipName>.movie (registered + compiled; errors if the file exists — the scene itself is NOT saved). Returns { authored, path, name, durationSeconds, frames, sampleRate, shots, tracks, bakeMs, compiled, loadable, camera, nextSteps }. Camera: omit cameraId for a temp camera (destroyed after the bake — play back with add_movie_player createTargets:true so the missing target is recreated), or pass cameraId of an existing camera GameObject (transform + FOV restored EXACTLY afterwards; the clip then animates THAT object on playback). fovDegrees is baked for real (the clip carries a FieldOfView track). Authored clips animate ONLY the camera the bake moves — other scene objects don't move in edit mode (that's what record_gameplay_clip is for). Total timeline capped at 120s, max 32 shots. Errors during play mode (stop_play first). Verify with list_movies; play via add_movie_player + play_movie in play mode.", {
+        shots: z
+            .array(z.object({
+            position: z
+                .string()
+                .describe("Camera position for this shot as 'x,y,z'"),
+            lookAt: z
+                .string()
+                .optional()
+                .describe("Aim target: a GameObject GUID (resolved to its world position at bake time) or a world point 'x,y,z'. Omit to keep the previous shot's rotation (first shot: the camera's starting rotation)"),
+            fovDegrees: z
+                .number()
+                .optional()
+                .describe("Field of view in degrees (clamped 5-170), baked into the clip as a FieldOfView track. Omit to carry the previous shot's FOV (first shot: the camera's current FOV)"),
+            holdSeconds: z
+                .number()
+                .optional()
+                .describe("How long to hold this shot's pose (default 1, clamped 0-120)"),
+            blendSeconds: z
+                .number()
+                .optional()
+                .describe("Blend time from the previous shot into this one (default 1, clamped 0-120; ignored on the first shot)"),
+            ease: z
+                .enum(["linear", "smoothstep"])
+                .optional()
+                .describe("Easing of the blend INTO this shot (default smoothstep)"),
+        }))
+            .describe("The shot list in order (1-32 shots). Timeline = hold₀, then blendᵢ + holdᵢ per following shot"),
+        clipName: z
+            .string()
+            .optional()
+            .describe("Asset name without extension (default authored_<UTC timestamp>; sanitized to [A-Za-z0-9_-])"),
+        folder: z
+            .string()
+            .optional()
+            .describe('Assets subfolder to save into (default "movies")'),
+        sampleRate: z
+            .number()
+            .int()
+            .optional()
+            .describe("Clip samples per second (default 30, clamped 1-120)"),
+        cameraId: z
+            .string()
+            .optional()
+            .describe("GUID of an existing camera GameObject (must have a CameraComponent) to bake through — restored EXACTLY afterwards, and playback then animates that object. Omit for a temp camera that is destroyed after the bake"),
+    }, async (params) => {
+        const res = await bridge.send("author_movie_clip", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+}
+//# sourceMappingURL=movieauthoring.js.map

package/dist/tools/moviemaker.js

@@ -14,7 +14,7 @@ import { z } from "zod";
  */
 export function registerMovieMakerTools(server, bridge) {
     // ── list_movies ───────────────────────────────────────────────────
-    server.tool("list_movies", "List the project's .movie resources (Sandbox.MovieMaker clips authored in the editor's Movie Maker dock: Window → Movie Maker). Returns each movie's asset-relative path, whether it currently loads via ResourceLibrary, and whether it has a compiled clip. Start here before add_movie_player / play_movie — and if the list is empty, the movie has to be authored in the dock first (the bridge plays movies; it doesn't author keyframes).", {}, async () => {
+    server.tool("list_movies", "List the project's .movie resources (Sandbox.MovieMaker clips authored in the editor's Movie Maker dock: Window → Movie Maker). Scans the ENTIRE Assets folder recursively and returns every .movie found — no limit or paging. Returns { count, movies, note } where each movie has { path (asset-relative — the form add_movie_player/play_movie expect), name, loadable (resolves via ResourceLibrary), hasCompiledClip }. Start here before add_movie_player / play_movie — if the list is empty, the movie has to be authored in the dock first (the bridge plays movies; it doesn't author keyframes).", {}, async () => {
         const res = await bridge.send("list_movies", {});
         if (!res.success) {
             return { content: [{ type: "text", text: `Error: ${res.error}` }] };

package/dist/tools/multiplayertest.d.ts

@@ -0,0 +1,23 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Multiplayer test harness — host a lobby on the RUNNING game and boot real
+ * sbox.exe clients that auto-join it (the engine's official test path:
+ * networking/testing-multiplayer.md "Join via new instance" / `connect local`,
+ * live-verified through the bridge 2026-07-13):
+ *
+ *   - start_multiplayer_test    CreateLobby (if needed) + spawn N `sbox.exe -joinlocal`
+ *   - multiplayer_test_status   read-only: networking, connections, client PIDs, join-wait
+ *   - stop_multiplayer_test     kill tracked clients (+ optional disconnect / stray sweep)
+ *
+ * The composition this unlocks: start_multiplayer_test → poll status until the guest
+ * joins (~80 s boot) → drive the HOST player (drive_player / playtest) → assert
+ * replication host-side (inspect_networked_object's [Sync] dump, get_runtime_property)
+ * → stop_multiplayer_test. HONEST LIMIT: the bridge cannot see or drive the CLIENT
+ * instance (no bridge runs inside it) — a human can eyeball the client window.
+ *
+ * None of the three are scene-mutating — they must stay callable during play mode,
+ * where the session lives (record_playtest precedent).
+ */
+export declare function registerMultiplayerTestTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=multiplayertest.d.ts.map

package/dist/tools/multiplayertest.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+/**
+ * Multiplayer test harness — host a lobby on the RUNNING game and boot real
+ * sbox.exe clients that auto-join it (the engine's official test path:
+ * networking/testing-multiplayer.md "Join via new instance" / `connect local`,
+ * live-verified through the bridge 2026-07-13):
+ *
+ *   - start_multiplayer_test    CreateLobby (if needed) + spawn N `sbox.exe -joinlocal`
+ *   - multiplayer_test_status   read-only: networking, connections, client PIDs, join-wait
+ *   - stop_multiplayer_test     kill tracked clients (+ optional disconnect / stray sweep)
+ *
+ * The composition this unlocks: start_multiplayer_test → poll status until the guest
+ * joins (~80 s boot) → drive the HOST player (drive_player / playtest) → assert
+ * replication host-side (inspect_networked_object's [Sync] dump, get_runtime_property)
+ * → stop_multiplayer_test. HONEST LIMIT: the bridge cannot see or drive the CLIENT
+ * instance (no bridge runs inside it) — a human can eyeball the client window.
+ *
+ * None of the three are scene-mutating — they must stay callable during play mode,
+ * where the session lives (record_playtest precedent).
+ */
+export function registerMultiplayerTestTools(server, bridge) {
+    const reply = (res) => res.success
+        ? { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] }
+        : { content: [{ type: "text", text: `Error: ${res.error}` }] };
+    // ── start_multiplayer_test ────────────────────────────────────────
+    server.tool("start_multiplayer_test", [
+        "Spin up a REAL multiplayer session for the running game — REQUIRES play mode (start_play first; errors otherwise). Hosts a lobby on the current session if none is active (play mode does NOT host by default) and launches N real sbox.exe game clients with -joinlocal that boot and auto-join — the engine's official multiplayer test path ('Join via new instance' / connect local). The sbox.exe path is auto-resolved (next to the editor process, else Steam library scan) — never hardcoded.",
+        "Returns { hosting, isHost, lobbyCreated, maxPlayers, spawned:[pids], sboxExe, resolvedVia, expectedConnections, jobId?, waitForJoinSeconds, note } IMMEDIATELY. With waitForJoinSeconds > 0 an async frame-loop job (jobId) polls Connection.All.Count until it reaches expectedConnections (host + every tracked client) or times out — poll multiplayer_test_status until joinWait.state is 'complete'. A client takes ~80 SECONDS to boot and join, and uses ~4.5 GB RAM (default clients=1, hard cap 2 total).",
+        "What to do next: once joined, drive the HOST player via drive_player or playtest, and assert replication HOST-SIDE — inspect_networked_object dumps [Sync] state, get_runtime_property reads live values, multiplayer_test_status shows the connection list. Then stop_multiplayer_test to clean up.",
+        "HONEST LIMIT: the bridge CANNOT see or drive the CLIENT instance — no bridge runs inside it. All assertions are host-side; a human can eyeball the client window for visual confirmation.",
+    ].join("\n"), {
+        clients: z
+            .number()
+            .int()
+            .optional()
+            .describe("How many sbox.exe client instances to launch (default 1, hard cap 2 total tracked alive — each uses ~4.5 GB RAM)"),
+        maxPlayers: z
+            .number()
+            .int()
+            .optional()
+            .describe("Lobby capacity (default 4). Only applied when THIS call creates the lobby (via LobbyConfig — Networking.MaxPlayers is read-only); ignored if a session is already active"),
+        waitForJoinSeconds: z
+            .number()
+            .int()
+            .optional()
+            .describe("How long the async join-wait job polls for all clients to connect (default 120, clamped 0-600). 0 = don't wait, return right after spawning. Clients boot in ~80 s — don't set this below ~100 unless polling manually"),
+    }, async (params) => reply(await bridge.send("start_multiplayer_test", params)));
+    // ── multiplayer_test_status ───────────────────────────────────────
+    server.tool("multiplayer_test_status", "Read-only snapshot of the multiplayer test harness — works whether or not a test is running (no test = honest empty state). Returns { networkingActive, isHost, connectionCount, connections:[{name,id,isHost}], clients:[{pid,alive,uptimeSeconds}], joinWait:{state:'none'|'pending'|'complete'|'timeout', jobId, expectedConnections, currentConnections, elapsedSeconds, note}, playing }. The success signal for a join is connectionCount going 1 → N+1 (host + guests; guests appear with the Steam guest account name). 'timeout' is not fatal — clients boot in ~80 s, so a late join can still land: keep polling. Also your host-side assertion surface: pair it with inspect_networked_object / get_runtime_property to verify replication while the session runs.", {}, async () => reply(await bridge.send("multiplayer_test_status", {})));
+    // ── stop_multiplayer_test ─────────────────────────────────────────
+    server.tool("stop_multiplayer_test", "Kill every sbox.exe test client spawned by start_multiplayer_test (entire process tree) and clear the harness registry. Returns { stopped, clients:[{pid,killed,note?}], disconnected, strays, note } — a PID that's already dead (crashed / closed by hand) is reported per-PID, not an error. Pass disconnect:true to also Networking.Disconnect() the host session on the running game (default false: the session keeps running for another round). Pass alsoStrays:true as a safety net to kill ANY process named 'sbox' that isn't the editor (never touches sbox-dev / the editor's own PID). Killing a connected client leaves benign TcpChannel.SendThread traces in the editor log — not an error. Safe to call with nothing running.", {
+        disconnect: z
+            .boolean()
+            .optional()
+            .describe("Also Networking.Disconnect() the host session on the running game (default false — leaves the session up)"),
+        alsoStrays: z
+            .boolean()
+            .optional()
+            .describe("Safety net: also kill ANY process named 'sbox' that isn't the editor or a tracked client (default false). Never touches sbox-dev or the editor's own PID"),
+    }, async (params) => reply(await bridge.send("stop_multiplayer_test", params)));
+}
+//# sourceMappingURL=multiplayertest.js.map

package/dist/tools/networking.js

@@ -8,23 +8,23 @@ import { z } from "zod";
  */
 export function registerNetworkingTools(server, bridge) {
     // ── add_network_helper ────────────────────────────────────────────
-    server.tool("add_network_helper", "Add a NetworkHelper component to the scene for quick multiplayer setup. Handles lobby creation and player prefab spawning", {
+    server.tool("add_network_helper", "Add a NetworkHelper component (with StartServer=true) to an existing GameObject for quick multiplayer setup — at runtime it creates the lobby and spawns the player prefab per connection. Returns { added, id, component:'NetworkHelper' }. NOTE: the current handler requires id (create a holder with create_gameobject first) and does not apply maxPlayers/playerPrefab — wire PlayerPrefab afterward with set_prefab_ref/set_property", {
         id: z
             .string()
             .optional()
-            .describe("GUID of existing GameObject. Creates new if omitted"),
+            .describe("GUID of the GameObject to attach to. Required in practice — the current handler errors when omitted (create a holder with create_gameobject first)"),
         name: z
             .string()
             .optional()
-            .describe("Name for the network manager object. Defaults to 'Network Manager'"),
+            .describe("Rename the target GameObject to this. Omit to keep its current name"),
         maxPlayers: z
             .number()
             .optional()
-            .describe("Maximum number of players in the lobby"),
+            .describe("Maximum number of players in the lobby (currently not applied by the handler)"),
         playerPrefab: z
             .string()
             .optional()
-            .describe("Path to the player prefab to spawn for each connection"),
+            .describe("Path to the player prefab to spawn for each connection (currently not applied by the handler — set the NetworkHelper's PlayerPrefab afterward with set_prefab_ref)"),
     }, async (params) => {
         const res = await bridge.send("add_network_helper", params);
         if (!res.success) {
@@ -35,23 +35,23 @@ export function registerNetworkingTools(server, bridge) {
         };
     });
     // ── configure_network ─────────────────────────────────────────────
-    server.tool("configure_network", "Configure networking settings on the existing NetworkHelper: max players, lobby name, player prefab, start server", {
+    server.tool("configure_network", "Configure lobby settings on Sandbox.Networking. Currently only lobbyName is applied (sets Networking.ServerName) — Networking.MaxPlayers is read-only on this SDK, and playerPrefab/startServer are not applied by the handler (use add_network_helper + set_prefab_ref for those). Returns { configured, maxPlayers, serverName } reflecting the live Networking values", {
         maxPlayers: z
             .number()
             .optional()
-            .describe("Maximum number of players"),
+            .describe("Maximum number of players (currently not applied — Networking.MaxPlayers is read-only on this SDK; the live value is echoed in the response)"),
         lobbyName: z
             .string()
             .optional()
-            .describe("Display name for the lobby"),
+            .describe("Display name for the lobby (sets Networking.ServerName — the only setting this handler applies)"),
         playerPrefab: z
             .string()
             .optional()
-            .describe("Path to the player prefab"),
+            .describe("Path to the player prefab (currently not applied by the handler — set the NetworkHelper's PlayerPrefab via set_prefab_ref instead)"),
         startServer: z
             .boolean()
             .optional()
-            .describe("Start the server/lobby immediately"),
+            .describe("Start the server/lobby immediately (currently not applied by the handler — add_network_helper sets StartServer=true on the NetworkHelper)"),
     }, async (params) => {
         const res = await bridge.send("configure_network", params);
         if (!res.success) {
@@ -62,7 +62,7 @@ export function registerNetworkingTools(server, bridge) {
         };
     });
     // ── get_network_status ────────────────────────────────────────────
-    server.tool("get_network_status", "Check the current multiplayer status: connection state, player count, lobby info, networked objects", {}, async (params) => {
+    server.tool("get_network_status", "Check the current multiplayer status. Returns { isActive, isHost, isClient, isConnecting, maxPlayers, serverName } read from Sandbox.Networking — meaningful mostly in play mode with networking active. It does NOT return a player list or networked-object dump; use inspect_networked_object for a specific object's Network/[Sync] state", {}, async (params) => {
         const res = await bridge.send("get_network_status", params);
         if (!res.success) {
             return { content: [{ type: "text", text: `Error: ${res.error}` }] };
@@ -72,7 +72,7 @@ export function registerNetworkingTools(server, bridge) {
         };
     });
     // ── network_spawn ─────────────────────────────────────────────────
-    server.tool("network_spawn", "Network-enable a GameObject so it is synchronized across all connected clients. Calls NetworkSpawn()", {
+    server.tool("network_spawn", "Network-enable a GameObject so it is synchronized across all connected clients. Calls NetworkSpawn(). Returns { spawned, id } on success — follow with inspect_networked_object to confirm the Network state, or set_ownership to hand it to a connection", {
         id: z.string().describe("GUID of the GameObject to network"),
     }, async (params) => {
         const res = await bridge.send("network_spawn", params);
@@ -84,12 +84,12 @@ export function registerNetworkingTools(server, bridge) {
         };
     });
     // ── set_ownership ─────────────────────────────────────────────────
-    server.tool("set_ownership", "Transfer network ownership of a GameObject to a different connection, or take/drop ownership", {
+    server.tool("set_ownership", "Assign network ownership of a GameObject to a connection, or drop ownership. Omitting connectionId (or passing an empty string) calls Network.DropOwnership(); passing a connection Id or SteamId calls Network.AssignOwnership() on the matching live Connection. Returns { ownershipAssigned, id, connectionId } or { ownershipDropped, id }; errors if no connection matches (connections only exist while networking is active)", {
         id: z.string().describe("GUID of the networked GameObject"),
         connectionId: z
             .string()
             .optional()
-            .describe("GUID of the target connection. Empty string = drop ownership. Omit = take ownership"),
+            .describe("Connection Id GUID or SteamId of the target connection. Omit OR pass an empty string to DROP ownership (there is no take-ownership mode in the current handler)"),
     }, async (params) => {
         const res = await bridge.send("set_ownership", params);
         if (!res.success) {
@@ -100,7 +100,7 @@ export function registerNetworkingTools(server, bridge) {
         };
     });
     // ── add_sync_property ─────────────────────────────────────────────
-    server.tool("add_sync_property", "Annotate an EXISTING public property in a C# script with the [Sync] attribute so s&box replicates it across the network. This does NOT create a new property — the property named by `propertyName` must already be declared in the file; the tool only inserts the [Sync] attribute above it", {
+    server.tool("add_sync_property", "Annotate an EXISTING public property in a C# script with the [Sync] attribute so s&box replicates it across the network. This does NOT create a new property — the property named by `propertyName` must already be declared in the file; the tool only inserts the [Sync] attribute above it. Returns { added, path, property, attribute } — attribute echoes the exact [Sync...] emitted; errors if the property already has [Sync] or isn't found. Follow with trigger_hotload, then get_compile_errors", {
         path: z
             .string()
             .describe("Relative path to the script file (e.g. 'code/Player.cs')"),
@@ -156,7 +156,7 @@ export function registerNetworkingTools(server, bridge) {
         };
     });
     // ── create_networked_player ───────────────────────────────────────
-    server.tool("create_networked_player", "Generate a network-aware player controller with [Sync] properties, owner-only input, and [Rpc.Broadcast] actions", {
+    server.tool("create_networked_player", "Generate a network-aware player controller with [Sync] properties, owner-only input, and [Rpc.Broadcast] actions. Writes <name>.cs and returns { created, path, className }. The generated Component syncs PlayerName/Health, moves a CharacterController from Input.AnalogMove behind an IsProxy guard, and exposes a [Property] MoveSpeed plus an [Rpc.Broadcast] TakeDamage(int). Follow with trigger_hotload, then get_compile_errors, then attach + network_spawn", {
         name: z
             .string()
             .optional()
@@ -165,11 +165,11 @@ export function registerNetworkingTools(server, bridge) {
             .string()
             .optional()
             .describe("Subdirectory under code/"),
-        moveSpeed: z.number().optional().describe("Movement speed. Defaults to 300"),
+        moveSpeed: z.number().optional().describe("Movement speed (generated MoveSpeed [Property]). Defaults to 200"),
         includeHealth: z
             .boolean()
             .optional()
-            .describe("Include health/damage system with host-authoritative TakeDamage. Defaults to true"),
+            .describe("Currently not applied by the handler — the [Sync] Health and [Rpc.Broadcast] TakeDamage are always generated"),
     }, async (params) => {
         const res = await bridge.send("create_networked_player", params);
         if (!res.success) {
@@ -180,7 +180,7 @@ export function registerNetworkingTools(server, bridge) {
         };
     });
     // ── create_lobby_manager ──────────────────────────────────────────
-    server.tool("create_lobby_manager", "Generate a lobby manager script with create/join/leave lobby, player spawning, and connection cleanup", {
+    server.tool("create_lobby_manager", "Generate a lobby manager Component implementing Component.INetworkListener: a static Instance singleton, a [Sync] PlayerCount maintained in OnActive/OnDisconnected, and a LobbyState [Property] that flips to 'playing' when the lobby fills. Writes <name>.cs and returns { created, path, className }. Follow with trigger_hotload, then get_compile_errors, then place via add_component_to_new_object", {
         name: z
             .string()
             .optional()
@@ -192,7 +192,7 @@ export function registerNetworkingTools(server, bridge) {
         maxPlayers: z
             .number()
             .optional()
-            .describe("Default max players. Defaults to 8"),
+            .describe("Currently not applied by the handler — the generated MaxPlayers [Property] defaults to 16; tune it per-instance with set_property"),
     }, async (params) => {
         const res = await bridge.send("create_lobby_manager", params);
         if (!res.success) {
@@ -203,7 +203,7 @@ export function registerNetworkingTools(server, bridge) {
         };
     });
     // ── create_network_events ─────────────────────────────────────────
-    server.tool("create_network_events", "Generate a network event handler script implementing INetworkListener for connect/disconnect/chat events", {
+    server.tool("create_network_events", "Generate a network event relay Component: [Rpc.Broadcast] SendEvent(eventName, payload) to all clients and [Rpc.Host] SendEventToHost(...), both dispatching into a local OnNetworkEvent switch you extend. It does NOT implement INetworkListener — use create_lobby_manager for connect/disconnect hooks. Writes <name>.cs and returns { created, path, className }. Follow with trigger_hotload, then get_compile_errors", {
         name: z
             .string()
             .optional()
@@ -215,7 +215,7 @@ export function registerNetworkingTools(server, bridge) {
         includeChat: z
             .boolean()
             .optional()
-            .describe("Include a chat message broadcast system. Defaults to false"),
+            .describe("Currently not applied by the handler — no chat system is generated"),
     }, async (params) => {
         const res = await bridge.send("create_network_events", params);
         if (!res.success) {