sbox-mcp-server 1.20.0 → 2.1.0

package/dist/tools/physics.js

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

package/dist/tools/playmode.js

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

package/dist/tools/playtest.js

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

package/dist/tools/prefabs.js

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

package/dist/tools/project.js

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

package/dist/tools/publishing.js

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

package/dist/tools/roundui.d.ts

@@ -0,0 +1,22 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Round-flow & UI pack — three tools:
+ *
+ *   - create_round_timer_hud   Razor screen HUD showing round/phase time remaining;
+ *                              binds at runtime (TypeLibrary reflection) to whichever
+ *                              shipped round machine exists — no code coupling
+ *   - scaffold_map_vote_flow   end-of-round map vote: [Rpc.Host] ballots, [Sync]
+ *                              NetList tallies, countdown, deterministic tie-break,
+ *                              winner -> Scene.LoadFromFile, plus a Razor vote panel
+ *   - add_panel_buildhash      FILE-EDIT tool (not a scaffold): patches an existing
+ *                              .razor to add the BuildHash() override razor_lint
+ *                              flags as missing
+ *
+ * All are file-mutating (refused during play mode by the bridge dispatch). The
+ * Razor output is razor_lint-safe by construction (BuildHash override, no
+ * switch-expressions or non-ASCII in @code, class-selector SCSS roots), modeled
+ * on create_leaderboard_panel / the UI-feedback pack.
+ */
+export declare function registerRoundUiTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=roundui.d.ts.map

package/dist/tools/roundui.js

