sbox-mcp-server 1.17.1 → 1.19.0

package/README.md

@@ -1,6 +1,6 @@
 # sbox-mcp-server
 
-MCP Server for the s&box game engine. Lets Claude Code build s&box games through conversation — **170+ tools** for scenes, scripts, GameObjects, components, assets, materials, audio, physics, UI, networking, publishing, world-gen, lighting & atmosphere, characters, scene layout, navmesh & spatial queries, particles, animation, NPC brains, playable-game scaffolds, networking & scene inspection/lint, save & services queries, self-diagnosis, console/C# execution, live docs search, and type discovery.
+MCP Server for the s&box game engine. Lets Claude Code build s&box games through conversation — **200+ tools** for scenes, scripts, GameObjects, components, assets, materials, audio, physics, UI, networking, publishing, world-gen, lighting & atmosphere, characters, lipsync, scene layout, navmesh & spatial queries, particles, animation, NPC brains, playable-game scaffolds, gameplay playtesting, networking & scene inspection/lint, save & services queries, self-diagnosis, console/C# execution, live docs search, and type discovery.
 
 ## Fastest install — the Claude Code plugin
 
@@ -54,9 +54,9 @@ Claude Code → (stdio) → sbox-mcp-server → (file IPC) → bridge addon →
 
 Communication uses file-based IPC through `%TEMP%/sbox-bridge-ipc/`. The MCP server writes request JSON files, the bridge addon (running inside s&box) polls and processes on the main editor thread, then writes response files back. WebSocket is not used — s&box's sandboxed C# environment blocks `System.Net`.
 
-## Tools (v1.9.0)
+## Tools
 
-`get_bridge_status` reports the `handlerCount` — that's the C# handlers compiled inside the editor. Six tools run **MCP-server-side** and need no editor handler: `read_log`, `get_compile_errors`, `execute_csharp`, `search_docs`, `get_doc_page`, `list_doc_categories`. They read the log / hotload-eval / fetch docs directly, so they keep working even when the editor has crashed or stalled.
+`get_bridge_status` reports the `handlerCount` — that's the C# handlers compiled inside the editor. A handful of tools run **MCP-server-side** and need no editor handler (`read_log`, `get_compile_errors`, `execute_csharp`, `search_docs`, `get_doc_page`, `list_doc_categories`, `run_self_test`, `screenshot_orbit`). They read the log / hotload-eval / fetch docs / orchestrate other tools directly, so most keep working even when the editor has crashed or stalled.
 
 | Category | Tools |
 |----------|-------|
