sbox-mcp-server 1.20.0 → 2.1.0

package/dist/tools/dialoguefx.js

@@ -0,0 +1,144 @@
+import { z } from "zod";
+/**
+ * Dialogue & Camera FX pair — two scaffold generators:
+ *
+ *   - generate_lipsync_dialogue  NPCs speak their lines with moving mouths
+ *                                (Synthesizer TTS + viseme-driven morphs + loose
+ *                                create_dialogue_system HUD bind)
+ *   - create_camera_effects      static conveniences over the SDK's built-in
+ *                                CameraComponent.AddShake/AddPunch/AddTilt
+ *
+ * Both write a .cs file into the project (scene/file-mutating; refused during
+ * play mode by the bridge dispatch). Both templates were live-verified on
+ * 2026-07-13: default render written into the live project, hotloaded, compile
+ * clean, TypeLibrary-load confirmed, then deleted. Key SDK facts verified the
+ * same day: Handle.LipSync.Visemes is IReadOnlyList<float> in the engine's
+ * 15-viseme order (read live from Sandbox.LipSync.VisemeNames), the viseme->
+ * morph mapping is baked into models (Model.GetVisemeMorph — nonzero on
+ * Citizen), and the camera built-ins are whitelist-callable from game code.
+ *
+ * Mirrors the aisystems.ts module shape: zod params, one bridge.send per tool,
+ * JSON.stringify(res.data) on success.
+ */
+// A world-space Vector3 accepted as EITHER an object {x,y,z} OR a comma string
+// "x,y,z", passed through unchanged. The C# handler parses both forms.
+const Vec3 = z
+    .union([
+    z.object({
+        x: z.number().describe("X"),
+        y: z.number().describe("Y"),
+        z: z.number().describe("Z"),
+    }),
+    z.string().describe('Comma string "x,y,z", e.g. "0,0,200"'),
+])
+    .describe('A world-space Vector3 — object {x,y,z} OR comma string "x,y,z"');
+export function registerDialogueFxTools(server, bridge) {
+    // ── generate_lipsync_dialogue ─────────────────────────────────────
+    server.tool("generate_lipsync_dialogue", "Generate a lipsync dialogue performer — NPCs SPEAK their lines with MOVING MOUTHS: a sealed Component holding a [Property] line list (speaker GameObject name + text) that, per line, (a) mirrors the line into a generated create_dialogue_system HUD when one exists (loose TypeLibrary capability bind: List<string> Lines + Begin() + bool IsActive — neither system references the other), (b) speaks the text via Sandbox.Speech.Synthesizer positionally AT the speaker (per-speaker voice name/gender/age/rate via the Voices list), (c) drives the speaker's SkinnedModelRenderer mouth morphs from the live viseme stream — Handle.LipSync.Visemes (IReadOnlyList<float> in the engine's 15-viseme order, read live from Sandbox.LipSync.VisemeNames 2026-07-13) multiplied through the model's own baked viseme->morph table (Model.GetVisemeMorph — verified nonzero on Citizen, e.g. viseme_AA -> openjawL/R; NOT a hand-guessed morph map), with MorphScale + smoothing, and (d) advances when the audio handle stops (LineGapSeconds pause, LineTimeoutSeconds safety-skip, Skip() to cut a line short, StopDialogue() to abort). Static events: OnLineStarted(dialogue, lineIndex, speaker) + OnDialogueFinished(dialogue). Returns {created, path, className, lineCount, voiceCount, propertyNames[], note}. Next: trigger_hotload + get_compile_errors, attach (targetId re-call or add_component_with_properties), fill Lines/Voices in the inspector or bake them via params, call Begin() from game code (or autoStart:true; pair with create_interactable). Limits & honesty: the editor cannot playtest audio, so the LIVE viseme stream is RUNTIME-UNVERIFIED — the generated LogVisemes() helper + DebugLogVisemes property confirm it in seconds in play mode (the API surface and mapping data ARE live-verified); models without baked viseme data log a warning and stay audio-only (Citizen has it); voices are machine/OS-specific and TrySetVoice is best-effort; LOCAL-only — call Begin() inside an [Rpc.Broadcast] for everyone; a bound HUD's own advance input stays active (it only ends that HUD's display, not the audio). Refused during play mode; refuses to overwrite an existing file.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class/file name. Defaults to 'LipsyncDialogue'. Sanitized to a valid C# identifier."),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory under the project root for the .cs file. Defaults to 'Code'."),
+        lines: z
+            .array(z.object({
+            speaker: z.string().optional().describe("Scene GameObject name to speak from (case-insensitive; drives THAT object's mouth). Empty/omitted = the component's own GameObject."),
+            text: z.string().describe("The spoken line."),
+        }))
+            .optional()
+            .describe("Dialogue lines baked as inspector-editable defaults. Defaults to a two-line demo on the own GameObject."),
+        voices: z
+            .array(z.object({
+            speaker: z.string().describe("Speaker name these voice settings apply to (matches lines[].speaker, case-insensitive)."),
+            voiceName: z.string().optional().describe("Exact installed OS voice name (machine-specific — the generated component's Voices list is inspector-editable). Empty = use gender/age hints."),
+            voiceGender: z.string().optional().describe("Voice gender hint used when voiceName is empty (e.g. 'Female', 'Male'). Pair with voiceAge. Passed through unvalidated."),
+            voiceAge: z.string().optional().describe("Voice age hint paired with voiceGender (e.g. 'Adult', 'Child', 'Senior')."),
+            rate: z.number().optional().describe("Speaking rate offset (integer): negative = slower, positive = faster. Defaults to 0."),
+        }))
+            .optional()
+            .describe("Per-speaker voice settings baked as defaults. Defaults to empty (every speaker uses the OS default voice)."),
+        volume: z.number().optional().describe("Playback volume for spoken lines. Defaults to 1."),
+        positional: z
+            .boolean()
+            .optional()
+            .describe("true (default): 3D audio parented to the speaker GameObject. false: flat 2D narrator voice."),
+        driveMouth: z
+            .boolean()
+            .optional()
+            .describe("true (default): drive the speaker's SkinnedModelRenderer mouth morphs from the viseme stream. false: audio-only."),
+        morphScale: z
+            .number()
+            .optional()
+            .describe("Multiplier on viseme-derived morph weights (same idea as Sandbox.LipSync.MorphScale). Defaults to 1."),
+        mouthSmoothSeconds: z
+            .number()
+            .optional()
+            .describe("Seconds of exponential smoothing on mouth morphs (0 = raw viseme weights). Defaults to 0.05."),
+        lineGapSeconds: z
+            .number()
+            .optional()
+            .describe("Pause between a line's audio ending and the next line starting. Defaults to 0.2."),
+        lineTimeoutSeconds: z
+            .number()
+            .optional()
+            .describe("Safety: a line whose audio never starts (synthesis pending/failed) is skipped after this many seconds. Defaults to 20."),
+        bindHud: z
+            .boolean()
+            .optional()
+            .describe("true (default): loosely bind a create_dialogue_system HUD in the scene (TypeLibrary capability match) and mirror each line into it. false: no HUD mirroring."),
+        autoStart: z
+            .boolean()
+            .optional()
+            .describe("true: Begin() fires in OnStart. Defaults to false (call Begin() from game code)."),
+        debugLogVisemes: z
+            .boolean()
+            .optional()
+            .describe("true: log the live viseme stream ~4x/second while speaking — the fast way to runtime-verify the mouth drive. Defaults to false."),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of a GameObject to attach the component to (only attaches if the type is already in the TypeLibrary — hotload first, then re-call or use add_component_with_properties)."),
+    }, async (params) => {
+        const res = await bridge.send("generate_lipsync_dialogue", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── create_camera_effects ─────────────────────────────────────────
+    server.tool("create_camera_effects", "Generate static conveniences over the SDK's BUILT-IN camera effects — CameraComponent.AddShake(amplitude, frequency, duration), AddPunch(Vector3 direction, amplitude, frequency, duration, fovAmplitude), AddPunch(Angles, ...) and AddTilt(Angles, duration, easeTime), all fire-and-forget, self-expiring, whitelist-verified in sandboxed game code 2026-07-13: a sealed Component exposing {name}.Shake/ShakeAt/Punch/PunchAngles/Tilt statics that resolve the main camera (Scene.Camera, else IsMainCamera search, else first camera; warn + return null when the scene has none) and return the live Sandbox.CameraEffectSystem.BaseEffect (Stop()/IsDone; ShakeAt sets Epicenter+Radius for distance falloff), plus one-word preset triggers — HitPunch() / ExplosionShake() / ExplosionShakeAt(position, radius) / LandingTilt() — driven by [Property] tunables. Statics work with NO instance placed; place the component only to tune presets in the inspector. RELATIONSHIP: create_camera_shake is the CONTINUOUS trauma model (AddTrauma accumulates and decays); these built-ins are ONE-SHOT engine effects — they compose safely, but don't fire both for the same event or hits feel doubled. Returns {created, path, className, staticApi[], presetTriggers[], propertyNames[], note}. Next: trigger_hotload + get_compile_errors, call the statics from game code (e.g. {name}.Shake(4, 25, 0.8) on explosion) or attach via targetId and trigger presets. Limits & honesty: compile + camera resolution verified; the editor cannot judge FEEL — tune amplitudes in a human playtest; effects are LOCAL visuals (wrap in [Rpc.Broadcast] for everyone). Refused during play mode; refuses to overwrite an existing file.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class/file name. Defaults to 'CameraFx'. Sanitized to a valid C# identifier."),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory under the project root for the .cs file. Defaults to 'Code'."),
+        hitPunchDirection: Vec3.optional().describe("HitPunch preset: punch direction. Defaults to Vector3.Backward (camera kicks back)."),
+        hitPunchAmplitude: z.number().optional().describe("HitPunch preset: positional kick strength. Defaults to 8."),
+        hitPunchFrequency: z.number().optional().describe("HitPunch preset: oscillation frequency. Defaults to 20."),
+        hitPunchDuration: z.number().optional().describe("HitPunch preset: seconds. Defaults to 0.25."),
+        hitPunchFovAmplitude: z.number().optional().describe("HitPunch preset: FOV kick amount (0 = none). Defaults to 3."),
+        explosionShakeAmplitude: z.number().optional().describe("ExplosionShake preset: shake strength. Defaults to 5."),
+        explosionShakeFrequency: z.number().optional().describe("ExplosionShake preset: oscillation frequency. Defaults to 25."),
+        explosionShakeDuration: z.number().optional().describe("ExplosionShake preset: seconds. Defaults to 0.8."),
+        landingTiltAngles: Vec3.optional().describe("LandingTilt preset as {x: pitch, y: yaw, z: roll} degrees (or 'p,y,r'). Defaults to 5 pitch / 0 yaw / 2 roll."),
+        landingTiltDuration: z.number().optional().describe("LandingTilt preset: seconds the tilt lasts. Defaults to 0.35."),
+        landingTiltEase: z.number().optional().describe("LandingTilt preset: ease-in/out time within the duration. Defaults to 0.15."),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of a GameObject to attach the component to — only needed to tune presets in the inspector; the statics work with no instance (only attaches if the type is already in the TypeLibrary — hotload first)."),
+    }, async (params) => {
+        const res = await bridge.send("create_camera_effects", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+}
+//# sourceMappingURL=dialoguefx.js.map

package/dist/tools/discovery.js

@@ -19,21 +19,21 @@ export function registerDiscoveryTools(server, bridge) {
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
     // ── list_libraries ───────────────────────────────────────────────
-    server.tool("list_libraries", "List the s&box libraries/addons installed in this project (reads Libraries/ + each .sbproj). Discovers what's available to build ON — e.g. character controllers (fish.scc = Shrimple Character Controller, facepunch.playercontroller), world/spline/road tools — so you can leverage an installed library (add its components via add_component_with_properties, or generate code against its API) instead of writing from scratch. Returns ident/org/title/type/enabled per library. Read-only.", {}, async () => {
+    server.tool("list_libraries", "List the s&box libraries/addons installed in this project (reads Libraries/ + each .sbproj). Discovers what's available to build ON — e.g. character controllers (fish.scc = Shrimple Character Controller, facepunch.playercontroller), world/spline/road tools — so you can leverage an installed library (add its components via add_component_with_properties, or generate code against its API) instead of writing from scratch. Returns `count` and `libraries` [{folder, ident, org, title, type, enabled}] — ALL libraries, no limit or pagination; `enabled` is false when the library's .sbproj has been disabled (renamed .sbproj.disabled). Read-only.", {}, async () => {
         const res = await bridge.send("list_libraries", {});
         if (!res.success)
             return { content: [{ type: "text", text: `Error: ${res.error}` }] };
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
     // ── search_types ─────────────────────────────────────────────────
-    server.tool("search_types", "Find types matching a name pattern. Pass components_only=true to filter to Component subclasses only. Useful for discovering 'is there a built-in X for this?'", {
+    server.tool("search_types", "Find loaded types matching a name pattern. Useful for discovering 'is there a built-in X for this?'. Returns `count` and `matches` with each type's name, fullName, isComponent, and isAbstract — results are silently truncated at `limit` (default 50), so narrow the pattern if you hit the cap. Pass a match's name to describe_type for its full member surface.", {
         pattern: z.string().describe("Substring to match against type name (case-insensitive)"),
         namespace: z
             .string()
             .optional()
             .describe("Optional namespace filter (case-insensitive substring)"),
-        components_only: z.boolean().default(false),
-        limit: z.number().int().default(50),
+        components_only: z.boolean().default(false).describe("Only return Component subclasses (default false)"),
+        limit: z.number().int().default(50).describe("Maximum matches to return (default 50); the search stops silently at this cap"),
     }, async (params) => {
         const res = await bridge.send("search_types", params);
         if (!res.success)
@@ -51,10 +51,10 @@ export function registerDiscoveryTools(server, bridge) {
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
     // ── find_in_project ──────────────────────────────────────────────
-    server.tool("find_in_project", "Grep the user's s&box project for a symbol. Returns file paths and line numbers. Useful for finding usage examples of an API or seeing how the project already does something.", {
+    server.tool("find_in_project", "Grep the user's s&box project for a symbol (case-sensitive substring; skips .git/bin/obj). Useful for finding usage examples of an API or seeing how the project already does something. Returns `symbol`, `count`, and `results` [{file, line, text}], capped at `max_results` (default 25) — raise it if you may be missing hits. Follow up with read_file on a result's file path.", {
         symbol: z.string().describe("Substring or symbol to search for"),
         extension: z.string().default(".cs").describe("File extension filter"),
-        max_results: z.number().int().default(25),
+        max_results: z.number().int().default(25).describe("Maximum hits to return (default 25); the search stops once reached"),
     }, async (params) => {
         const res = await bridge.send("find_in_project", params);
         if (!res.success)

package/dist/tools/economysave.d.ts

@@ -0,0 +1,27 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Economy & Save family — six Tier-2 scaffolds (Track E):
+ *
+ *   - create_currency_account    audited host-authoritative ledger: [Sync(FromHost)]
+ *                                balance + Deposit/Withdraw/TryTransfer + a fixed-size
+ *                                transaction ring buffer with GetRecentTransactions()
+ *   - create_idle_economy        geometric bulk-buy purchasing (BaseCost * Growth^Owned,
+ *                                closed-form Buy 1 / N / Max) + income auto-wired to a
+ *                                sibling wallet via TypeLibrary reflection
+ *   - create_signed_save         tamper-evident save: FNV-1a signature over payload+salt,
+ *                                verify-on-load, Sanitize() clamp hook, forced reset on
+ *                                mismatch, versioned
+ *   - create_meta_progression    between-runs roguelite meta: persistent meta-currency +
+ *                                unlock flags, BankRun(int) run-end seam, OnUnlocked event
+ *   - add_steam_stat_currency    currency persisted over Sandbox.Services.Stats
+ *                                (Steam-cloud, per account, per package ident)
+ *   - create_loot_table_resource GameResource-based loot table assets ([AssetType],
+ *                                .loot files, nested tables, depth cap) + a resolver component
+ *
+ * All generate clean, self-contained sealed game code (.cs) into the project; file/scene
+ * mutating, refused during play mode by the bridge dispatch. Host-authoritative state uses
+ * [Sync(SyncFlags.FromHost)] + IsProxy guards throughout.
+ */
+export declare function registerEconomySaveTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=economysave.d.ts.map

package/dist/tools/economysave.js

@@ -0,0 +1,231 @@
+import { z } from "zod";
+/**
+ * Economy & Save family — six Tier-2 scaffolds (Track E):
+ *
+ *   - create_currency_account    audited host-authoritative ledger: [Sync(FromHost)]
+ *                                balance + Deposit/Withdraw/TryTransfer + a fixed-size
+ *                                transaction ring buffer with GetRecentTransactions()
+ *   - create_idle_economy        geometric bulk-buy purchasing (BaseCost * Growth^Owned,
+ *                                closed-form Buy 1 / N / Max) + income auto-wired to a
+ *                                sibling wallet via TypeLibrary reflection
+ *   - create_signed_save         tamper-evident save: FNV-1a signature over payload+salt,
+ *                                verify-on-load, Sanitize() clamp hook, forced reset on
+ *                                mismatch, versioned
+ *   - create_meta_progression    between-runs roguelite meta: persistent meta-currency +
+ *                                unlock flags, BankRun(int) run-end seam, OnUnlocked event
+ *   - add_steam_stat_currency    currency persisted over Sandbox.Services.Stats
+ *                                (Steam-cloud, per account, per package ident)
+ *   - create_loot_table_resource GameResource-based loot table assets ([AssetType],
+ *                                .loot files, nested tables, depth cap) + a resolver component
+ *
+ * All generate clean, self-contained sealed game code (.cs) into the project; file/scene
+ * mutating, refused during play mode by the bridge dispatch. Host-authoritative state uses
+ * [Sync(SyncFlags.FromHost)] + IsProxy guards throughout.
+ */
+export function registerEconomySaveTools(server, bridge) {
+    // ── create_currency_account ───────────────────────────────────────
+    server.tool("create_currency_account", "Generate a host-authoritative currency ACCOUNT component (sealed) — the audited sibling of create_economy_wallet (wallet = simple money, account = money + a ledger). Balance is [Sync(SyncFlags.FromHost)] so clients can't author their own money; host-guarded Deposit(amount, reason), Withdraw(amount, reason) -> bool, and TryTransfer(otherAccount, amount, reason) -> bool each record a Transaction { Time (Time.Now), signed Amount, Reason, BalanceAfter } into a fixed-size ring buffer (historySize, default 32; oldest entries overwritten SILENTLY). GetRecentTransactions(max) returns them NEWEST FIRST — the ledger is HOST-SIDE ONLY and does not replicate (Balance does); proxies get an empty list. Bind the instance OnBalanceChanged(long) for HUD labels. Single-player safe. Returns { created, path, className, startingBalance, historySize, placedOn, note, nextSteps }. Next: trigger_hotload, then attach via targetId re-run or add_component_to_new_object. Refuses if the file already exists; refused during play mode. Use create_economy_wallet when you don't need the audit trail; pair with create_idle_economy (it auto-wires this account's Money/TrySpend).", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated component. Defaults to 'CurrencyAccount'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        startingBalance: z
+            .number()
+            .int()
+            .optional()
+            .describe("Balance the account opens with (host seeds it in OnStart). Defaults to 0"),
+        historySize: z
+            .number()
+            .int()
+            .optional()
+            .describe("Transaction ring-buffer capacity (clamped 1..4096); fixed once the first transaction is recorded, oldest overwritten silently after that. Defaults to 32"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of a per-player/bank GameObject to attach to (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_currency_account", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── create_idle_economy ───────────────────────────────────────────
+    server.tool("create_idle_economy", "Generate a geometric idle-economy component (sealed): generators on the classic BaseCost * Growth^Owned cost curve with Buy 1 / Buy N / Buy Max — CostOf(index, count), MaxAffordable(index), TryBuy(index, count) and BuyMax(index) all use the CLOSED-FORM geometric series (cost = c0*(g^n-1)/(g-1), buyMax = floor(log_g(funds*(g-1)/c0+1))) — no per-copy loops, Buy 1000 is the same math as Buy 1. Wallet wiring is TypeLibrary reflection with NO compile-time wallet dependency (the shipped create_idle_income pattern): each income tick invokes AddMoney(long|int) on the first sibling component that has one, purchases invoke TrySpend(long|int), Buy Max reads the sibling's Money (or Balance) property — works out of the box next to create_economy_wallet or create_currency_account; with NO wallet sibling, purchases are refused with a Log.Warning (never silent) while TotalEarned still accumulates. Host-authoritative: mutations IsProxy-guarded; owned counts are HOST-SIDE state (not replicated); TotalEarned is [Sync(FromHost)]. Static events OnPurchased(index, count, cost) and OnIncomeTick(amount, total). BuyMax steps down once past a whole-currency rounding edge rather than failing. Returns { created, path, className, generators, tickSeconds, placedOn, note, nextSteps }. Next: trigger_hotload, place it NEXT TO a wallet on the same GameObject, tune the parallel GeneratorNames/BaseCosts/Growths/IncomesPerSecond lists with set_property. Refused during play mode. Pair with create_offline_progress for away-time earnings; use create_idle_income for a bare income ticker with no purchasing.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated component. Defaults to 'IdleEconomy'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        tickSeconds: z
+            .number()
+            .optional()
+            .describe("Seconds between income grants (floored at 0.1). Defaults to 1"),
+        generators: z
+            .array(z.object({
+            name: z.string().optional().describe("Generator display name"),
+            baseCost: z.number().optional().describe("Cost of the first copy. Defaults to 15"),
+            growth: z.number().optional().describe("Per-copy cost multiplier, min 1 (1.15 = classic curve). Defaults to 1.15"),
+            incomePerSecond: z.number().optional().describe("Income each owned copy produces per second. Defaults to 0.5"),
+        }))
+            .optional()
+            .describe("Baked-in generator defaults (inspector-tunable after generation). Omit for a starter trio: Cursor 15/1.15/0.5, Farm 200/1.15/4, Factory 3000/1.12/30"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of the GameObject to attach to — put it on the SAME GameObject as the wallet so the reflection wiring finds it (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_idle_economy", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── create_signed_save ────────────────────────────────────────────
+    server.tool("create_signed_save", "Generate a tamper-evident, versioned save-system component (sealed, owner-only). The SaveData payload POCO is serialized to JSON (Sandbox.Json), FNV-1a-64 hashed over payload + version + salt, and written as a signed envelope { Version, Payload, Signature } to FileSystem.Data. Load() re-verifies: a signature mismatch (hand-edited/corrupt file) triggers a FORCED RESET — the save file is DELETED, defaults are used, and the static OnTampered(reason) event fires (destructive and deliberate; tell the player). A version mismatch starts fresh without the tamper event (add migrations in Load). Loaded values pass a Sanitize() clamp hook so even a re-signed save can't smuggle absurd values. Dirty-flag autosave (autosaveSeconds, default 10; MarkDirty() to arm) + a final save in OnDestroy. HONEST LIMIT: the salt ships inside the game assembly, so this is tamper-EVIDENT (stops notepad edits), NOT cryptographically secure. If you omit salt, a unique random one is baked into the generated file — changing it later invalidates existing saves. Returns { created, path, className, fileName, version, autosaveSeconds, placedOn, note, nextSteps }. Next: trigger_hotload, attach, add your fields to SaveData + clamps to Sanitize(), bump version on shape changes. Refused during play mode. Use create_save_system for a plain unsigned save, create_save_slots for multi-slot UI flows, create_meta_progression for roguelite meta-state.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated component. Defaults to 'SignedSave'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        fileName: z
+            .string()
+            .optional()
+            .describe("FileSystem.Data path the signed envelope is written to. Defaults to 'save_signed.json'"),
+        version: z
+            .number()
+            .int()
+            .optional()
+            .describe("Save-shape version baked into the file and the signature; mismatched files start fresh. Defaults to 1"),
+        salt: z
+            .string()
+            .optional()
+            .describe("Signing salt baked into the generated code. Omit to bake a unique random salt (recommended); changing it later invalidates existing saves"),
+        autosaveSeconds: z
+            .number()
+            .optional()
+            .describe("Dirty-flag autosave cadence in seconds; 0 disables the heartbeat (OnDestroy still saves). Defaults to 10"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of a save-manager GameObject to attach to (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_signed_save", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── create_meta_progression ───────────────────────────────────────
+    server.tool("create_meta_progression", "Generate a between-runs roguelite meta-progression component (sealed, owner-only): persistent meta-currency + an unlock-flag dictionary saved to FileSystem.Data JSON (dirty-flag autosave + OnDestroy, the create_save_system shape). API: Grant(long), TrySpend(long) -> bool, Unlock(key) (idempotent — the static OnUnlocked(key) event fires only on the FIRST unlock, and unlocks write through to disk immediately), IsUnlocked(key) -> bool, and the run-end seam BankRun(int earned) which converts a finished run's earnings into meta-currency, bumps RunsBanked, and saves immediately — call it from your round machine's end-of-run transition (create_round_state_machine / create_round_phase_machine). Instance OnCurrencyChanged(long) drives meta-shop balance labels. Versioned payload: old-version files start fresh. IsProxy-guarded — in multiplayer each machine banks only its own local meta file (this is per-machine persistence, not a server economy). Returns { created, path, className, fileName, version, placedOn, note, nextSteps }. Next: trigger_hotload, attach to a persistent hub/menu-scene manager GameObject, gate content with IsUnlocked when building the player. Refused during play mode. Pair with create_currency_account (in-run money) and create_signed_save (if the meta file needs tamper evidence — this one is unsigned).", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated component. Defaults to 'MetaProgression'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        fileName: z
+            .string()
+            .optional()
+            .describe("FileSystem.Data path the meta state is written to. Defaults to 'meta.json'"),
+        version: z
+            .number()
+            .int()
+            .optional()
+            .describe("Payload version; mismatched files start fresh. Defaults to 1"),
+        autosaveSeconds: z
+            .number()
+            .optional()
+            .describe("Dirty-flag autosave cadence in seconds; 0 disables the heartbeat (unlocks and BankRun still write through immediately). Defaults to 10"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of a persistent manager GameObject to attach to (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_meta_progression", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── add_steam_stat_currency ───────────────────────────────────────
+    server.tool("add_steam_stat_currency", "Generate a currency component (sealed) persisted over Sandbox.Services.Stats — Steam-cloud persistence, per Steam account, per package ident, with NO local save file. The stat stores the ABSOLUTE balance: every Add(double)/TrySpend(double) pushes Stats.SetValue(statName, balance); Flush() (and OnDestroy) pushes the buffered writes. On start it reads the balance back asynchronously via Stats.GetLocalPlayerStats(ident) -> Refresh() -> Get(statName).Value and fires the static OnBalanceLoaded(double); wait for IsLoaded before showing the balance. CLOUD SEMANTICS (surprising): stat writes are buffered/rate-limited by the backend and apply ONLY to the LOCAL Steam user — calling this for another player silently does nothing, so attach it to the LOCAL player's GameObject (IsProxy guards keep remote copies inert); read-back is eventually consistent and can lag minutes behind writes — the in-session Balance property is the runtime truth. Dev sessions without a real published package ident may read back nothing (balance starts 0 with a log line). packageIdent defaults to the running package (Game.Ident). Returns { created, path, className, statName, packageIdent, flushEveryChange, placedOn, note, nextSteps }. Next: trigger_hotload, attach to the local player, bind OnBalanceChanged for the HUD. Refused during play mode. Use create_economy_wallet/create_currency_account for in-run networked money, create_signed_save for offline local persistence; pair with create_leaderboard_panel (the same stat can back a leaderboard).", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated component. Defaults to 'SteamStatCurrency'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        statName: z
+            .string()
+            .optional()
+            .describe("Sandbox.Services stat that stores the balance (the stat-name string is the contract between write and read-back). Defaults to 'currency'"),
+        packageIdent: z
+            .string()
+            .optional()
+            .describe("Package ident to read stats from. Omit/empty = the running package (Game.Ident)"),
+        flushEveryChange: z
+            .boolean()
+            .optional()
+            .describe("Call Stats.Flush() after every balance change instead of relying on the buffered flush + OnDestroy flush (the backend rate-limits flushes). Defaults to false"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of the LOCAL player's GameObject to attach to (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("add_steam_stat_currency", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── create_loot_table_resource ────────────────────────────────────
+    server.tool("create_loot_table_resource", "Generate GameResource-based loot tables — the data-asset sibling of create_weighted_loot_table. One .cs file containing THREE types: an entry POCO { Name, Weight, optional NestedTable reference }, a [AssetType]-registered GameResource loot-table class (designers author '.loot' files in the editor asset browser — New > Loot Table — after the hotload; NOTE: [AssetType(Name=..., Extension=..., Category=...)] is used because GameResourceAttribute is [Obsolete] on this SDK), and a '<name>Resolver' Component that rolls an assigned table by cumulative weight. Nested tables: an entry with a NestedTable rolls INTO that table instead of dropping its Name, capped at maxDepth (default 4) with a self-reference guard so cycles terminate (at the cap the deepest entry's Name is returned). Resolver.Roll() returns the item name (null + warning when no Table is assigned or the table is empty; entries with weight <= 0 never win; all-zero weights fall back to the first entry) and fires the static OnLoot(GameObject, item) event; roll HOST-SIDE and replicate the result yourself. targetId attaches the RESOLVER (the resource is an asset type, not a component). SURPRISING: pick an extension that is NOT a suffix of a built-in one (e.g. avoid 'cfg') or ResourceLibrary picks up engine files as phantom instances. Returns { created, path, className, resolverClass, extension, maxDepth, placedOn, note, nextSteps }. Next: trigger_hotload -> author .loot assets in the editor -> assign the resolver's Table (set_property with the asset path). Refused during play mode. Use create_weighted_loot_table for a single inline component with no asset files; create_gacha_drop_table for pity + duplicate mechanics.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated GameResource (the resolver becomes '<name>Resolver'). Defaults to 'LootTableResource'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        extension: z
+            .string()
+            .optional()
+            .describe("Asset file extension (lowercase alphanumerics; avoid suffixes of built-in extensions like 'cfg'). Defaults to 'loot'"),
+        title: z
+            .string()
+            .optional()
+            .describe("Display name of the asset type in the editor's New-asset menu. Defaults to 'Loot Table'"),
+        maxDepth: z
+            .number()
+            .int()
+            .optional()
+            .describe("Default nested-table resolve depth cap baked into the resolver (clamped 0..16; also a [Property]). Defaults to 4"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of a GameObject to attach the RESOLVER component to (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_loot_table_resource", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+}
+//# sourceMappingURL=economysave.js.map

package/dist/tools/gameobjects.js

@@ -70,7 +70,7 @@ export function registerGameObjectTools(server, bridge) {
         };
     });
     // ── duplicate_gameobject ─────────────────────────────────────────
-    server.tool("duplicate_gameobject", "Clone a GameObject with all its components. Optionally offset position or rename", {
+    server.tool("duplicate_gameobject", "Clone a GameObject with all its components. Returns { duplicated, original, gameObject } — gameObject.id is the clone's new GUID; pass it to set_transform / add_component_with_properties. If offset is omitted the clone lands exactly on top of the original.", {
         id: z.string().describe("GUID of the GameObject to duplicate"),
         name: z.string().optional().describe("New name for the clone"),
         offset: Vector3Schema.optional().describe("Position offset from original so the clone doesn't overlap"),
@@ -84,7 +84,7 @@ export function registerGameObjectTools(server, bridge) {
         };
     });
     // ── rename_gameobject ────────────────────────────────────────────
-    server.tool("rename_gameobject", "Change the display name of a GameObject", {
+    server.tool("rename_gameobject", "Change the display name of a GameObject identified by its GUID (the GUID itself never changes, so existing references stay valid). Returns { renamed, id, oldName, newName }. Name-based lookups (e.g. find_objects) will see the new name immediately.", {
         id: z.string().describe("GUID of the GameObject"),
         name: z.string().describe("New display name"),
     }, async (params) => {
@@ -114,7 +114,7 @@ export function registerGameObjectTools(server, bridge) {
         };
     });
     // ── set_enabled ──────────────────────────────────────────────────
-    server.tool("set_enabled", "Enable or disable a GameObject (disabled objects are invisible and inactive)", {
+    server.tool("set_enabled", "Enable or disable a GameObject (disabled objects are invisible and inactive, including their components and children). Returns { id, enabled } confirming the new state.", {
         id: z.string().describe("GUID of the GameObject"),
         enabled: z.boolean().describe("true to enable, false to disable"),
     }, async (params) => {
@@ -127,7 +127,7 @@ export function registerGameObjectTools(server, bridge) {
         };
     });
     // ── set_transform ────────────────────────────────────────────────
-    server.tool("set_transform", "Set position, rotation, and/or scale on a GameObject. Only provided values are changed", {
+    server.tool("set_transform", "Set position, rotation, and/or scale on a GameObject. Only provided values are changed; values apply in world space unless local=true. Returns { transformed, gameObject } with the full serialized object (id, name, position, rotation, scale, components) so you can verify what actually applied.", {
         id: z.string().describe("GUID of the GameObject"),
         position: Vector3Schema.optional().describe("New position"),
         rotation: RotationSchema.optional().describe("New rotation"),
@@ -170,7 +170,7 @@ export function registerGameObjectTools(server, bridge) {
         };
     });
     // ── get_selected_objects ─────────────────────────────────────────
-    server.tool("get_selected_objects", "Get the GameObjects currently selected by the user in the s&box editor", {}, async () => {
+    server.tool("get_selected_objects", "Get the GameObjects currently selected by the user in the s&box editor. Returns { count, selected } where each entry is a serialized GameObject (id, name, enabled, position, rotation, scale, components, childCount) — use the ids with set_transform, add_component_with_properties, etc. Handy for 'do X to what I have selected' requests.", {}, async () => {
         const res = await bridge.send("get_selected_objects");
         if (!res.success) {
             return { content: [{ type: "text", text: `Error: ${res.error}` }] };
@@ -180,7 +180,7 @@ export function registerGameObjectTools(server, bridge) {
         };
     });
     // ── select_object ────────────────────────────────────────────────
-    server.tool("select_object", "Select a GameObject in the editor (highlights it in the hierarchy and scene view)", {
+    server.tool("select_object", "Select a GameObject in the editor (highlights it in the hierarchy and scene view). Replaces the current selection unless addToSelection=true. Returns { selected, id }; confirm the result with get_selected_objects.", {
         id: z.string().describe("GUID of the GameObject to select"),
         addToSelection: z
             .boolean()
@@ -196,7 +196,7 @@ export function registerGameObjectTools(server, bridge) {
         };
     });
     // ── focus_object ─────────────────────────────────────────────────
-    server.tool("focus_object", "Move the editor camera to focus on a specific GameObject (like double-clicking in the hierarchy)", {
+    server.tool("focus_object", "Highlight a GameObject by selecting it in the editor. NOTE: s&box exposes no dedicated focus API, so this only sets the selection — it does NOT move any camera (returns { focused, id, note } saying so). To actually point the viewport at an object use frame_camera; to aim a screenshot use screenshot_from.", {
         id: z.string().describe("GUID of the GameObject to focus"),
     }, async (params) => {
         const res = await bridge.send("focus_object", params);

package/dist/tools/gameplay.js

@@ -109,7 +109,7 @@ export function registerGameplayTools(server, bridge) {
     });
     // ── create_objective_system ───────────────────────────────────────
     // The win/lose primitive — turns "objects in a scene" into "a game with a goal".
-    server.tool("create_objective_system", "Generate an ObjectiveManager component — the win/lose brain of a game. Tracks an objective (collect_all / reach_goal / survive_time / eliminate_all), fires a win, and handles a lose condition (fall below kill-Z / timer / out of lives). Self-contained C#; other systems call ObjectiveManager.Instance. Optionally placed as a scene singleton", {
+    server.tool("create_objective_system", "Generate an ObjectiveManager component — the win/lose brain of a game. Tracks an objective (collect_all / reach_goal / survive_time / eliminate_all), fires a win, and handles a lose condition (fall below kill-Z / timer / out of lives). Self-contained C#; other systems call ObjectiveManager.Instance. Optionally placed as a scene singleton. Returns { created, path, className, gameObject, note } — gameObject is the placed singleton, or null with a note when the fresh type isn't in the TypeLibrary yet. Follow with trigger_hotload, then get_compile_errors; if placement was skipped, place with add_component_to_new_object after the hotload", {
         name: z
             .string()
             .optional()
@@ -310,7 +310,7 @@ export function registerGameplayTools(server, bridge) {
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
     // -- create_pickup -----------------------------------------------------
-    server.tool("create_pickup", "Generate a trigger-based collectible component. On enter by a tagged object it raises OnCollected (wire it to your objective/score system) and despawns. Optionally builds a visible pickup GameObject with a trigger SphereCollider (+ a model) in one call", {
+    server.tool("create_pickup", "Generate a trigger-based collectible component. On enter by a tagged object it raises OnCollected (wire it to your objective/score system) and despawns. Optionally builds a visible pickup GameObject with a trigger SphereCollider (+ a model) in one call. Returns { created, path, className, gameObject, note } — gameObject is the placed pickup (null unless placeInScene=true); a note flags when the component couldn't attach because the fresh type needs a hotload. Follow with trigger_hotload, then get_compile_errors", {
         name: z.string().optional().describe("Class name. Defaults to 'Pickup'"),
         directory: z
             .string()
@@ -379,7 +379,7 @@ export function registerGameplayTools(server, bridge) {
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
     // -- create_leaderboard_panel ------------------------------------------
-    server.tool("create_leaderboard_panel", "Generate a Razor PanelComponent that fetches and displays a Sandbox.Services leaderboard derived from a stat name. Produces TWO files: {name}.razor and {name}.razor.scss. The panel auto-refreshes every 30 s, shows rank/displayName/value rows, handles loading state, and includes a BuildHash() override (razor-lint clean). Must be hosted under a ScreenPanel or WorldPanel. Stats must be configured for the project ident on sbox.game. Uses Leaderboards.Get(statName) + board.Refresh() -- the exact API from ServicesQueryHandler.", {
+    server.tool("create_leaderboard_panel", "Generate a Razor PanelComponent that fetches and displays a Sandbox.Services leaderboard derived from a stat name. Produces TWO files: {name}.razor and {name}.razor.scss. The panel auto-refreshes every 30 s, shows rank/displayName/value rows, handles loading state, and includes a BuildHash() override (razor-lint clean). Must be hosted under a ScreenPanel or WorldPanel. Stats must be configured for the project ident on sbox.game. Uses Leaderboards.Get(statName) + board.Refresh() -- the exact API from ServicesQueryHandler. Returns { created, razorPath, scssPath, className, note }. Follow with trigger_hotload, then get_compile_errors, then host it via add_screen_panel (panelComponent=className).", {
         name: z.string().optional().describe("Class name for the panel component. Defaults to 'LeaderboardPanel'"),
         directory: z.string().optional().describe("Subdirectory for the generated files. Defaults to 'Code/UI'"),
         statName: z.string().optional().describe("Sandbox.Services stat name the leaderboard is derived from. Defaults to 'score'"),
@@ -407,7 +407,7 @@ export function registerGameplayTools(server, bridge) {
         return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
     });
     // -- create_stat_modifier_system ---------------------------------------
-    server.tool("create_stat_modifier_system", "Generate an enum-keyed stat modifier system with three modifier layers: SET (highest-priority-wins hard override), ADD (summed bonuses), MULT (multiplied factors applied last). Modifier storage uses parallel private Lists of primitive types (serialization-safe). RemoveModifiersFrom(source) cleans up all mods from a buff/debuff source by reference. Static OnStatChanged(stat, value) event fires after every add/remove. Mined from RPG/buff/debuff patterns across shipped s&box games.", {
+    server.tool("create_stat_modifier_system", "Generate an enum-keyed stat modifier system with three modifier layers: SET (highest-priority-wins hard override), ADD (summed bonuses), MULT (multiplied factors applied last). Modifier storage uses parallel private Lists of primitive types (serialization-safe). RemoveModifiersFrom(source) cleans up all mods from a buff/debuff source by reference. Static OnStatChanged(stat, value) event fires after every add/remove. Mined from RPG/buff/debuff patterns across shipped s&box games. Returns { created, path, className, stats, placedOn, note } — stats echoes the sanitized stat names ({name}Stat enum values); placedOn is the target GameObject when attached (needs the type hotloaded). Follow with trigger_hotload, then get_compile_errors.", {
         name: z.string().optional().describe("Class name prefix -- generates {name}Stat enum + {name} Component. Defaults to 'StatSystem'"),
         directory: z.string().optional().describe("Subdirectory for the .cs file. Defaults to 'Code'"),
         stats: z.union([z.array(z.string()), z.string()]).optional().describe("Stat names as a JSON array or comma-separated string. Defaults to 'Health,Speed,Damage'"),

package/dist/tools/gameplayrecorder.d.ts

@@ -0,0 +1,18 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Gameplay Recording family — record live PLAY-MODE gameplay to a .movie clip
+ * via Sandbox.MovieMaker.MovieRecorder (shipped in the current editor build,
+ * verified live 2026-07-12; closes engine-watch #2 in docs/TOOL_BACKLOG.md):
+ *
+ *   - record_gameplay_clip       start an async frame-loop recording job
+ *   - stop_gameplay_recording    stop → persist as a project .movie asset
+ *   - gameplay_recording_status  poll the job
+ *
+ * The counterpart to the MovieMaker playback family (list_movies /
+ * add_movie_player / play_movie / stop_movie): those play clips, this CREATES
+ * them from live gameplay. None of the three are scene-mutating — they must
+ * stay callable during play mode, where recording lives.
+ */
+export declare function registerGameplayRecorderTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=gameplayrecorder.d.ts.map