sbox-mcp-server 2.0.0 → 2.1.0

package/dist/index.js

@@ -63,6 +63,15 @@ import { registerAuditTools } from "./tools/audit.js";
 import { registerBatchTools } from "./tools/batch.js";
 import { registerWorkflowTools } from "./tools/workflow.js";
 import { registerVehicleTools } from "./tools/vehicles.js";
+import { registerEconomySaveTools } from "./tools/economysave.js";
+import { registerStatsAchievementsTools } from "./tools/statsachievements.js";
+import { registerRoundUiTools } from "./tools/roundui.js";
+import { registerWorldRenderTools } from "./tools/worldrender.js";
+import { registerAiSystemsTools } from "./tools/aisystems.js";
+import { registerGameplayRecorderTools } from "./tools/gameplayrecorder.js";
+import { registerDialogueFxTools } from "./tools/dialoguefx.js";
+import { registerMovieAuthoringTools } from "./tools/movieauthoring.js";
+import { registerCinematicRecordingTools } from "./tools/cinematicrecording.js";
 // ── CLI flags ──────────────────────────────────────────────────────
 const args = process.argv.slice(2);
 /** Read the package version from package.json, or return "unknown" on failure. */
@@ -246,6 +255,15 @@ registerAuditTools(server, bridge);
 registerBatchTools(server, bridge);
 registerWorkflowTools(server, bridge);
 registerVehicleTools(server, bridge);