@@ -100,6 +100,16 @@ Communication uses file-based IPC through `%TEMP%/sbox-bridge-ipc/`. The MCP ser
 | **Object utilities** *(v1.5.0)* | remove_component, get_tags |
 | **Docs search** *(v1.5.0, MCP-server-side)* | search_docs, get_doc_page, list_doc_categories — official `Facepunch/sbox-docs` |
 | **Inspection & validation** *(v1.9.0)* | inspect_networked_object (per-object `Network.*` + every component's `[Sync]` fields/values), networking_lint (static scan for `[Sync]`/RPC footguns), scene_validate (no-camera / stray root Rigidbody / trigger-vs-trace), save_inspect (list/read/diff `FileSystem.Data` saves), services_query (`Sandbox.Services` stats + leaderboards), simulate_input (drive named input actions in play mode) |
+| **Editor & self-test** *(v1.5.1–v1.7)* | restart_editor (self-restart + reconnect — closes the C#-edit loop), list_libraries, recompile_asset, run_self_test (8-check end-to-end health gate), capture_view (**renders the RUNNING play scene** from any camera — the play-mode eyes) |
+| **Animation & verification** *(v1.6.0)* | list_animations, play_animation, set_animgraph_param, get_bounds, screenshot_orbit (multi-angle orbit shots of any object) |
+| **Call & input** *(v1.10.0)* | invoke_method (call a component method **with args**), ensure_input_action (add a `.sbproj` input action), drive_player / drive_player_status (play-mode input driver) |
+| **Gameplay scaffolds** *(v1.7–v1.13)* | set_component_reference, add_component_to_new_object, create_objective_system, create_health_system, create_pickup, create_trigger_zone, create_economy_wallet, create_round_phase_machine, create_day_night_clock, create_interactable, create_weighted_loot_table, create_save_system, create_leaderboard_panel, create_inventory, create_stat_modifier_system, create_placement_mode |
+| **NPC brains** *(v1.7.0)* | create_npc_brain (FSM: Idle/Patrol/Wander/Chase/Search/Flee/Ambush + FOV/LOS/hearing), place_patrol_route, assign_patrol_route, create_npc_spawner, simulate_npc_perception |
+| **Lints & asset utils** *(v1.12.0)* | sandbox_lint (whitelist pre-compile scan), razor_lint (Razor/SCSS transpiler footguns), copy_asset_with_dependencies (asset + full dependency closure) |
+| **Meta & debug-draw** *(v1.14–v1.15)* | set_time_scale (pause/slow-mo/fast-forward), get_profiler_stats (FPS/frame/GPU/allocations), debug_draw_line/ray/box/sphere, debug_clear |
+| **Playtest harness** *(v1.17)* | playtest (scripted gameplay loop in PLAY MODE with **in-frame assertions** — move/look/action/jump/set/wait/capture/assert), playtest_status |
+| **Lipsync** *(v1.18.0)* | add_lipsync — wires `Sandbox.LipSync` (new in the 2026-07-01 engine update) to a citizen/model: `SkinnedModelRenderer` + a `SoundPointComponent` bound to a `.sound` path, facial morphs animating while the sound plays |
+| **Gameplay scaffolds** *(v1.18.0)* | create_round_state_machine (multi-state round manager + abstract `RoundState` lifecycle base, host-authoritative with late-joiner reconcile), add_interaction_station (one-occupant `IPressable` station, host-routed claims, reservation grace window, level gate), create_event_director (weighted-interval pacing/AI director, dedupe, `MaxActive` cap, timed self-destruct), create_save_slots (multi-slot save manager, versioned, optional GUID scene reconciliation — companion to create_save_system) |
 
 ## Working with Claude effectively
 
@@ -127,6 +137,6 @@ The companion plugin's `sbox-build-feature` skill encodes this workflow plus the
 
 ## License
 
-**AGPL-3.0-or-later** — see [LICENSE](../LICENSE) and [NOTICE](../NOTICE) for details. The code is open under AGPL; the "s&box Claude Bridge" / "sboxskins.gg" name and branding may not be reused to pass a fork off as the original.
+**Source-available (no redistribution)** — see [LICENSE](../LICENSE) and [NOTICE](../NOTICE) for details. You may use and locally modify the bridge to build your own games, but you may not redistribute, fork, repackage, or re-host it. The "s&box Claude Bridge" / "sboxskins.gg" name and branding are trademarks and may not be reused.
 
 Copyright (c) 2026 [sboxskins.gg](https://sboxskins.gg)

package/dist/index.js

@@ -48,6 +48,11 @@ import { registerInputTools } from "./tools/inputs.js";
 import { registerDebugVizTools } from "./tools/debugviz.js";
 import { registerDebugDrawTools } from "./tools/debugdraw.js";
 import { registerPlaytestTools } from "./tools/playtest.js";
+import { registerRoundStateTools } from "./tools/roundstate.js";
+import { registerStationTools } from "./tools/stations.js";
+import { registerDirectorTools } from "./tools/director.js";
+import { registerSaveSlotsTools } from "./tools/saveslots.js";
+import { registerGameFeelTools } from "./tools/gamefeel.js";
 // ── CLI flags ──────────────────────────────────────────────────────
 const args = process.argv.slice(2);
 /** Read the package version from package.json, or return "unknown" on failure. */
@@ -199,6 +204,11 @@ registerInputTools(server, bridge);
 registerDebugVizTools(server, bridge);
 registerDebugDrawTools(server, bridge);
 registerPlaytestTools(server, bridge);
+registerRoundStateTools(server, bridge);
+registerStationTools(server, bridge);
+registerDirectorTools(server, bridge);
+registerSaveSlotsTools(server, bridge);
+registerGameFeelTools(server, bridge);
 /** Start the MCP server on stdio and attempt initial Bridge connection. */
 async function main() {
     const transport = new StdioServerTransport();

package/dist/tools/characters.js

@@ -268,5 +268,29 @@ export function registerCharacterTools(server, bridge) {
             content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
         };
     });
+    // ── add_lipsync ────────────────────────────────────────────────────
+    server.tool("add_lipsync", "Add + wire s&box's LipSync component (new in the 2026-07 engine update): drives a SkinnedModelRenderer's facial morphs (visemes) from a playing sound. Wires the renderer on the target GameObject (or rendererId) and, if soundEvent is given, a SoundPointComponent bound to that .sound asset (see list_sounds / create_sound_event). Morphs animate at RUNTIME while the sound plays — verify in play mode with capture_view, not the static editor pose.", {
+        id: z.string().describe("GUID of the GameObject to add LipSync to (e.g. a spawn_citizen)"),
+        rendererId: z
+            .string()
+            .optional()
+            .describe("GUID of a different GameObject holding the SkinnedModelRenderer (default: same as id)"),
+        soundEvent: z
+            .string()
+            .optional()
+            .describe("Path to a .sound event to speak, e.g. 'sounds/dialogue/hello.sound' — creates/reuses a SoundPointComponent. Omit to wire an existing sound component on the GameObject (or wire audio later)."),
+        playOnStart: z.boolean().optional().describe("Play the sound on scene start (default true; only with soundEvent)"),
+        volume: z.number().optional().describe("SoundPointComponent volume (only with soundEvent)"),
+        morphScale: z.number().optional().describe("LipSync.MorphScale — exaggerate/dampen mouth movement (engine default when omitted)"),
+        morphSmoothTime: z.number().optional().describe("LipSync.MorphSmoothTime — morph smoothing seconds (engine default when omitted)"),
+    }, async (params) => {
+        const res = await bridge.send("add_lipsync", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
 }
 //# sourceMappingURL=characters.js.map

package/dist/tools/director.d.ts

@@ -0,0 +1,14 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * AI-director scaffold — generalized L4D-style event pacing.
+ *
+ *   - create_event_director  generate a host-authoritative "AI director" component that
+ *                            rolls on an interval, weighted-picks an event prefab,
+ *                            deduplicates against the active set, spawns it, and gives
+ *                            each spawned event a timed self-destruct.
+ *
+ * Code-gen + scene-mutating; refused during play mode by the bridge dispatch.
+ */
+export declare function registerDirectorTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=director.d.ts.map

package/dist/tools/director.js

@@ -0,0 +1,48 @@
+import { z } from "zod";
+/**
+ * AI-director scaffold — generalized L4D-style event pacing.
+ *
+ *   - create_event_director  generate a host-authoritative "AI director" component that
+ *                            rolls on an interval, weighted-picks an event prefab,
+ *                            deduplicates against the active set, spawns it, and gives
+ *                            each spawned event a timed self-destruct.
+ *
+ * Code-gen + scene-mutating; refused during play mode by the bridge dispatch.
+ */
+export function registerDirectorTools(server, bridge) {
+    // ── create_event_director ─────────────────────────────────────────
+    server.tool("create_event_director", "Generate a generalized L4D-style AI/pacing director component (host-authoritative). On a configurable interval the host rolls a weighted pick over a [Property] List<GameObject> EventPrefabs (with a parallel List<float> Weights), skips any event already active (dedupe) and anything past a MaxActive concurrency cap, clones the chosen prefab, NetworkSpawns it, and attaches a generated {name}TimedEvent companion so each spawned event self-destructs after EventLifetime seconds. Great for ambient events, waves, and world events. Single-player safe (IsProxy guard; NetworkSpawn falls back to a local clone). Fill EventPrefabs/Weights in the inspector or via the bridge after a hotload; edit the RollInterval() stub to make pacing adaptive (player-count/inactivity/time-pressure factors) per the ai-director cookbook. Optionally attached to an existing GameObject by GUID (after a hotload). NOTE: emits ONE .cs file containing two classes ({name} + {name}TimedEvent); the type only resolves after trigger_hotload.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the director (a {name}TimedEvent companion is generated alongside it). Defaults to 'EventDirector'"),
+        path: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        intervalSeconds: z
+            .number()
+            .optional()
+            .describe("Base seconds between director rolls. Defaults to 30 (clamped to >= 0.1)"),
+        maxActive: z
+            .number()
+            .int()
+            .optional()
+            .describe("Maximum number of concurrently-live events. Defaults to 3 (clamped to >= 1)"),
+        eventLifetime: z
+            .number()
+            .optional()
+            .describe("Seconds before each spawned event self-destructs. Defaults to 60 (clamped to >= 0.1)"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of an existing GameObject to attach the director to (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_event_director", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+}
+//# sourceMappingURL=director.js.map

package/dist/tools/gamefeel.d.ts

@@ -0,0 +1,14 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Game Feel pack — three "juice" scaffolds (v1.19.0):
+ *
+ *   - create_camera_shake         trauma-based Perlin camera shake
+ *   - add_flicker_light           flicker/pulse animator for an existing light
+ *   - create_floating_combat_text rising/fading damage-number popups
+ *
+ * All generate a clean, self-contained .cs (LOCAL/visual-only — no [Sync]);
+ * file/scene-mutating, refused during play mode by the bridge dispatch.
+ */
+export declare function registerGameFeelTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=gamefeel.d.ts.map

package/dist/tools/gamefeel.js

@@ -0,0 +1,113 @@
+import { z } from "zod";
+/**
+ * Game Feel pack — three "juice" scaffolds (v1.19.0):
+ *
+ *   - create_camera_shake         trauma-based Perlin camera shake
+ *   - add_flicker_light           flicker/pulse animator for an existing light
+ *   - create_floating_combat_text rising/fading damage-number popups
+ *
+ * All generate a clean, self-contained .cs (LOCAL/visual-only — no [Sync]);
+ * file/scene-mutating, refused during play mode by the bridge dispatch.
+ */
+export function registerGameFeelTools(server, bridge) {
+    // ── create_camera_shake ───────────────────────────────────────────
+    server.tool("create_camera_shake", "Generate a trauma-based camera shake component (the standard game-feel model: events add Trauma 0..1, shake magnitude = Trauma², smooth Perlin offsets — not white-noise jitter — and Trauma decays every frame, so explosions slam and footsteps barely register). Attach the generated component to the CAMERA GameObject; fire from any game code via the static <Name>.Shake(0.4f). Applies in OnPreRender AFTER controllers position the camera, with an un-apply guard so it neither fights a controller-driven camera nor accumulates on a static one, and restores the camera when trauma hits zero. LOCAL-only (no [Sync]) — call Shake inside an [Rpc.Broadcast] handler if every client should feel it. Optionally attached to an existing GameObject by GUID (after a hotload).", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated component. Defaults to 'CameraShake'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        maxOffset: z
+            .number()
+            .optional()
+            .describe("Positional shake at full trauma, in world units. Defaults to 6"),
+        maxAngle: z
+            .number()
+            .optional()
+            .describe("Rotational shake at full trauma, in degrees (applied to pitch/yaw/roll). Defaults to 4"),
+        frequency: z
+            .number()
+            .optional()
+            .describe("Noise speed — higher = violent rattle, lower = drunken sway. Defaults to 10"),
+        decayPerSecond: z
+            .number()
+            .optional()
+            .describe("How much trauma drains per second. Defaults to 1.5"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of the camera GameObject to attach to (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_camera_shake", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── add_flicker_light ─────────────────────────────────────────────
+    server.tool("add_flicker_light", "Generate a light-flicker animator and optionally attach it to an existing light GameObject by GUID. Five presets: Candle (soft organic sway), Fluorescent (mostly steady with random dips), Faulty (hard on/off cuts), Pulse (slow sine breathing), Lightning (dim baseline with rare bright flashes). Modulates the sibling Light component's LightColor around the color it found on enable (works on PointLight / SpotLight / DirectionalLight) and restores it exactly on disable; intensity 0..1 sets flicker depth, speed scales the whole pattern. The single biggest atmosphere win per call for horror/night scenes — pairs with apply_atmosphere. LOCAL/visual-only.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated component. Defaults to 'FlickerLight'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        style: z
+            .enum(["Candle", "Fluorescent", "Faulty", "Pulse", "Lightning"])
+            .optional()
+            .describe("Default flicker preset baked into the component (editable per-instance in the inspector). Defaults to 'Candle'"),
+        intensity: z
+            .number()
+            .optional()
+            .describe("Flicker depth 0..1: 0 = steady, 1 = full blackouts / double-bright flashes. Defaults to 0.5"),
+        speed: z
+            .number()
+            .optional()
+            .describe("Speed multiplier for the whole pattern. Defaults to 1"),
+        lightId: z
+            .string()
+            .optional()
+            .describe("GUID of a GameObject holding a light component to attach to (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("add_flicker_light", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── create_floating_combat_text ───────────────────────────────────
+    server.tool("create_floating_combat_text", "Generate a floating combat text component — rising, fading, camera-billboarded world-space popups for damage numbers, '+10 gold', pickup names. TextRenderer-based: no Razor, no WorldPanel, zero UI setup. Nothing to place in the scene — the generated class carries a static factory: <Name>.Spawn(position, \"-25\", Color.Red[, sizeMultiplier]) spawns a popup that rises at RiseSpeed, fades over Lifetime, and destroys itself. Pairs with create_health_system (spawn from the damage path so every hit prints its number). LOCAL-only — spawn inside an [Rpc.Broadcast] handler if every client should see it.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated component. Defaults to 'FloatingCombatText'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        riseSpeed: z
+            .number()
+            .optional()
+            .describe("World units the popup rises per second. Defaults to 48"),
+        lifetime: z
+            .number()
+            .optional()
+            .describe("Seconds until the popup is fully faded and destroyed. Defaults to 1.1"),
+        fontSize: z
+            .number()
+            .optional()
+            .describe("Base font size baked into Spawn() (the optional Spawn size argument multiplies it). Defaults to 24"),
+    }, async (params) => {
+        const res = await bridge.send("create_floating_combat_text", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+}
+//# sourceMappingURL=gamefeel.js.map

package/dist/tools/roundstate.d.ts

@@ -0,0 +1,28 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * create_round_state_machine — the COMPLEX, multi-state round machine scaffold.
+ *
+ * The sibling of create_round_phase_machine. Both are host-authoritative round
+ * flow, but they scaffold different shapes:
+ *
+ *   create_round_phase_machine  → ONE sealed component with a [Sync] enum cycled
+ *       on a shared per-phase timer. Reach for it for 3–5 LIGHT phases whose
+ *       only per-phase logic is "how long" (round/day-night/match phases).
+ *
+ *   create_round_state_machine  → a RoundManager singleton + an abstract
+ *       RoundState base (Begin/Tick/OnTimeUp/Finish lifecycle + per-state
+ *       [Sync] TimeUntil timer) + one sealed stub class PER state. Reach for it
+ *       when each phase deserves its OWN file/behaviour: entry side-effects,
+ *       per-frame Tick logic, a CanEnter() skip condition, copy-data-out-on-exit.
+ *       This is the "state-as-component" pattern from the round-match cookbook.
+ *
+ * The generated manager auto-attaches the state components on start (so a
+ * non-coder only places the manager), index-wraps when advancing, skips states
+ * whose CanEnter() returns false, and announces transitions via a static
+ * OnStateChanged event mirrored by an [Rpc.Broadcast] so proxies converge
+ * instantly (the [Sync] index is the durable late-joiner reconcile path).
+ * Single-player safe. Scene/file-mutating; refused during play mode.
+ */
+export declare function registerRoundStateTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=roundstate.d.ts.map

package/dist/tools/roundstate.js

@@ -0,0 +1,67 @@
+import { z } from "zod";
+/**
+ * create_round_state_machine — the COMPLEX, multi-state round machine scaffold.
+ *
+ * The sibling of create_round_phase_machine. Both are host-authoritative round
+ * flow, but they scaffold different shapes:
+ *
+ *   create_round_phase_machine  → ONE sealed component with a [Sync] enum cycled
+ *       on a shared per-phase timer. Reach for it for 3–5 LIGHT phases whose
+ *       only per-phase logic is "how long" (round/day-night/match phases).
+ *
+ *   create_round_state_machine  → a RoundManager singleton + an abstract
+ *       RoundState base (Begin/Tick/OnTimeUp/Finish lifecycle + per-state
+ *       [Sync] TimeUntil timer) + one sealed stub class PER state. Reach for it
+ *       when each phase deserves its OWN file/behaviour: entry side-effects,
+ *       per-frame Tick logic, a CanEnter() skip condition, copy-data-out-on-exit.
+ *       This is the "state-as-component" pattern from the round-match cookbook.
+ *
+ * The generated manager auto-attaches the state components on start (so a
+ * non-coder only places the manager), index-wraps when advancing, skips states
+ * whose CanEnter() returns false, and announces transitions via a static
+ * OnStateChanged event mirrored by an [Rpc.Broadcast] so proxies converge
+ * instantly (the [Sync] index is the durable late-joiner reconcile path).
+ * Single-player safe. Scene/file-mutating; refused during play mode.
+ */
+export function registerRoundStateTools(server, bridge) {
+    server.tool("create_round_state_machine", "Generate a host-authoritative MULTI-STATE round machine (the complex variant of create_round_phase_machine). Produces one .cs file: a RoundManager singleton component + an abstract RoundState base (Begin/Tick/OnTimeUp/Finish lifecycle with a per-state [Sync(SyncFlags.FromHost)] TimeUntil timer) + one sealed stub class per named state. The manager auto-attaches the state components on start (you only place the manager), ticks ONLY the active state on the host, Advance()s on timeout with index-wrap, SKIPS any state whose CanEnter() returns false, and announces every transition via a static OnStateChanged event plus an [Rpc.Broadcast] mirror so the host fires immediately and proxies converge without waiting a snapshot (the [Sync] index reconciles late joiners). Single-player safe. USE THIS (not create_round_phase_machine) when each phase needs its OWN behaviour — entry side-effects, per-frame Tick logic, a skip condition, or copy-data-out-on-exit; use the phase machine for 3–5 light phases that differ only in duration. Optionally attached to an existing GameObject by GUID (after a hotload).", {
+        name: z
+            .string()
+            .optional()
+            .describe("Manager class name. Defaults to 'RoundManager'. The abstract base is derived from it (RoundManager → RoundState)"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the .cs file (path override). Defaults to 'Code'"),
+        states: z
+            .array(z.string())
+            .optional()
+            .describe('Ordered state names — each becomes a sealed {Name}State stub class. Defaults to ["Waiting","Active","PostRound"]'),
+        duration: z
+            .number()
+            .optional()
+            .describe("Default seconds each state lasts (each state also gets its own tunable [Property] Duration). 0 = no auto-advance for a state. Defaults to 30"),
+        durations: z
+            .union([
+            z.array(z.number()),
+            z.record(z.number()),
+        ])
+            .optional()
+            .describe('Optional per-state duration override: an array aligned to `states` ([10,120,8]) OR an object keyed by state name ({"Waiting":10,"Active":120}). Any state not covered falls back to `duration`'),
+        loop: z
+            .boolean()
+            .optional()
+            .describe("Loop back to the first state after the last (true) or hold on the last state (false). Defaults to true"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of an existing GameObject to attach the manager to (only if the type is already loaded — trigger_hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_round_state_machine", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+}
+//# sourceMappingURL=roundstate.js.map

package/dist/tools/saveslots.d.ts

@@ -0,0 +1,15 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Multi-slot save manager scaffold — the slot-picker sibling of create_save_system.
+ *
+ *   - create_save_slots   generate a SaveSlotManager component: list / create /
+ *                         load / save / delete N save slots, each with picker
+ *                         metadata (name + timestamp + playtime), versioned
+ *                         payloads with delete-on-version-mismatch, and an
+ *                         optional GUID scene-object reconciliation on load.
+ *
+ * File/scene-mutating; refused during play mode by the bridge dispatch.
+ */
+export declare function registerSaveSlotsTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=saveslots.d.ts.map

package/dist/tools/saveslots.js

@@ -0,0 +1,45 @@
+import { z } from "zod";
+/**
+ * Multi-slot save manager scaffold — the slot-picker sibling of create_save_system.
+ *
+ *   - create_save_slots   generate a SaveSlotManager component: list / create /
+ *                         load / save / delete N save slots, each with picker
+ *                         metadata (name + timestamp + playtime), versioned
+ *                         payloads with delete-on-version-mismatch, and an
+ *                         optional GUID scene-object reconciliation on load.
+ *
+ * File/scene-mutating; refused during play mode by the bridge dispatch.
+ */
+export function registerSaveSlotsTools(server, bridge) {
+    // ── create_save_slots ─────────────────────────────────────────────
+    server.tool("create_save_slots", "Generate a multi-slot save MANAGER component (the slot-picker sibling of create_save_system). Use this when the game needs SEVERAL named save slots the player chooses between (New Game / Load Game menu, per-character or per-run saves) — not one silent autosave. Use create_save_system instead when a single implicit save file is enough. Emits one sealed Component that lists / creates / loads / saves / deletes N slots: a lightweight manifest file (saveslots.json) holds per-slot metadata for the picker (Used flag + Name + SavedAtUnix timestamp + PlaytimeSeconds) so listing never loads a heavy payload, and each slot's game state lives in its own saveslot_<i>.json. Versioned SlotData POCO with clamp-on-load Sanitize() and delete-on-version-mismatch; runs only on the owning machine (IsProxy guard). Static OnSlotLoaded / OnSlotSaved / OnSlotDeleted hooks for HUD. Storage stays within the verified FileSystem.Data.ReadJsonOrDefault / WriteJson / DeleteFile surface (index-file pattern, no directory enumeration). Set sceneReconciliation:true to also reconcile scene objects by GameObject.Id on load — records the save marks destroyed are destroyed, survivors repositioned, missing skipped (good for a placeable-world tycoon). Optionally attached to an existing GameObject by GUID (after a hotload).", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated component. Defaults to 'SaveSlotManager'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        maxSlots: z
+            .number()
+            .int()
+            .optional()
+            .describe("How many save slots the manager manages (manifest is normalized to exactly this many, indexed 0..N-1). Clamped to 1..100. Defaults to 3"),
+        sceneReconciliation: z
+            .boolean()
+            .optional()
+            .describe("If true, saved records carry each object's GameObject.Id GUID and load reconciles the live scene against them (destroy the save's destroyed records via Scene.Directory.FindByGuid, reposition survivors, skip missing) — call RecordObject(go) to track a placeable. If false (default), the slot save is a plain payload with no scene reconciliation. Defaults to false"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of an existing GameObject to attach the manager to (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_save_slots", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+}
+//# sourceMappingURL=saveslots.js.map

package/dist/tools/stations.d.ts

@@ -0,0 +1,15 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Interaction-station scaffold — a Tier-1 backlog item (mined from 2 games).
+ *
+ *   - add_interaction_station   an IPressable "station" prop (crafting bench /
+ *                               shop till / arcade cabinet) with host-authoritative
+ *                               single-occupant occupancy, a reservation grace
+ *                               window, an unlock-level gate, and an overlay-open hook.
+ *
+ * Generates a clean, self-contained .cs and optionally attaches it to a live
+ * GameObject. Scene/file-mutating; refused during play mode by the bridge dispatch.
+ */
+export declare function registerStationTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=stations.d.ts.map

package/dist/tools/stations.js

@@ -0,0 +1,47 @@
+import { z } from "zod";
+/**
+ * Interaction-station scaffold — a Tier-1 backlog item (mined from 2 games).
+ *
+ *   - add_interaction_station   an IPressable "station" prop (crafting bench /
+ *                               shop till / arcade cabinet) with host-authoritative
+ *                               single-occupant occupancy, a reservation grace
+ *                               window, an unlock-level gate, and an overlay-open hook.
+ *
+ * Generates a clean, self-contained .cs and optionally attaches it to a live
+ * GameObject. Scene/file-mutating; refused during play mode by the bridge dispatch.
+ */
+export function registerStationTools(server, bridge) {
+    // ── add_interaction_station ───────────────────────────────────────
+    server.tool("add_interaction_station", "Generate a Component.IPressable 'station' prop (crafting bench / shop till / arcade cabinet) that ONE user occupies at a time. Occupancy is host-authoritative: the occupant is a [Sync(SyncFlags.FromHost)] Guid (GameObject/Connection aren't [Sync]-able) and Press() routes the claim to the host via an [Rpc.Host] Occupy(). Includes a reservation grace window (the station stays reserved for its last user for graceSeconds after they leave, so a brief walk-away can't jump the queue), an optional unlock-level gate (users below requiredLevel can't use it — wire the static ResolveUserLevel hook to your progression system to activate it), and an overlay-open hook (a static OnStationOpened(GameObject) event to open your UI, plus an opt-in [Rpc.Broadcast] mirror). Single-player safe. Optionally attached to an existing GameObject by GUID (only after a trigger_hotload). Give the prop a Collider so the player's use key can raycast it. Mined from interaction-station patterns across shipped s&box games.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated component. Defaults to 'InteractionStation'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the .cs file (path override). Defaults to 'Code'"),
+        graceSeconds: z
+            .number()
+            .optional()
+            .describe("Seconds the station stays reserved for its last user after they leave, before anyone else can claim it. 0 = no grace window. Defaults to 5"),
+        requiredLevel: z
+            .number()
+            .int()
+            .optional()
+            .describe("Unlock-level gate: users below this level can't use the station. 0 = no gate. The gate only bites once you wire the static ResolveUserLevel hook to your progression system. Defaults to 0"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of an existing GameObject to attach the station component to (only attaches if the type is already loaded — generate, trigger_hotload, then it places; otherwise add it after the hotload)"),
+    }, async (params) => {
+        const res = await bridge.send("add_interaction_station", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+        };
+    });
+}
+//# sourceMappingURL=stations.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sbox-mcp-server",
-  "version": "1.17.1",
+  "version": "1.19.0",
   "description": "MCP Server for s&box game engine — enables Claude to build games through conversation",
   "type": "module",
   "main": "dist/index.js",
@@ -51,5 +51,5 @@
   "engines": {
     "node": ">=18.0.0"
   },
-  "license": "AGPL-3.0-or-later"
+  "license": "SEE LICENSE IN LICENSE"
 }