sbox-mcp-server 1.19.0 → 2.0.0

package/dist/tools/looteconomy.js

@@ -0,0 +1,107 @@
+import { z } from "zod";
+/**
+ * Loot / Economy variants pack — three Tier-2 scaffolds (v1.20.0, Track D):
+ *
+ *   - create_gacha_drop_table  per-rarity roll + pity counter + duplicate detection,
+ *                              host-authoritative ([Rpc.Host] roll → [Rpc.Broadcast])
+ *   - create_currency_pickup   networked coin: optional magnet + host-validated grant
+ *                              into create_economy_wallet's AddMoney + replicated despawn
+ *   - create_offline_progress  DateTime delta on enable + clamp + deterministic tick replay
+ *
+ * All generate a clean, self-contained sealed Component .cs; file/scene-mutating, refused
+ * during play mode by the bridge dispatch. create_currency_pickup + create_offline_progress
+ * emit host/owner-authoritative code ([Sync]-free state stays host-side); create_gacha_drop_table
+ * routes the roll through [Rpc.Host] and announces via [Rpc.Broadcast].
+ */
+export function registerLootEconomyTools(server, bridge) {
+    // ── create_gacha_drop_table ───────────────────────────────────────
+    server.tool("create_gacha_drop_table", "Generate a host-authoritative gacha / loot-box roller component. Two-level pick: parallel [Property] lists RarityNames + RarityWeights select a RARITY by cumulative weight (the create_weighted_loot_table shape), then a flat 'Rarity:Item' [Property] list (e.g. 'Legendary:Dragon Fang') picks an ITEM uniformly within that rarity — simple and inspector-editable. A pity counter (PityAfter, default 50) guarantees the rarest tier (the LAST entry in RarityNames) after N rolls without it and resets on a hit. Duplicate detection against an owned-items set fires a host-side OnDuplicate hook (marked TODO: convert dupes to shards/currency). Roll() routes to the host via an [Rpc.Host] RequestRoll (Rpc.Caller re-validated — NetFlags is not security) and the result fans out via [Rpc.Broadcast] so every machine fires the static OnRolled(rarity, item, isDuplicate) event; single-player safe (RPCs run locally). Use create_weighted_loot_table instead for a simpler single-tier weighted pick with no pity/dupe/networking. Pairs with create_economy_wallet (spend currency to roll) and create_inventory (store the pulls).", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated component. Defaults to 'GachaDropTable'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        pityAfter: z
+            .number()
+            .int()
+            .optional()
+            .describe("Rolls without a rarest-tier hit before the next roll is guaranteed rarest. 0 disables pity. Defaults to 50"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of a per-player/manager GameObject to attach to (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_gacha_drop_table", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── create_currency_pickup ────────────────────────────────────────
+    server.tool("create_currency_pickup", "Generate a networked coin / currency pickup component (sealed, Component.ITriggerListener). Host-spawned; when a GameObject carrying PlayerTag ('player') enters its trigger the HOST validates and grants Value (default 1) into a wallet on the player, then destroys the pickup network-wide (the host Destroy() replicates — there is no NetworkDestroy on this SDK). Optional magnet: while MagnetRadius (default 0 = off) is > 0 the coin accelerates toward the nearest player each FixedUpdate (host-side, capped by MaxMagnetSpeed). IsProxy guards keep the grant + despawn host-only in multiplayer (NetworkSpawn the coin on the host); single-player works with no networking. The deposit is reflection-free and dependency-free: a static Grant seam is wired ONCE to the direct typed call — player.Components.Get<EconomyWallet>()?.AddMoney(amount) — so the component compiles with NO hard reference to a specific wallet class (rename the wallet type if yours differs; mirrors create_pickup's self-contained convention). WalletComponentName (default 'EconomyWallet') is used to locate the wallet and name the fix if Grant is left unwired (never silent). Pairs with create_economy_wallet (AddMoney/TrySpend/CanAfford) and create_floating_combat_text (spawn a '+N' popup from OnCollected).", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated component. Defaults to 'CurrencyPickup'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        value: z
+            .number()
+            .int()
+            .optional()
+            .describe("How much currency the pickup grants into the wallet. Defaults to 1"),
+        magnetRadius: z
+            .number()
+            .optional()
+            .describe("Magnet range in world units — within it the coin flies to the nearest player each FixedUpdate. 0 = magnet off. Defaults to 0"),
+        walletComponentName: z
+            .string()
+            .optional()
+            .describe("Type name of the wallet component to deposit into (used to locate it and to name the fix if the Grant seam is left unwired). Defaults to 'EconomyWallet'"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of a coin GameObject to attach to — give it a trigger Collider (SphereCollider, IsTrigger=true). Only attaches if the type is already loaded — hotload first"),
+    }, async (params) => {
+        const res = await bridge.send("create_currency_pickup", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── create_offline_progress ───────────────────────────────────────
+    server.tool("create_offline_progress", "Generate an offline / idle-progress component (sealed, owner/host-only) — the idle-game staple. Persists LastSeenUtc (DateTime) to FileSystem.Data JSON on a dirty-flag autosave heartbeat (AutosaveSeconds) and on OnDisabled, copying create_save_system's persistence patterns. On enable it computes elapsed = now − LastSeenUtc, guards a clock rollback (negative → 0), clamps to MaxOfflineHours (default 8), then replays that time through a SimulateOffline(double seconds) TODO hook in fixed TickSeconds chunks (default 1) so idle accumulation is deterministic (frame-rate independent), and fires the static OnOfflineProgressApplied(seconds) event (drive a 'welcome back, you earned X' screen). IsProxy-guarded so a client can't author their own offline earnings. Fill in the SimulateOffline hook with your idle math (e.g. wallet.AddMoney(rate*seconds)). Pairs with create_economy_wallet / create_save_system / create_stat_modifier_system.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated component. Defaults to 'OfflineProgress'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        maxOfflineHours: z
+            .number()
+            .optional()
+            .describe("Offline time is clamped to this many hours (stops a week-away paying out a week). Defaults to 8"),
+        tickSeconds: z
+            .number()
+            .optional()
+            .describe("SimulateOffline chunk size in seconds — smaller = finer-grained deterministic replay (floored at 0.1). Defaults to 1"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of an idle/save-manager GameObject to attach to (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_offline_progress", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+}
+//# sourceMappingURL=looteconomy.js.map

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/moviemaker.d.ts

@@ -0,0 +1,17 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * MovieMaker / cutscene family (v1.20.0) — first bridge coverage of
+ * Sandbox.MovieMaker (landed in the shipping build; verified live 2026-07-08):
+ *
+ *   - list_movies       enumerate the project's .movie resources
+ *   - add_movie_player  wire a MoviePlayer component + MovieResource
+ *   - play_movie        start playback (real playback advances in play mode)
+ *   - stop_movie        stop playback (optionally rewind)
+ *
+ * Movies are AUTHORED in the editor's Movie Maker dock — the bridge wires and
+ * plays them; it does not author keyframes. Only add_movie_player is
+ * scene-mutating; play/stop stay callable during play mode.
+ */
+export declare function registerMovieMakerTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=moviemaker.d.ts.map

package/dist/tools/moviemaker.js

@@ -0,0 +1,98 @@
+import { z } from "zod";
+/**
+ * MovieMaker / cutscene family (v1.20.0) — first bridge coverage of
+ * Sandbox.MovieMaker (landed in the shipping build; verified live 2026-07-08):
+ *
+ *   - list_movies       enumerate the project's .movie resources
+ *   - add_movie_player  wire a MoviePlayer component + MovieResource
+ *   - play_movie        start playback (real playback advances in play mode)
+ *   - stop_movie        stop playback (optionally rewind)
+ *
+ * Movies are AUTHORED in the editor's Movie Maker dock — the bridge wires and
+ * plays them; it does not author keyframes. Only add_movie_player is
+ * scene-mutating; play/stop stay callable during play mode.
+ */
+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). 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}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── add_movie_player ──────────────────────────────────────────────
+    server.tool("add_movie_player", "Add a Sandbox.MovieMaker.MoviePlayer component and optionally wire a .movie resource into it — the cutscene playback primitive. Creates a new 'Movie Player' GameObject when no id is given. Set playOnStart to begin playback the moment play mode starts (intro cinematics), or leave it and trigger via play_movie (scripted cutscenes — call it from a trigger zone or dialogue beat). isLooping + timeScale map straight onto the component. Movies must already exist as .movie assets (list_movies; author in the Movie Maker dock). Scene-mutating — refused during play mode.", {
+        id: z
+            .string()
+            .optional()
+            .describe("GameObject GUID to attach to. Omit to create a new 'Movie Player' object"),
+        moviePath: z
+            .string()
+            .optional()
+            .describe("Asset-relative path of the .movie resource to wire (see list_movies)"),
+        isLooping: z.boolean().optional().describe("Loop playback"),
+        timeScale: z
+            .number()
+            .optional()
+            .describe("Playback speed multiplier (1 = normal)"),
+        createTargets: z
+            .boolean()
+            .optional()
+            .describe("Let the player create missing track-target objects on play"),
+        playOnStart: z
+            .boolean()
+            .optional()
+            .describe("Begin playing as soon as play mode starts (intro cinematic)"),
+    }, async (params) => {
+        const res = await bridge.send("add_movie_player", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── play_movie ────────────────────────────────────────────────────
+    server.tool("play_movie", "Start MoviePlayer playback. Targets the MoviePlayer on the given GameObject, or the first MoviePlayer in the scene when id is omitted. Pass moviePath to load-and-play a different .movie on the same player; positionSeconds seeks before playing; isLooping/timeScale apply immediately. Clips genuinely advance in PLAY MODE (start_play first, then verify with capture_view) — in edit mode this only sets state, which the response calls out. NOT scene-mutating, so it works during play mode.", {
+        id: z
+            .string()
+            .optional()
+            .describe("GameObject GUID holding the MoviePlayer. Omit to use the first MoviePlayer in the scene"),
+        moviePath: z
+            .string()
+            .optional()
+            .describe("Asset-relative .movie path to load and play (otherwise plays the wired Resource)"),
+        positionSeconds: z
+            .number()
+            .optional()
+            .describe("Seek to this time (seconds) before playing"),
+        timeScale: z
+            .number()
+            .optional()
+            .describe("Playback speed multiplier (1 = normal)"),
+        isLooping: z.boolean().optional().describe("Loop playback"),
+    }, async (params) => {
+        const res = await bridge.send("play_movie", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── stop_movie ────────────────────────────────────────────────────
+    server.tool("stop_movie", "Stop MoviePlayer playback (the counterpart to play_movie). Targets the MoviePlayer on the given GameObject, or the first MoviePlayer in the scene when id is omitted. Pass rewind to also reset the playhead to 0 so the next play_movie starts from the top. Works during play mode.", {
+        id: z
+            .string()
+            .optional()
+            .describe("GameObject GUID holding the MoviePlayer. Omit to use the first MoviePlayer in the scene"),
+        rewind: z
+            .boolean()
+            .optional()
+            .describe("Also reset the playhead to 0"),
+    }, async (params) => {
+        const res = await bridge.send("stop_movie", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+}
+//# sourceMappingURL=moviemaker.js.map

package/dist/tools/netprimitives.d.ts

@@ -0,0 +1,18 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Networking primitives pack — four multiplayer scaffolds (v1.20.0, Track B):
+ *
+ *   - create_host_rpc_action       validated + rate-limited [Rpc.Host] action skeleton
+ *   - add_targeted_rpc             Rpc.FilterInclude single-client (unicast) side-effect
+ *   - create_local_player_resolver proxy-safe "who is MY player" resolver (online + offline)
+ *   - add_host_migration_recovery  proxy→authority transition detector + OnBecameHost hook
+ *
+ * Each generates ONE self-contained sealed Component .cs into the project via
+ * ScaffoldHelpers. These are the correctness primitives every networked s&box
+ * game hand-rolls (and usually gets wrong): host-authoritative validated actions,
+ * unicast RPCs, proxy-safe local-player resolution, and host-migration recovery.
+ * All are file/scene-mutating and refused during play mode by the bridge dispatch.
+ */
+export declare function registerNetPrimitivesTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=netprimitives.d.ts.map

package/dist/tools/netprimitives.js

@@ -0,0 +1,110 @@
+import { z } from "zod";
+/**
+ * Networking primitives pack — four multiplayer scaffolds (v1.20.0, Track B):
+ *
+ *   - create_host_rpc_action       validated + rate-limited [Rpc.Host] action skeleton
+ *   - add_targeted_rpc             Rpc.FilterInclude single-client (unicast) side-effect
+ *   - create_local_player_resolver proxy-safe "who is MY player" resolver (online + offline)
+ *   - add_host_migration_recovery  proxy→authority transition detector + OnBecameHost hook
+ *
+ * Each generates ONE self-contained sealed Component .cs into the project via
+ * ScaffoldHelpers. These are the correctness primitives every networked s&box
+ * game hand-rolls (and usually gets wrong): host-authoritative validated actions,
+ * unicast RPCs, proxy-safe local-player resolution, and host-migration recovery.
+ * All are file/scene-mutating and refused during play mode by the bridge dispatch.
+ */
+export function registerNetPrimitivesTools(server, bridge) {
+    // ── create_host_rpc_action ────────────────────────────────────────
+    server.tool("create_host_rpc_action", "Generate a validated, rate-limited host-action component — the SAFE skeleton for 'a client asks the host to DO something' (buy, use, vote, interact, spend). The generated sealed Component exposes a client-callable Request() that forwards to an [Rpc.Host] SubmitRequest() which runs ON THE HOST: it re-resolves WHO called it via Rpc.Caller (never trusting client args for identity), enforces a per-SteamId cooldown backed by a Dictionary<ulong, TimeSince>, runs a clearly-marked TODO block for your authoritative action, and fires the static OnActionExecuted(Connection) event. This is the correct answer to the #1 multiplayer exploit class: [Rpc.Host] is callable by ANY client with forged args — NetFlags restrict who may INVOKE, which is not security — so identity + rate-limit + validation all live inside the host body. Single-player safe (no session → the RPC runs locally, caller falls back to Connection.Local). Attach it to the object that owns the action (a player, a station, or your game manager). Next steps: hotload, tag/attach, call Request() from input or a UI button, fill the TODO host block, and subscribe to OnActionExecuted. Covers the backlog's add_rate_limited_rpc. Optionally attached to an existing GameObject by GUID (after a hotload).", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated component. Defaults to 'HostRpcAction'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        cooldownSeconds: z
+            .number()
+            .optional()
+            .describe("Minimum seconds between accepted requests, per calling player (the per-SteamId rate limit). Defaults 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("create_host_rpc_action", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── add_targeted_rpc ──────────────────────────────────────────────
+    server.tool("add_targeted_rpc", "Generate a component demonstrating the unicast (single-client) RPC pattern via Rpc.FilterInclude. A normal [Rpc.Broadcast] runs on EVERY machine; the generated component's host-side SendTo(Connection target, string message) wraps its [Rpc.Broadcast] call in `using ( Rpc.FilterInclude( target ) )` so ONLY the target connection executes the body, which raises the static OnReceived(string) event. This is the RIGHT way to send something to one player — a private prompt, a personal reward toast, a per-player cutscene cue — instead of broadcasting to everyone and filtering on the client (which leaks data and wastes bandwidth). Call SendTo on the host (guarded behind Networking.IsActive so Networking.IsHost can't throw with no session; runs locally in solo). Attach to a networked manager object that is NetworkSpawn'd. Next steps: hotload, attach, call SendTo(player.Network.Owner, \"...\") from the host, and subscribe to OnReceived on the target client. Optionally attached to an existing GameObject by GUID (after a hotload).", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated component. Defaults to 'TargetedRpc'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        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_targeted_rpc", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── create_local_player_resolver ──────────────────────────────────
+    server.tool("create_local_player_resolver", "Generate a proxy-safe 'who is MY player?' resolver — the corpus footgun-killer that stops you running local-player logic against a proxy of someone else's player. The generated sealed Component exposes a static Local property that lazily finds the player GameObject belonging to THIS machine: online it's the tagged object whose Network.Owner is the local connection (Network.Owner == Connection.Local, or Network.IsOwner); offline/solo (no session) it's the first/only tagged player. The result is cached and revalidated with IsValid() so a destroyed or respawned player is re-resolved automatically. Also exposes a static IsLocal(GameObject) helper for filtering events (e.g. only open a station overlay for your own player). Works identically online and offline — no `if (Network.IsOwner)` guard that silently disables everything in a solo playtest. Attach ONE to a persistent object (your game manager) so PlayerTag is configurable in the inspector; the resolver is static and callable from anywhere. Next steps: hotload, attach, tag each player GameObject with the PlayerTag, then read <Name>.Local / filter with <Name>.IsLocal(go). Optionally attached to an existing GameObject by GUID (after a hotload).", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated component. Defaults to 'LocalPlayerResolver'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        playerTag: z
+            .string()
+            .optional()
+            .describe("Tag that marks a player GameObject (players must carry this tag). Baked as the default PlayerTag, editable per-instance in the inspector. Defaults to 'player'"),
+        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_local_player_resolver", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── add_host_migration_recovery ───────────────────────────────────
+    server.tool("add_host_migration_recovery", "Generate a host-migration recovery component — it detects when THIS machine takes authority over its GameObject (the proxy→authority transition that promotes a client to host when the old host leaves) and gives you a clean hook to rebuild host-only state. It tracks IsProxy each frame; when it flips from true (someone else was the authority) to false (now it's us), it fires the static OnBecameHost(GameObject) event and runs a virtual-style TODO rebuild region, then — after a tunable SettleSeconds delay so in-flight packets can land — runs a deferred validation region. s&box has a known bug where networked objects are often destroyed during host migration and the new host inherits stale transient state, so the recommended shape is: detect becoming host, aggressively rebuild (re-arm host-only loops/TimeUntil timers against your clock, TakeOwnership of orphans, rebuild handle maps by world position, reconcile the [Sync] registry against the real scene), and defer the sanity check ~1s. Inert offline (IsProxy is always false with no session). Attach to your host-authoritative manager object (NetworkSpawn'd). Next steps: hotload, attach, subscribe to OnBecameHost, and fill the two TODO regions. Requires a real host migration (a second client that becomes host) to fire — it can't be exercised in a solo playtest. Optionally attached to an existing GameObject by GUID (after a hotload).", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated component. Defaults to 'HostMigrationRecovery'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        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_host_migration_recovery", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+}
+//# sourceMappingURL=netprimitives.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) {

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