+registerEconomySaveTools(server, bridge);
+registerStatsAchievementsTools(server, bridge);
+registerRoundUiTools(server, bridge);
+registerWorldRenderTools(server, bridge);
+registerAiSystemsTools(server, bridge);
+registerGameplayRecorderTools(server, bridge);
+registerDialogueFxTools(server, bridge);
+registerMovieAuthoringTools(server, bridge);
+registerCinematicRecordingTools(server, bridge);
 /** Start the MCP server on stdio and attempt initial Bridge connection. */
 async function main() {
     const transport = new StdioServerTransport();

package/dist/tools/aisystems.d.ts

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

package/dist/tools/aisystems.js

@@ -0,0 +1,236 @@
+import { z } from "zod";
+/**
+ * AI & Systems pack — five scaffold generators:
+ *
+ *   - create_needs_system      sim/tycoon needs engine (decay -> Happiness + events)
+ *   - create_utility_ai        scored-action brain (abstract Action base + brain + 2 examples)
+ *   - create_npc_schedule_brain daily-routine NPC bound to the day-night clock contract
+ *   - create_event_bus         typed LOCAL pub/sub static class (not a Component)
+ *   - add_tts_voice            TTS speaker over Sandbox.Speech.Synthesizer
+ *
+ * All write a .cs file into the project (scene/file-mutating; refused during play
+ * mode by the bridge dispatch). Every generated template was live-compile-verified
+ * (hotload + TypeLibrary-load) against the 2026-07 SDK on 2026-07-12.
+ *
+ * Mirrors the gamefeel.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 registerAiSystemsTools(server, bridge) {
+    // ── create_needs_system ───────────────────────────────────────────
+    server.tool("create_needs_system", "Generate a sim/tycoon needs engine component: a [Property] list of need definitions (name, decay rate/s, critical threshold, weight) with per-need 0..100 values that decay over Time.Delta, Satisfy(name, amount) to restore, an aggregate Happiness (weighted mean, [Sync(FromHost)] when networked), and static OnNeedCritical (edge-triggered: fires once crossing below threshold, re-arms above) + OnHappinessChanged (>0.25-point moves) events. Returns {created, path, className, needs[], propertyNames[], note}. Next: trigger_hotload, get_compile_errors, then attach via targetId re-call or add_component_with_properties; drive from game code (e.g. a create_interactable that calls Satisfy). Limits: per-need values live on the simulating machine only (host) — sync per-need UI yourself via RPCs; events fire on the simulating machine only; networked default true means a no-session solo playtest won't tick (everything is a proxy) — pass networked:false to iterate solo. Refused during play mode; refuses to overwrite an existing file.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class/file name. Defaults to 'NeedsSystem'. Sanitized to a valid C# identifier."),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory under the project root for the .cs file. Defaults to 'Code'."),
+        needs: z
+            .array(z.object({
+            name: z.string().describe("Need name, e.g. 'Hunger' (the key for Satisfy/GetNeed)."),
+            decayPerSecond: z.number().optional().describe("Points lost per second on the 0..100 scale. Defaults to 0.5."),
+            criticalThreshold: z.number().optional().describe("OnNeedCritical fires when the value falls below this. Defaults to 20."),
+            weight: z.number().optional().describe("Contribution to the Happiness weighted mean. Defaults to 1."),
+        }))
+            .optional()
+            .describe("Need definitions baked as inspector-editable defaults. Defaults to the classic sim trio: Hunger(0.8/s), Energy(0.5/s), Fun(0.3/s)."),
+        networked: z
+            .boolean()
+            .optional()
+            .describe("true (default): host-authoritative (IsProxy guard) + [Sync(FromHost)] Happiness — needs a host session. false: local build that ticks in a solo playtest."),
+        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("create_needs_system", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── create_utility_ai ─────────────────────────────────────────────
+    server.tool("create_utility_ai", "Generate a utility-AI (scored-action) brain: one file with an abstract {name}Action : Component base (Score() 0..1 + Begin/Tick/End lifecycle), a sealed {name}Brain that every EvaluateInterval picks the highest-scoring sibling action (score × ScoreWeight, current action gets +HysteresisBonus so near-ties don't flip-flop), and two example actions — {name}IdleAction (constant fallback score) and {name}WanderAction (desire builds while idle, walks to random points by direct transform movement, no navmesh). How it differs from create_npc_brain: the FSM has a FIXED transition table; here behavior EMERGES from per-frame scores — add behaviors by subclassing the base on the same GameObject, no transition wiring. Returns {created, path, classNames[4], propertyNames[], note}. Next: trigger_hotload + get_compile_errors, attach the brain AND example actions to one GameObject (targetId attaches only the brain), verify in play mode via get_runtime_property CurrentActionName. Limits: networked default true = host-authoritative (won't tick in a no-session solo playtest — use networked:false); actions Tick on the simulating machine only. Refused during play mode; refuses to overwrite an existing file.", {
+        name: z
+            .string()
+            .optional()
+            .describe("System prefix — generates {name}Action / {name}Brain / {name}IdleAction / {name}WanderAction in {name}Ai.cs. Defaults to 'Utility'. Sanitized to a valid C# identifier."),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory under the project root for the .cs file. Defaults to 'Code'."),
+        evaluateInterval: z
+            .number()
+            .optional()
+            .describe("Seconds between score evaluations (the active action still Ticks every frame). Defaults to 0.25."),
+        hysteresisBonus: z
+            .number()
+            .optional()
+            .describe("Score bonus the current action gets during evaluation — stickiness that prevents flip-flopping between near-tied actions. Defaults to 0.15."),
+        moveSpeed: z
+            .number()
+            .optional()
+            .describe("Example WanderAction walk speed in world units/s. Defaults to 80."),
+        wanderRadius: z
+            .number()
+            .optional()
+            .describe("Example WanderAction roam radius around its start position. Defaults to 300."),
+        networked: z
+            .boolean()
+            .optional()
+            .describe("true (default): host-authoritative brain (IsProxy guard) + [Sync(FromHost)] CurrentActionName. false: local build for solo iteration."),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of a GameObject to attach the BRAIN to (actions must be added separately; only attaches if the type is already in the TypeLibrary — hotload first)."),
+    }, async (params) => {
+        const res = await bridge.send("create_utility_ai", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── create_npc_schedule_brain ─────────────────────────────────────
+    server.tool("create_npc_schedule_brain", "Generate a daily-routine NPC brain: a [Property] list of schedule entries (startHour/endHour 0..24, taskName, target = named scene GameObject or fixed position), the hour read from any create_day_night_clock component (capability match: a float TimeOfDay property, same GameObject first then scene-wide) with an HONEST fallback to its own internal clock when none exists (check the generated UsingClockComponent bool), walking the NPC to the active entry's target and idling outside the schedule, plus a static OnTaskChanged(brain, taskName) event and [Sync(FromHost)] CurrentTask. Entries with endHour < startHour wrap past midnight. Returns {created, path, className, tasks[], propertyNames[], note}. Next: trigger_hotload + get_compile_errors, attach (targetId or add_component_with_properties), create the named target GameObjects (e.g. 'WorkSpot'), pair with create_day_night_clock for shared time, verify via get_runtime_property CurrentTask in play mode. Limits: default movement is a direct transform walk (walks through walls) — pass useNavMeshAgent:true for pathfinding (then bake_navmesh is REQUIRED); a clock with a different shape (e.g. 0..1 DayProgress) will NOT bind; networked default true won't tick in a no-session solo playtest (networked:false to iterate). Refused during play mode; refuses to overwrite an existing file.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class/file name. Defaults to 'NpcScheduleBrain'. Sanitized to a valid C# identifier."),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory under the project root for the .cs file. Defaults to 'Code'."),
+        schedule: z
+            .array(z.object({
+            startHour: z.number().describe("Entry start hour, 0..24 (inclusive)."),
+            endHour: z.number().describe("Entry end hour, 0..24 (exclusive). Smaller than startHour = wraps past midnight (e.g. 22 -> 6)."),
+            taskName: z.string().describe("Task label, e.g. 'Work' — surfaced via CurrentTask + OnTaskChanged."),
+            targetName: z.string().optional().describe("Named scene GameObject to walk to (case-insensitive; wins over targetPosition). Missing name = NPC idles."),
+            targetPosition: Vec3.optional().describe("Fixed world position to walk to, used when targetName is empty."),
+        }))
+            .optional()
+            .describe("Schedule entries baked as inspector-editable defaults. Defaults to Work 8-17 @ 'WorkSpot', Relax 17-22 @ 'HomeSpot' (idles/sleeps otherwise)."),
+        moveSpeed: z
+            .number()
+            .optional()
+            .describe("Walk speed in world units/s. Defaults to 100."),
+        arriveDistance: z
+            .number()
+            .optional()
+            .describe("Distance at which the NPC counts as arrived and idles at the spot. Defaults to 32."),
+        useNavMeshAgent: z
+            .boolean()
+            .optional()
+            .describe("true: move via NavMeshAgent.MoveTo (real pathfinding — REQUIRES bake_navmesh or the NPC won't move). Defaults to false (direct transform walk, no navmesh needed, walks through walls)."),
+        fallbackDayLengthSeconds: z
+            .number()
+            .optional()
+            .describe("Internal fallback clock only: real seconds per 24 in-game hours when NO TimeOfDay clock component exists. Defaults to 600."),
+        fallbackStartHour: z
+            .number()
+            .optional()
+            .describe("Internal fallback clock only: starting hour 0..24. Defaults to 8."),
+        networked: z
+            .boolean()
+            .optional()
+            .describe("true (default): host-authoritative (IsProxy guard) + [Sync(FromHost)] CurrentTask. false: local build for solo iteration."),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of the NPC GameObject to attach to (only attaches if the type is already in the TypeLibrary — hotload first)."),
+    }, async (params) => {
+        const res = await bridge.send("create_npc_schedule_brain", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── create_event_bus ──────────────────────────────────────────────
+    server.tool("create_event_bus", "Generate a typed LOCAL pub/sub event bus: a pure STATIC class (NOT a Component — nothing to place in the scene) with Subscribe<T>(owner, Action<T>), Unsubscribe(owner) (removes all of that owner's handlers across every event type), Publish<T>(evt) (synchronous, exact-type-T subscribers only, snapshot-iterated so handlers may subscribe/unsubscribe mid-publish), Count<T>() and Clear(), keyed by a plain Dictionary<Type, List<(object, Delegate)>> — plus a tiny example event record ({name}Ping). Decouples game systems: the quest system publishes 'EnemyDied', UI and achievements subscribe, neither knows the other. Returns {created, path, className, exampleEvent, api[], note}. Next: trigger_hotload + get_compile_errors, then Subscribe in components' OnStart and — REQUIRED — Unsubscribe(this) in OnDestroy: handler lists hold PLAIN references (no weak refs), so a component that never unsubscribes leaks itself for the scene's life; call Clear() on scene teardown. Limits: LOCAL only — Publish reaches the calling machine's subscribers, NOT other clients; for networked events pair with [Rpc.Broadcast]/[Rpc.Host] methods that Publish on arrival. No base-type dispatch (Publish<Base> won't reach Subscribe<Derived>). Refuses to overwrite an existing file; refused during play mode.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Static class/file name. Defaults to 'EventBus'. The example event record is named {name}Ping. Sanitized to a valid C# identifier."),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory under the project root for the .cs file. Defaults to 'Code'."),
+    }, async (params) => {
+        const res = await bridge.send("create_event_bus", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── add_tts_voice ─────────────────────────────────────────────────
+    server.tool("add_tts_voice", "Generate a text-to-speech speaker component over Sandbox.Speech.Synthesizer (the OS speech engine — dynamic NPC dialog with zero recorded VO): call <class>.Say(\"text\") from game code and it builds a Synthesizer (TrySetVoice by exact VoiceName, else gender/age hint, else OS default) -> WithText -> WithRate -> Play(), returning a tracked SoundHandle — positional 3D parented to the speaker (default) or flat 2D, with stop-previous-on-say interruption, IsSpeaking, StopSpeaking(), and LogVoices() to enumerate installed OS voices. Returns {created, path, className, propertyNames[], note}. Next: trigger_hotload + get_compile_errors, attach (targetId or add_component_with_properties), then Say from game code — LOCAL audio only, wrap the Say call in an [Rpc.Broadcast] handler for everyone to hear. Limits & honesty: the editor cannot playtest audio, so RUNTIME speech is UNVERIFIED (the API surface compiles — verify with your ears in play mode); voices are machine/OS-specific and TrySetVoice is best-effort; LIPSYNC IS NOT AUTO-WIRED — s&box's Sandbox.LipSync component consumes a BaseSoundComponent, not the raw SoundHandle TTS produces, and Synthesizer.OnVisemeReached's delegate arg types can't be confirmed via reflection; enableVisemeData:true enables Handle.LipSync.Visemes for your own mouth-drive code (runtime-unverified). Refuses to overwrite an existing file; refused during play mode.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class/file name. Defaults to 'TtsSpeaker'. Sanitized to a valid C# identifier."),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory under the project root for the .cs file. Defaults to 'Code'."),
+        voiceName: z
+            .string()
+            .optional()
+            .describe("Exact installed OS voice name (machine-specific — the generated LogVoices() lists them at runtime). Empty = use voiceGender/voiceAge, or the OS default."),
+        voiceGender: z
+            .string()
+            .optional()
+            .describe("Voice gender hint used only when voiceName is empty (e.g. 'Female', 'Male'). Must be paired with voiceAge. Passed through unvalidated."),
+        voiceAge: z
+            .string()
+            .optional()
+            .describe("Voice age hint paired with voiceGender (e.g. 'Adult', 'Child', 'Senior'). Passed through unvalidated."),
+        rate: z
+            .number()
+            .optional()
+            .describe("Speaking rate offset (integer): negative = slower, positive = faster. Defaults to 0 (normal)."),
+        volume: z
+            .number()
+            .optional()
+            .describe("Playback volume for spoken lines. Defaults to 1."),
+        positional: z
+            .boolean()
+            .optional()
+            .describe("true (default): 3D sound parented to the speaker GameObject (follows it). false: flat 2D voice on the listener (narrator/UI style)."),
+        stopPreviousOnSay: z
+            .boolean()
+            .optional()
+            .describe("true (default): a new Say() fades out the still-playing previous line. false: lines overlap."),
+        stopFadeSeconds: z
+            .number()
+            .optional()
+            .describe("Fade-out duration used when interrupting/stopping a line. Defaults to 0.1."),
+        enableVisemeData: z
+            .boolean()
+            .optional()
+            .describe("true: sets Handle.LipSync.Enabled on each played line so custom mouth-drive code can read Handle.LipSync.Visemes. Runtime behavior unverified (editor can't playtest audio). Defaults to false."),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of the speaker GameObject to attach to (only attaches if the type is already in the TypeLibrary — hotload first)."),
+    }, async (params) => {
+        const res = await bridge.send("add_tts_voice", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+}
+//# sourceMappingURL=aisystems.js.map

package/dist/tools/cinematicrecording.d.ts

@@ -0,0 +1,31 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Cinematic Recording pair — scripted-run capture + killcam scaffold:
+ *
+ *   - record_playtest   one call = scripted playtest + gameplay recording of the
+ *                       SAME run. Composition of the playtest harness and the
+ *                       Batch 60 MovieRecorder stack: automated regression
+ *                       footage — a failing playtest comes with a replayable
+ *                       clip of exactly what happened.
+ *   - create_killcam    codegen scaffold (sealed Component): rolling-buffer
+ *                       recording + on-death replay via MoviePlayer + a
+ *                       chase-camera takeover of Scene.Camera.
+ *
+ * Live-verified (2026-07-13, Gravehold editor): sandboxed GAME code can
+ * construct + drive MovieRecorder/MoviePlayer at runtime, and
+ * MovieRecorderOptions.BufferDuration is a true rolling buffer — ~8.7s of
+ * recording with a 3s buffer compiled to a clip with Duration exactly 3.00s,
+ * re-based to start at 0. The official recording-api doc
+ * (Facepunch/sbox-docs docs/movie-maker/recording-api.md) confirms game-code
+ * recording is the supported use case and documents
+ * MovieRecorderOptions.Default (a static, invisible to describe_type) +
+ * record `with` syntax — the whole-scene idiom create_killcam's
+ * RecordWholeScene mode generates.
+ *
+ * record_playtest is NOT scene-mutating (it only exists in play mode — the
+ * Batch 60 recording precedent). create_killcam IS scene-mutating (writes a
+ * .cs scaffold to disk, like every create_* scaffold).
+ */
+export declare function registerCinematicRecordingTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=cinematicrecording.d.ts.map

package/dist/tools/cinematicrecording.js

@@ -0,0 +1,107 @@
+import { z } from "zod";
+/**
+ * Cinematic Recording pair — scripted-run capture + killcam scaffold:
+ *
+ *   - record_playtest   one call = scripted playtest + gameplay recording of the
+ *                       SAME run. Composition of the playtest harness and the
+ *                       Batch 60 MovieRecorder stack: automated regression
+ *                       footage — a failing playtest comes with a replayable
+ *                       clip of exactly what happened.
+ *   - create_killcam    codegen scaffold (sealed Component): rolling-buffer
+ *                       recording + on-death replay via MoviePlayer + a
+ *                       chase-camera takeover of Scene.Camera.
+ *
+ * Live-verified (2026-07-13, Gravehold editor): sandboxed GAME code can
+ * construct + drive MovieRecorder/MoviePlayer at runtime, and
+ * MovieRecorderOptions.BufferDuration is a true rolling buffer — ~8.7s of
+ * recording with a 3s buffer compiled to a clip with Duration exactly 3.00s,
+ * re-based to start at 0. The official recording-api doc
+ * (Facepunch/sbox-docs docs/movie-maker/recording-api.md) confirms game-code
+ * recording is the supported use case and documents
+ * MovieRecorderOptions.Default (a static, invisible to describe_type) +
+ * record `with` syntax — the whole-scene idiom create_killcam's
+ * RecordWholeScene mode generates.
+ *
+ * record_playtest is NOT scene-mutating (it only exists in play mode — the
+ * Batch 60 recording precedent). create_killcam IS scene-mutating (writes a
+ * .cs scaffold to disk, like every create_* scaffold).
+ */
+export function registerCinematicRecordingTools(server, bridge) {
+    const reply = (res) => res.success
+        ? { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] }
+        : { content: [{ type: "text", text: `Error: ${res.error}` }] };
+    // ── record_playtest ───────────────────────────────────────────────
+    server.tool("record_playtest", [
+        "Run a scripted playtest AND record the same run to a .movie clip in ONE call — automated regression footage: a failing playtest comes with a replayable clip of exactly what happened. REQUIRES play mode (start_play first).",
+        "steps uses the EXACT playtest schema (one verb per step: move / look / lookDelta / action / jump / set / wait / capture / assert — see the playtest tool for the full verb reference). The recording defaults to the playtest's resolved player hierarchy; pass ids to record other objects, or nothing resolvable falls back to whole-scene capture (heavy).",
+        "Returns { started, steps, recordingJobId, capture, sampleRate, clipName, folder, recorderCapSeconds, note } immediately; both jobs run ASYNC in the editor frame loop and the clip AUTO-SAVES the moment the playtest finishes (a failing or aborted run still saves its footage; play mode ending early is also saved).",
+        "THE POLL CHAIN: 1) playtest_status until finished:true → the per-step pass/fail transcript. 2) gameplay_recording_status → the saved clip summary { saved, assetPath, durationSeconds, trackCount } (if it still says pendingSave, the save is a frame away — poll again; a save error there means name collision: call stop_gameplay_recording yourself with a new name).",
+        "Replay the footage with add_movie_player + play_movie. Errors if a playtest or gameplay recording is already active. Only one at a time.",
+    ].join("\n"), {
+        steps: z
+            .array(z.record(z.string(), z.any()))
+            .describe("Ordered playtest step objects — identical schema to the playtest tool (move/look/lookDelta/action/jump/set/wait/capture/assert). Runs top-to-bottom in the frame loop."),
+        id: z
+            .string()
+            .optional()
+            .describe("GUID of the player/controller GameObject the playtest drives. Omit to auto-resolve the first PlayerController."),
+        component: z
+            .string()
+            .optional()
+            .describe("Controller component type to target (e.g. 'PlayerController'). Omit to auto-detect."),
+        ids: z
+            .array(z.string())
+            .optional()
+            .describe("GameObject GUIDs to RECORD (from get_scene_hierarchy WHILE PLAYING). Omit to record the playtest's player hierarchy (the default and usually what you want)."),
+        sampleRate: z
+            .number()
+            .int()
+            .optional()
+            .describe("Recording samples per second (default 30, clamped 1-120)"),
+        clipName: z
+            .string()
+            .optional()
+            .describe("Saved .movie asset name without extension (default playtest_<UTC timestamp>; sanitized to [A-Za-z0-9_-])"),
+        folder: z
+            .string()
+            .optional()
+            .describe('Assets subfolder to save the clip into (default "recordings")'),
+    }, async (params) => reply(await bridge.send("record_playtest", params)));
+    // ── create_killcam ────────────────────────────────────────────────
+    server.tool("create_killcam", [
+        "Generate a sealed killcam Component: a rolling-buffer MovieRecorder keeps ONLY the last MaxBufferSeconds of a target's gameplay (BufferDuration verified live: the compiled clip's Duration equals the buffer, re-based to 0), and TriggerReplay() plays that history back through a MoviePlayer while the main camera chase-follows the target (Scene.Camera takeover in OnPreRender, restored exactly afterwards; static OnReplayFinished event + IsReplaying flag).",
+        "Sandbox-safe: live-verified that GAME code can construct and drive MovieRecorder/MoviePlayer at runtime, and killcams/replays are the official recording-api use case — this is the real MovieMaker path, not a transform-history approximation. The replay REWINDS THE LIVE TARGET through its recorded past (classic killcam — the target is dead/inactive when it runs; disable a still-alive controller for the duration). wholeScene:true makes the generated component default to MovieRecorderOptions.Default (all renderers/cameras/sound points/particles — the replay rewinds everything, killer included; heavy in dense scenes), and it stays toggleable per-instance via the RecordWholeScene property.",
+        "Returns { created, path, className, bufferSeconds, sampleRate, cameraDistance, cameraHeight, nextSteps }. Then: trigger_hotload → attach to a MANAGER object → set_component_reference Target to the player → arm via WatchOnStart or StartWatching() from spawn code → call TriggerReplay() from death code (pairs with create_health_system). LOCAL/visual-only — wrap in an [Rpc.Broadcast] for all clients. Refuses if the file already exists.",
+    ].join("\n"), {
+        name: z
+            .string()
+            .optional()
+            .describe('Component class/file name (default "Killcam")'),
+        directory: z
+            .string()
+            .optional()
+            .describe('Project folder for the .cs file (default "Code")'),
+        bufferSeconds: z
+            .number()
+            .optional()
+            .describe("Rolling-buffer length in seconds — the replay shows at most this much history (default 10, clamped 2-120)"),
+        sampleRate: z
+            .number()
+            .int()
+            .optional()
+            .describe("Recorder samples per second (default 30, clamped 1-120)"),
+        cameraDistance: z
+            .number()
+            .optional()
+            .describe("Replay chase-camera distance behind the target (default 150, clamped 10-2000)"),
+        cameraHeight: z
+            .number()
+            .optional()
+            .describe("Replay chase-camera height above the target (default 60, clamped 0-2000)"),
+        wholeScene: z
+            .boolean()
+            .optional()
+            .describe("Generated default for RecordWholeScene: true = buffer the WHOLE scene via MovieRecorderOptions.Default (replay rewinds everything; heavy in dense scenes), false = only the Target hierarchy (default)"),
+    }, async (params) => reply(await bridge.send("create_killcam", params)));
+}
+//# sourceMappingURL=cinematicrecording.js.map

package/dist/tools/dialoguefx.d.ts

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

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/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