@@ -0,0 +1,88 @@
+import { z } from "zod";
+/**
+ * Round-flow & UI pack — three tools:
+ *
+ *   - create_round_timer_hud   Razor screen HUD showing round/phase time remaining;
+ *                              binds at runtime (TypeLibrary reflection) to whichever
+ *                              shipped round machine exists — no code coupling
+ *   - scaffold_map_vote_flow   end-of-round map vote: [Rpc.Host] ballots, [Sync]
+ *                              NetList tallies, countdown, deterministic tie-break,
+ *                              winner -> Scene.LoadFromFile, plus a Razor vote panel
+ *   - add_panel_buildhash      FILE-EDIT tool (not a scaffold): patches an existing
+ *                              .razor to add the BuildHash() override razor_lint
+ *                              flags as missing
+ *
+ * All are file-mutating (refused during play mode by the bridge dispatch). The
+ * Razor output is razor_lint-safe by construction (BuildHash override, no
+ * switch-expressions or non-ASCII in @code, class-selector SCSS roots), modeled
+ * on create_leaderboard_panel / the UI-feedback pack.
+ */
+export function registerRoundUiTools(server, bridge) {
+    // ── create_round_timer_hud ────────────────────────────────────────
+    server.tool("create_round_timer_hud", "Generate a Razor screen-panel HUD (.razor + .razor.scss) showing the active round/phase time remaining as mm:ss with the phase/state name above it. NO code coupling to your round machine: at runtime it discovers one by TypeLibrary property reflection — same-GameObject components first, then the whole scene, re-scanning every 2s while unbound — matching either shipped machine shape: create_round_phase_machine output (a [Sync] TimeUntil 'PhaseTimer' + 'CurrentPhase' enum for the label) or create_round_state_machine output (a manager with 'StateIndex' + 'Current', whose active state carries a [Sync] TimeUntil 'TimeLeft' + 'Identifier'). First matching component wins; any hand-written machine exposing those member names also binds. Adaptive BuildHash folds the WHOLE second remaining so the panel re-renders at 1 Hz, not every frame. Optional low-time warning: at/below lowTimeSeconds the clock gets the 'low' CSS class (red by default). Shows '--:--' (and fades out via the 'unbound' class) until a machine exists. Returns { created, razorPath, scssPath, className, lowTimeSeconds, note, nextSteps }. Renders NOTHING without a ScreenPanel host: follow with trigger_hotload, then add_screen_panel, then add_component_with_properties (component=className) on the same object; verify with capture_view (renderUI=true) in play mode.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated panel. Defaults to 'RoundTimerHud'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .razor + .razor.scss. Defaults to 'Code/UI'"),
+        lowTimeSeconds: z
+            .number()
+            .optional()
+            .describe("Remaining-seconds threshold at/below which the clock gets the 'low' warning class (clamped to >= 0; 0 disables). Editable per-instance via the LowTimeSeconds [Property]. Defaults to 10"),
+    }, async (params) => {
+        const res = await bridge.send("create_round_timer_hud", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── scaffold_map_vote_flow ────────────────────────────────────────
+    server.tool("scaffold_map_vote_flow", "Scaffold an end-of-round map vote. Three files: <Name>.cs (sealed host-authoritative controller) + <Name>Panel.razor + <Name>Panel.razor.scss (vote UI: one button per map, live tallies, countdown, own-pick highlight, winner banner). Flow: host calls StartVote() (usually from a post-round phase/state, or set the AutoStart [Property]) -> clients click -> votes route client-to-host via [Rpc.Host] SubmitVote with the caller re-resolved HOST-SIDE from Rpc.Caller (null-checked — Connection has no IsValid on this SDK) and the map index re-validated (re-votes overwrite, keyed by SteamId) -> tallies replicate via [Sync(FromHost)] NetList<int> -> when the [Sync] TimeUntil countdown expires the host picks the winner (most votes; ties break deterministically via one LCG scramble of a time seed — no System.Random) -> after resultLingerSeconds the HOST calls Scene.LoadFromFile(winner) (API verified live on this SDK; clients follow via the scene networking layer — verify the client hand-off in a real multi-client session). Static event OnVoteFinished(sceneFile) fires on every machine. Returns { created, componentPath, razorPath, scssPath, className, panelClassName, maps, voteDurationSeconds, resultLingerSeconds, autoStart, note, nextSteps }. REQUIREMENTS: the controller must sit on a NETWORK-SPAWNED object in multiplayer or [Sync] never replicates; if maps is omitted the MapScenes list is generated EMPTY and StartVote() refuses with a warning until you fill it in the inspector. Follow with trigger_hotload, attach via add_component_with_properties, host the panel under add_screen_panel.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the controller; the panel is generated as <Name>Panel. Defaults to 'MapVote'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs + .razor + .razor.scss. Defaults to 'Code'"),
+        maps: z
+            .array(z.string())
+            .optional()
+            .describe("Scene files to vote between, e.g. [\"scenes/arena.scene\", \"scenes/docks.scene\"] (find them with list_scenes). Baked into the MapScenes [Property] list, editable later in the inspector. Defaults to an EMPTY list (StartVote() then refuses until it's filled)"),
+        voteDurationSeconds: z
+            .number()
+            .optional()
+            .describe("Seconds the vote stays open once StartVote() is called (clamped to >= 3). Defaults to 20"),
+        resultLingerSeconds: z
+            .number()
+            .optional()
+            .describe("Seconds the winner banner shows before the host loads the winning scene (clamped to >= 0). Defaults to 4"),
+        autoStart: z
+            .boolean()
+            .optional()
+            .describe("Start the vote automatically on spawn (host only). Usually false — call StartVote() from your round machine's post-round state instead. Defaults to false"),
+    }, async (params) => {
+        const res = await bridge.send("scaffold_map_vote_flow", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── add_panel_buildhash ───────────────────────────────────────────
+    server.tool("add_panel_buildhash", "PATCH an existing .razor file (razor_lint's companion FIXER — razor_lint flags 'PanelComponent without BuildHash', this adds it). NOT a scaffold: it EDITS the file in place, inserting 'protected override int BuildHash() => System.HashCode.Combine( ... )' at the end of the first @code block, folding the fields and auto-properties declared there. HEURISTIC string/regex parsing — review the diff: computed (=>) properties, statics, consts, events and Action/Func members are skipped; reference-typed members fold by REFERENCE (a mutated List re-renders only if Count-style state is also folded); TimeSince/TimeUntil/RealTimeSince/RealTimeUntil members fold as whole seconds (1 Hz re-render, not every frame); braces inside @code string literals can confuse the block parser. If no members are found a '=> 0' stub with a TODO is inserted (silences the lint but does NOT re-render — replace it). Returns { patched, path, hashedMembers[], buildHash, note } on success, { alreadyPresent: true, path } when a BuildHash already exists (file left UNCHANGED — extend it by hand), or { error } for non-PanelComponent files, missing @code, or a path outside the project. Follow with trigger_hotload, then razor_lint to confirm the finding cleared.", {
+        path: z
+            .string()
+            .describe("Project-relative path to the .razor file to patch, e.g. 'Code/UI/MyHud.razor' (from razor_lint's finding.file or list_project_files). Must '@inherits PanelComponent'; .razor.scss files are rejected"),
+    }, async (params) => {
+        const res = await bridge.send("add_panel_buildhash", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+}
+//# sourceMappingURL=roundui.js.map

package/dist/tools/scenes.js

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

package/dist/tools/scripts.js

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

package/dist/tools/statsachievements.d.ts

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

package/dist/tools/statsachievements.js

@@ -0,0 +1,243 @@
+import { z } from "zod";
+/**
+ * Stats & Achievements pack — five scaffolds:
+ *
+ *   - add_leaderboard_stat        batched write-side stat reporter (Stats.Increment)
+ *   - create_achievement_set      achievement engine + unlock toast HUD (razor)
+ *   - add_achievement_trigger     trigger zone firing Progress/Unlock (creates a GO)
+ *   - create_speedrun_leaderboard timer + min-aggregation submit + friends-filter panel
+ *   - create_elo_rating_system    host-authoritative elo math + persisted ratings
+ *
+ * The write-side partners of create_leaderboard_panel (the read side). All are
+ * file/scene-mutating and refused during play mode by the bridge dispatch.
+ * Sandbox.Services APIs used by the generated code were verified live via
+ * describe_type (Stats.Increment/SetValue/Flush, Leaderboards.GetFromStat ->
+ * Board2.SetFriendsOnly/SetAggregationMin/SetSortAscending/Refresh(token)).
+ */
+// A 3D vector accepted as EITHER an object {x,y,z} OR a comma string "x,y,z".
+// The value is passed through to the bridge unchanged; the C# handler parses
+// both forms (C# is the source of truth for parsing).
+const Vector3Object = z.object({
+    x: z.number().describe("X coordinate"),
+    y: z.number().describe("Y coordinate"),
+    z: z.number().describe("Z coordinate"),
+});
+const Vector3Schema = z
+    .union([
+    Vector3Object,
+    z.string().describe('Comma string "x,y,z", e.g. "0,0,200"'),
+])
+    .describe('3D vector — object {x,y,z} OR comma string "x,y,z"');
+export function registerStatsAchievementsTools(server, bridge) {
+    // ── add_leaderboard_stat ──────────────────────────────────────────
+    server.tool("add_leaderboard_stat", "Generate a batched write-side stat reporter component for Sandbox.Services.Stats — the write partner of create_leaderboard_panel. Gameplay code calls the static <Name>.Report(\"kills\", 1) from anywhere; amounts accumulate locally and flush as Stats.Increment deltas on a timer (default every 12 s, also on disable/destroy). Baseline-delta bookkeeping means a partial flush retries the un-sent remainder instead of double-counting, and deltas larger than maxChunk are sent in chunks. Returns { created, path, className, placedOn, note, nextSteps }. Place ONE in the scene after trigger_hotload (add_component_to_new_object), or pass targetId to attach immediately when the type is already compiled. Stats are PER LOCAL PLAYER (each client reports its own) and only exist on leaderboards once the stat is registered for the project ident on sbox.game. Fails if the file already exists.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated component. Defaults to 'StatReporter'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        flushIntervalSeconds: z
+            .number()
+            .optional()
+            .describe("Seconds between batched flushes to the backend. Defaults to 12, clamped to >= 1"),
+        maxChunk: z
+            .number()
+            .optional()
+            .describe("Largest amount sent in a single Stats.Increment call; bigger deltas are chunked. Defaults to 1000, clamped to >= 1"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of a GameObject to attach to (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("add_leaderboard_stat", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── create_achievement_set ────────────────────────────────────────
+    server.tool("create_achievement_set", "Generate an achievement engine: a component with an AchievementDef list (id/title/description/target), per-achievement progress persisted via FileSystem.Data JSON (survives restarts), Progress(id, amount) / Unlock(id) API on a static Instance, a static OnAchievementUnlocked event, and an optional Stats.Increment mirror ('ach-<id>' += 1) on unlock. Also emits a Razor unlock-toast HUD (<Name>Toast.razor + .razor.scss, razor_lint clean) unless makeToast=false. Returns { created, path, className, toastRazorPath, toastScssPath, toastClassName, achievements, placedOn, note, nextSteps }. Ids are sanitized to [a-z0-9_-]; omitting achievements bakes 3 editable samples. After trigger_hotload: place ONE set in the scene, and host the toast under a ScreenPanel (add_screen_panel). Pair with add_achievement_trigger for world-trigger unlocks. LOCAL-only: achievements belong to each client's local player. Fails if the .cs or toast .razor already exists.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated engine component (toast panel becomes <name>Toast). Defaults to 'AchievementSet'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for all generated files. Defaults to 'Code'"),
+        achievements: z
+            .array(z.object({
+            id: z.string().describe("Stable id, sanitized to [a-z0-9_-] (used in the save file and the mirrored stat name)"),
+            title: z.string().describe("Display title shown in the toast"),
+            description: z.string().optional().describe("Short description shown in the toast"),
+            target: z.number().optional().describe("Progress value that unlocks it. Defaults to 1, clamped to >= 1"),
+        }))
+            .optional()
+            .describe("Achievement definitions baked into the component. Omit for 3 editable samples (first_steps, collector, veteran)"),
+        fileName: z
+            .string()
+            .optional()
+            .describe("Save file name inside FileSystem.Data. Defaults to 'achievements.json'"),
+        mirrorToStats: z
+            .boolean()
+            .optional()
+            .describe("Mirror each unlock into Sandbox.Services.Stats as 'ach-<id>' += 1. Defaults to true"),
+        makeToast: z
+            .boolean()
+            .optional()
+            .describe("Also emit the <name>Toast.razor + .razor.scss unlock toast HUD. Defaults to true"),
+        toastSeconds: z
+            .number()
+            .optional()
+            .describe("Seconds each unlock toast stays on screen. Defaults to 4, clamped to >= 0.5"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of a GameObject to attach the engine to (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_achievement_set", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── add_achievement_trigger ───────────────────────────────────────
+    server.tool("add_achievement_trigger", "SCENE-MUTATING: generate a data-driven achievement trigger-zone component AND create its GameObject now (named zone with a sized BoxCollider, IsTrigger=true, at the given position). When an object tagged triggerTag enters, the component calls <achievementSetClass>.Instance.Progress(achievementId, amount) — or Unlock() when unlock=true — with a once-only latch and optional destroy-after-fire. Returns { created, path, className, achievementSetClass, achievementId, gameObject, attached, note, nextSteps }. The generated component only attaches to the zone after trigger_hotload — until then `attached` is false and nextSteps carries the exact add_component_with_properties follow-up. The generated code references the set class BY NAME: run create_achievement_set first or the project will not compile (the result warns via `note`). Re-running with the same name fails unless reuseClass=true, which skips codegen and just places another zone (attaching + configuring immediately since the class is already compiled). Refused during play mode.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated trigger component. Defaults to 'AchievementTrigger'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        achievementSetClass: z
+            .string()
+            .optional()
+            .describe("Class name of the achievement set the zone reports to (from create_achievement_set). Defaults to 'AchievementSet'"),
+        achievementId: z
+            .string()
+            .describe("Id of the achievement to progress/unlock (sanitized to [a-z0-9_-])"),
+        amount: z
+            .number()
+            .optional()
+            .describe("Progress amount added per fire (ignored when unlock=true). Defaults to 1"),
+        unlock: z
+            .boolean()
+            .optional()
+            .describe("Call Unlock() instead of Progress(). Defaults to false"),
+        triggerTag: z
+            .string()
+            .optional()
+            .describe("Tag the entering object must carry (put it on the player via set_tags). Defaults to 'player'"),
+        onceOnly: z
+            .boolean()
+            .optional()
+            .describe("Only the first tagged entry fires. Defaults to true"),
+        destroyAfterFire: z
+            .boolean()
+            .optional()
+            .describe("Destroy the zone GameObject after firing. Defaults to false"),
+        createObject: z
+            .boolean()
+            .optional()
+            .describe("Create the zone GameObject now (with BoxCollider). Defaults to true; false = code-gen only"),
+        objectName: z
+            .string()
+            .optional()
+            .describe("Name for the zone GameObject. Defaults to '<name>Zone'"),
+        position: Vector3Schema.optional().describe("World position of the zone GameObject"),
+        scale: z
+            .union([z.number(), Vector3Schema])
+            .optional()
+            .describe('BoxCollider size — uniform number, object {x,y,z}, or comma string "x,y,z". Defaults to 100,100,100'),
+        reuseClass: z
+            .boolean()
+            .optional()
+            .describe("If the .cs already exists, skip codegen and just place another zone with the existing class. Defaults to false"),
+    }, async (params) => {
+        const res = await bridge.send("add_achievement_trigger", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── create_speedrun_leaderboard ───────────────────────────────────
+    server.tool("create_speedrun_leaderboard", "Generate a speedrun timer component plus a leaderboard display panel. The timer (<Name>.cs) is TimeSince-based with a static Instance: StartTimer() at run start, StopTimer() at the finish (pairs with a trigger zone), ResetTimer() to abort. StopTimer persists the local best via FileSystem.Data and submits Stats.SetValue(statName, seconds) ONLY when the run beats it — configure the stat with MIN aggregation on sbox.game so the global board keeps best times. The panel (<Name>Panel.razor + .razor.scss, razor_lint clean) fetches via Leaderboards.GetFromStat with min aggregation + ascending sort, has a clickable Friends-only filter button, and overlays a local-best row read from the same save file. Returns { created, path, className, panelRazorPath, panelScssPath, panelClassName, statName, placedOn, note, nextSteps }. After trigger_hotload: place ONE timer (add_component_to_new_object or targetId) and host the panel under a ScreenPanel/WorldPanel (add_screen_panel). maxRows clamps to 1..50; makePanel=false skips the panel files. Fails if the .cs or panel .razor already exists.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated timer component (panel becomes <name>Panel). Defaults to 'SpeedrunTimer'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for all generated files. Defaults to 'Code'"),
+        statName: z
+            .string()
+            .optional()
+            .describe("Sandbox.Services stat the best time is written to (sanitized to [a-z0-9_-]). Defaults to 'best_time'"),
+        fileName: z
+            .string()
+            .optional()
+            .describe("Save file name inside FileSystem.Data for the local best. Defaults to 'speedrun.json'"),
+        title: z
+            .string()
+            .optional()
+            .describe("Panel title text. Defaults to 'Best Times'"),
+        maxRows: z
+            .number()
+            .optional()
+            .describe("Leaderboard rows fetched/shown. Defaults to 10, clamped to 1..50"),
+        makePanel: z
+            .boolean()
+            .optional()
+            .describe("Also emit the <name>Panel.razor + .razor.scss display panel. Defaults to true"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of a GameObject to attach the timer to (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_speedrun_leaderboard", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── create_elo_rating_system ──────────────────────────────────────
+    server.tool("create_elo_rating_system", "Generate a self-contained, host-authoritative elo rating component: standard elo math (expected = 1/(1+10^((Rb-Ra)/400)), delta = K * (score - expected)) with a [Property] K-factor, ratings in a [Sync(SyncFlags.FromHost)] NetDictionary<long,float> keyed by SteamId, and host-side persistence via FileSystem.Data JSON. API on a static Instance: ReportMatch(winnerSteamId, loserSteamId) for 1v1 and ReportTeamMatch(winnerIds, loserIds) for teams (team-average elo, uniform delta per member) — both are IsProxy-guarded no-ops on clients; GetRating(steamId) works anywhere (unknown players = defaultRating); the static OnRatingChanged(steamId, newRating) fires on EVERY machine via an [Rpc.Broadcast]. Returns { created, path, className, kFactor, defaultRating, placedOn, note, nextSteps }. After trigger_hotload: place ONE in the scene and network its GameObject (network_spawn) or the [Sync] never replicates. Only the HOST's disk holds the ratings ledger. Fails if the file already exists.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated component. Defaults to 'EloRatingSystem'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        kFactor: z
+            .number()
+            .optional()
+            .describe("Elo K-factor — how far one result moves ratings (32 = fast, 16 = stable). Defaults to 32, clamped to >= 1"),
+        defaultRating: z
+            .number()
+            .optional()
+            .describe("Rating assigned to players with no recorded matches. Defaults to 1000"),
+        fileName: z
+            .string()
+            .optional()
+            .describe("Save file name inside FileSystem.Data (host-side ledger). Defaults to 'elo_ratings.json'"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of a GameObject to attach to (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_elo_rating_system", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+}
+//# sourceMappingURL=statsachievements.js.map

package/dist/tools/status.js

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