sbox-mcp-server 1.20.0 → 2.1.0

package/dist/index.js

@@ -59,6 +59,19 @@ import { registerInteractionPackTools } from "./tools/interactionpack.js";
 import { registerLootEconomyTools } from "./tools/looteconomy.js";
 import { registerUiFeedbackTools } from "./tools/uifeedback.js";
 import { registerCinematicsTools } from "./tools/cinematics.js";
+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. */
@@ -78,68 +91,68 @@ if (args.includes("--version") || args.includes("-v")) {
     process.exit(0);
 }
 if (args.includes("--help") || args.includes("-h")) {
-    console.log(`sbox-mcp ${getVersion()} — MCP Server for s&box game engine
-
-USAGE
-  node dist/index.js              Start the MCP server (stdio transport)
-  node dist/index.js --help       Show this help
-  node dist/index.js --version    Show version
-
-ENVIRONMENT VARIABLES
-  SBOX_BRIDGE_IPC_DIR   IPC directory — MUST match the s&box addon's dir.
-                        Default: <os tmpdir>/sbox-bridge-ipc
-  SBOX_BRIDGE_HOST      Legacy/cosmetic — shown in get_bridge_status only
-  SBOX_BRIDGE_PORT      Legacy/cosmetic — shown in get_bridge_status only
-
-CONNECT TO CLAUDE CODE
-  claude mcp add sbox -- node /path/to/sbox-mcp-server/dist/index.js
-
-TOOLS (150 total / 142 s&box-editor handlers — +16 in v1.5.0)
-  Project:     get_project_info, list_project_files, read_file, write_file
-  Scripts:     create_script, edit_script, delete_script, trigger_hotload
-  Scenes:      list_scenes, load_scene, save_scene, create_scene
-  GameObjects: create/delete/duplicate/rename_gameobject, set_parent/enabled/transform
-  Components:  get/set_property, get_all_properties, list_available_components, add_component_with_properties, set_prefab_ref
-  Hierarchy:   get_scene_hierarchy (with maxDepth + rootId), get_selected_objects, select_object, focus_object
-  Assets:      search_assets, list_asset_library, install_asset, get_asset_info
-  Materials:   assign_model, create_material, assign_material, set_material_property
-  Audio:       list_sounds, create_sound_event, assign_sound, play_sound_preview
-  Play Mode:   start_play, stop_play, is_playing
-  Runtime:     get/set_runtime_property, take_screenshot
-  Editor:      undo, redo
-  Prefabs:     create_prefab, instantiate_prefab, list_prefabs, get_prefab_info
-  Physics:     add_physics, add_collider, add_joint, raycast
-  UI:          create_razor_ui, add_screen_panel, add_world_panel
-  Templates:   create_player_controller, create_npc_controller, create_game_manager, create_trigger_zone
-  Networking:  add_network_helper, configure_network, get_network_status, network_spawn, set_ownership
-  Net Scripts: add_sync_property, add_rpc_method, create_networked_player, create_lobby_manager, create_network_events
-  Publishing:  get_project_config, set_project_config, validate_project, set_project_thumbnail, get_package_details
-  World Gen:   invoke_button, list_component_buttons, raycast_terrain, build_terrain_mesh
-  Map Edit:    add_terrain_hill/clearing/trail, clear_terrain_features, sculpt_terrain
-  Caves:       add_cave_waypoint, clear_cave_path
-  Forest:      add_forest_poi/trail, set_forest_seed, clear_forest_pois, paint_forest_density
-  Placement:   place_along_path
-  Discovery:   describe_type, search_types, get_method_signature, find_in_project
-  Status:      get_bridge_status
-
-  ── New in v1.4.0 ───────────────────────────────────
-  Visual:      add_light, set_fog, add_post_process, set_skybox, add_envmap_probe, apply_atmosphere, apply_post_fx_look
-  Characters:  spawn_model, spawn_citizen, dress_citizen, set_bodygroup, pose_citizen, equip_model, set_look_at, add_ragdoll, set_expression
-  Scene:       snap_to_ground, align_objects, distribute_objects, grid_duplicate, measure_distance
-  Environment: scatter_props, randomize_transforms, group_objects
-  Utilities:   find_objects, set_tint, replace_model, set_tags
-  VFX (exp):   spawn_particle, create_particle_effect, add_trail, add_beam
-
-  ── New in v1.5.0 ───────────────────────────────────
-  Diagnostics: read_log, get_compile_errors  (MCP-server-side — work even if the editor crashed)
-  Camera:      screenshot_from (AIM a shot at an object/point — take_screenshot is fixed to the Main Camera), frame_camera
-  Navigation:  bake_navmesh, get_navmesh_path
-  Spatial:     physics_overlap (volume counterpart to raycast)
-  Reflections: bake_reflections
-  Particles:   spawn_vpcf (compiled .vpcf via LegacyParticleSystem — the supported particle path)
-  Console/Exec: console_run, execute_csharp (experimental)
-  Object utils: remove_component, get_tags
-  Docs search: search_docs, get_doc_page, list_doc_categories  (MCP-server-side — official Facepunch/sbox-docs)
+    console.log(`sbox-mcp ${getVersion()} — MCP Server for s&box game engine
+
+USAGE
+  node dist/index.js              Start the MCP server (stdio transport)
+  node dist/index.js --help       Show this help
+  node dist/index.js --version    Show version
+
+ENVIRONMENT VARIABLES
+  SBOX_BRIDGE_IPC_DIR   IPC directory — MUST match the s&box addon's dir.
+                        Default: <os tmpdir>/sbox-bridge-ipc
+  SBOX_BRIDGE_HOST      Legacy/cosmetic — shown in get_bridge_status only
+  SBOX_BRIDGE_PORT      Legacy/cosmetic — shown in get_bridge_status only
+
+CONNECT TO CLAUDE CODE
+  claude mcp add sbox -- node /path/to/sbox-mcp-server/dist/index.js
+
+TOOLS (245 total / 237 editor handlers · v2: the native editor MCP server at http://127.0.0.1:7269/mcp is the primary path — this stdio server is the full-surface fallback; --lifeline exposes just the editor-down diagnostics)
+  Project:     get_project_info, list_project_files, read_file, write_file
+  Scripts:     create_script, edit_script, delete_script, trigger_hotload
+  Scenes:      list_scenes, load_scene, save_scene, create_scene
+  GameObjects: create/delete/duplicate/rename_gameobject, set_parent/enabled/transform
+  Components:  get/set_property, get_all_properties, list_available_components, add_component_with_properties, set_prefab_ref
+  Hierarchy:   get_scene_hierarchy (with maxDepth + rootId), get_selected_objects, select_object, focus_object
+  Assets:      search_assets, list_asset_library, install_asset, get_asset_info
+  Materials:   assign_model, create_material, assign_material, set_material_property
+  Audio:       list_sounds, create_sound_event, assign_sound, play_sound_preview
+  Play Mode:   start_play, stop_play, is_playing
+  Runtime:     get/set_runtime_property, take_screenshot
+  Editor:      undo, redo
+  Prefabs:     create_prefab, instantiate_prefab, list_prefabs, get_prefab_info
+  Physics:     add_physics, add_collider, add_joint, raycast
+  UI:          create_razor_ui, add_screen_panel, add_world_panel
+  Templates:   create_player_controller, create_npc_controller, create_game_manager, create_trigger_zone
+  Networking:  add_network_helper, configure_network, get_network_status, network_spawn, set_ownership
+  Net Scripts: add_sync_property, add_rpc_method, create_networked_player, create_lobby_manager, create_network_events
+  Publishing:  get_project_config, set_project_config, validate_project, set_project_thumbnail, get_package_details
+  World Gen:   invoke_button, list_component_buttons, raycast_terrain, build_terrain_mesh
+  Map Edit:    add_terrain_hill/clearing/trail, clear_terrain_features, sculpt_terrain
+  Caves:       add_cave_waypoint, clear_cave_path
+  Forest:      add_forest_poi/trail, set_forest_seed, clear_forest_pois, paint_forest_density
+  Placement:   place_along_path
+  Discovery:   describe_type, search_types, get_method_signature, find_in_project
+  Status:      get_bridge_status
+
+  ── New in v1.4.0 ───────────────────────────────────
+  Visual:      add_light, set_fog, add_post_process, set_skybox, add_envmap_probe, apply_atmosphere, apply_post_fx_look
+  Characters:  spawn_model, spawn_citizen, dress_citizen, set_bodygroup, pose_citizen, equip_model, set_look_at, add_ragdoll, set_expression
+  Scene:       snap_to_ground, align_objects, distribute_objects, grid_duplicate, measure_distance
+  Environment: scatter_props, randomize_transforms, group_objects
+  Utilities:   find_objects, set_tint, replace_model, set_tags
+  VFX (exp):   spawn_particle, create_particle_effect, add_trail, add_beam
+
+  ── New in v1.5.0 ───────────────────────────────────
+  Diagnostics: read_log, get_compile_errors  (MCP-server-side — work even if the editor crashed)
+  Camera:      screenshot_from (AIM a shot at an object/point — take_screenshot is fixed to the Main Camera), frame_camera
+  Navigation:  bake_navmesh, get_navmesh_path
+  Spatial:     physics_overlap (volume counterpart to raycast)
+  Reflections: bake_reflections
+  Particles:   spawn_vpcf (compiled .vpcf via LegacyParticleSystem — the supported particle path)
+  Console/Exec: console_run, execute_csharp (experimental)
+  Object utils: remove_component, get_tags
+  Docs search: search_docs, get_doc_page, list_doc_categories  (MCP-server-side — official Facepunch/sbox-docs)
 `);
     process.exit(0);
 }
@@ -152,30 +165,47 @@ const server = new McpServer({
     // server (the way other MCP servers like Supabase / TurboTax do). Use it to
     // tell Claude how to work effectively with the bridge — the disciplines that
     // are easy to skip without a reminder.
-    instructions: `You are working with the s&box Claude Bridge — a file-based IPC bridge into the s&box game engine editor.
-
-To get good results:
-
-1. Always call \`mcp__sbox__get_bridge_status\` first to confirm the bridge addon is connected and s&box is running. If ping responds but other tools time out, the editor side isn't processing requests.
-
-2. For visual changes (models, positions, animations, UI panels, lighting), call \`mcp__sbox__take_screenshot\` after the change and READ THE PNG yourself. You're a multimodal model — you can see the result. Guessing about visual outcomes from code alone produces long iteration loops. The screenshot tool saves to <sbox-install>/screenshots/sbox.<timestamp>.png — list the newest file and read it.
-
-3. Before writing code that touches an unfamiliar s&box type, call \`mcp__sbox__describe_type\` or \`mcp__sbox__search_types\`. s&box's API changes between SDK versions — reflection is the source of truth, not training data.
-
-4. \`get_scene_hierarchy\` honors \`maxDepth\` (default 10) and accepts optional \`rootId\` to traverse from a specific GameObject. Use these to avoid dumping the entire scene into a tool result.
-
-5. Scene-mutating tools (create_gameobject, set_property, etc.) refuse during play mode and return a clear error. Stop play before making scene edits.
-
-6. First session with the bridge (or when the user asks "how do I start?" / "what can this do?")? Offer to run setup — invoke the \`sbox-setup\` skill: it verifies the connection, detects the user's installed libraries (\`list_libraries\`), recommends a first move, and points to help + feedback.
-
-If you're running inside Claude Code, install the companion plugin for the full workflow:
-    /plugin marketplace add LouSputthole/Sbox-Claude
-    /plugin install sbox-claude
-
+    instructions: `You are working with the s&box Claude Bridge — a file-based IPC bridge into the s&box game engine editor.
+
+To get good results:
+
+1. Always call \`mcp__sbox__get_bridge_status\` first to confirm the bridge addon is connected and s&box is running. If ping responds but other tools time out, the editor side isn't processing requests.
+
+2. For visual changes (models, positions, animations, UI panels, lighting), call \`mcp__sbox__take_screenshot\` after the change and READ THE PNG yourself. You're a multimodal model — you can see the result. Guessing about visual outcomes from code alone produces long iteration loops. The screenshot tool saves to <sbox-install>/screenshots/sbox.<timestamp>.png — list the newest file and read it.
+
+3. Before writing code that touches an unfamiliar s&box type, call \`mcp__sbox__describe_type\` or \`mcp__sbox__search_types\`. s&box's API changes between SDK versions — reflection is the source of truth, not training data.
+
+4. \`get_scene_hierarchy\` honors \`maxDepth\` (default 10) and accepts optional \`rootId\` to traverse from a specific GameObject. Use these to avoid dumping the entire scene into a tool result.
+
+5. Scene-mutating tools (create_gameobject, set_property, etc.) refuse during play mode and return a clear error. Stop play before making scene edits.
+
+6. First session with the bridge (or when the user asks "how do I start?" / "what can this do?")? Offer to run setup — invoke the \`sbox-setup\` skill: it verifies the connection, detects the user's installed libraries (\`list_libraries\`), recommends a first move, and points to help + feedback.
+
+If you're running inside Claude Code, install the companion plugin for the full workflow:
+    /plugin marketplace add LouSputthole/Sbox-Claude
+    /plugin install sbox-claude
+
 The plugin ships an \`sbox-build-feature\` skill that codifies the workflow above plus a list of common s&box gotchas (MathF not available in sandbox, Cloud assets ephemeral, head bone case-sensitive, CitizenAnimationHelper.IkRightHand works at runtime, etc.). Read its SKILL.md before starting non-trivial features.`,
 });
 // Bridge client talks to the s&box editor via file IPC. host/port are cosmetic.
 const bridge = new BridgeClient(process.env.SBOX_BRIDGE_HOST ?? "127.0.0.1", parseInt(process.env.SBOX_BRIDGE_PORT ?? "29015", 10));
+// ── Lifeline mode (v2 migration) ───────────────────────────────────
+// With the native editor MCP server carrying the full tool surface, this stdio
+// server's long-term job is "editor-down diagnostics": the native server dies
+// with the editor; these tools read the log / docs directly and don't. --lifeline
+// registers ONLY that set by filtering server.tool() — everything else is a no-op.
+const LIFELINE_TOOLS = new Set([
+    "read_log", "get_compile_errors", "search_docs", "get_doc_page",
+    "list_doc_categories", "run_self_test", "get_bridge_status",
+]);
+if (args.includes("--lifeline")) {
+    const realTool = server.tool.bind(server);
+    server.tool = (...toolArgs) => {
+        if (LIFELINE_TOOLS.has(toolArgs[0]))
+            return realTool(...toolArgs);
+        return undefined;
+    };
+}
 // Register all tools
 registerProjectTools(server, bridge);
 registerScriptTools(server, bridge);
@@ -221,6 +251,19 @@ registerInteractionPackTools(server, bridge);
 registerLootEconomyTools(server, bridge);
 registerUiFeedbackTools(server, bridge);
 registerCinematicsTools(server, bridge);
+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/assets.js

@@ -28,19 +28,19 @@ export function registerAssetTools(server, bridge) {
         };
     });
     // ── list_asset_library ───────────────────────────────────────────
-    server.tool("list_asset_library", "Browse the s&box community asset library. Search for packages by name, description, or type to find models, maps, and tools to install", {
+    server.tool("list_asset_library", "List assets visible to the editor's AssetSystem — project assets plus mounted engine/installed-package content (it does NOT query the remote sbox.game library; use install_asset to pull in new packages). Returns { count, assets:[{ name, path, relativePath, assetType }] } — pass a returned path to spawn_model, assign_model, or get_asset_info", {
         query: z
             .string()
             .optional()
-            .describe("Search term for packages"),
+            .describe("Search term, case-insensitive substring match against asset NAMES"),
         type: z
             .string()
             .optional()
-            .describe("Package type filter (e.g. 'model', 'map', 'library')"),
+            .describe("Asset type filter, substring-matched against the asset's type (e.g. 'model', 'material', 'sound')"),
         maxResults: z
             .number()
             .optional()
-            .describe("Maximum results. Defaults to 25"),
+            .describe("Maximum results. Defaults to 200"),
     }, async (params) => {
         const res = await bridge.send("list_asset_library", params);
         if (!res.success) {
@@ -51,7 +51,7 @@ export function registerAssetTools(server, bridge) {
         };
     });
     // ── install_asset ────────────────────────────────────────────────
-    server.tool("install_asset", "Install a community asset package into the project by its ident (e.g. 'facepunch.flatgrass'). Adds it as a project dependency", {
+    server.tool("install_asset", "Install a community asset package into the project by its ident (e.g. 'facepunch.flatgrass'). Adds it as a project dependency. Returns { installed, ident, name, path, relativePath, restartRecommended, note } — pass the returned path to spawn_model / assign_model. CAUTION: if the package is a code LIBRARY (adds a PackageReference), trigger_hotload will NOT surface its types — call restart_editor so the new package compiles into the project", {
         ident: z
             .string()
             .describe("Package identifier (e.g. 'facepunch.flatgrass', 'author.package_name')"),

package/dist/tools/audio.js

@@ -5,15 +5,15 @@ import { z } from "zod";
  */
 export function registerAudioTools(server, bridge) {
     // ── list_sounds ──────────────────────────────────────────────────
-    server.tool("list_sounds", "List available sound assets in the project and installed packages. Filter by name", {
+    server.tool("list_sounds", "List the project's .sound event files (recursive scan of the project root for *.sound). Returns { count, sounds } — project-relative paths ready to pass to assign_sound, play_sound_preview, or add_lipsync. NOTE: the current handler returns every match (filter/maxResults are not applied) and only covers .sound files in the project tree — use search_assets type='sound' for other sound assets", {
         filter: z
             .string()
             .optional()
-            .describe("Search filter for sound name or path"),
+            .describe("Search filter for sound name or path (currently not applied by the handler — all .sound files are returned)"),
         maxResults: z
             .number()
             .optional()
-            .describe("Maximum results. Defaults to 50"),
+            .describe("Maximum results. Defaults to 50 (currently not applied by the handler)"),
     }, async (params) => {
         const res = await bridge.send("list_sounds", params);
         if (!res.success) {
@@ -24,13 +24,14 @@ export function registerAudioTools(server, bridge) {
         };
     });
     // ── create_sound_event ───────────────────────────────────────────
-    server.tool("create_sound_event", "Create a new sound event file (.sound) with volume, pitch, distance falloff, and looping settings", {
+    server.tool("create_sound_event", "Create a .sound event file wired to a source .vsnd. Returns { created, path, soundReferenced, note } (path is project-relative); errors if the file already exists. Preview the result with play_sound_preview or attach it to an object with assign_sound. Note: .sound events have no loop flag — looping lives on the SoundPointComponent that plays the event", {
         path: z
             .string()
-            .describe("Path for the sound event file (e.g. 'sounds/footstep.sound')"),
+            .describe("Project-relative path for the sound event file (e.g. 'sounds/footstep.sound'; '.sound' appended if missing)"),
         sound: z
             .string()
-            .describe("Path to the source sound asset (.vsnd)"),
+            .optional()
+            .describe("Path to the source sound asset (.vsnd) the event plays. Omit to create an empty event and wire it later"),
         volume: z
             .number()
             .optional()
@@ -39,18 +40,10 @@ export function registerAudioTools(server, bridge) {
             .number()
             .optional()
             .describe("Pitch multiplier. Defaults to 1.0"),
-        minDistance: z
-            .number()
-            .optional()
-            .describe("Minimum distance before falloff starts (units). Defaults to 100"),
         maxDistance: z
             .number()
             .optional()
-            .describe("Maximum audible distance (units). Defaults to 2000"),
-        loop: z
-            .boolean()
-            .optional()
-            .describe("Whether the sound should loop. Defaults to false"),
+            .describe("Maximum audible distance in units (sets Distance + enables DistanceAttenuation). Omit for the engine default"),
     }, async (params) => {
         const res = await bridge.send("create_sound_event", params);
         if (!res.success) {
@@ -61,7 +54,7 @@ export function registerAudioTools(server, bridge) {
         };
     });
     // ── assign_sound ─────────────────────────────────────────────────
-    server.tool("assign_sound", "Attach a sound event to a GameObject via SoundPointComponent. Creates the component if needed", {
+    server.tool("assign_sound", "Attach a sound event to a GameObject via SoundPointComponent. Creates the component if needed. Returns { assigned, id, sound, soundLoaded, playOnStart } — soundLoaded:false means the .sound path did not resolve (the component is still added with no event; verify the path with list_sounds)", {
         id: z.string().describe("GUID of the GameObject"),
         sound: z
             .string()
@@ -69,7 +62,7 @@ export function registerAudioTools(server, bridge) {
         playOnStart: z
             .boolean()
             .optional()
-            .describe("Whether the sound plays automatically when the game starts"),
+            .describe("If true, the handler calls StartSound() immediately, so the sound starts playing right away (audible in the editor)"),
     }, async (params) => {
         const res = await bridge.send("assign_sound", params);
         if (!res.success) {
@@ -80,14 +73,14 @@ export function registerAudioTools(server, bridge) {
         };
     });
     // ── play_sound_preview ───────────────────────────────────────────
-    server.tool("play_sound_preview", "Play a sound in the editor for testing without entering play mode", {
+    server.tool("play_sound_preview", "Play a sound in the editor for testing without entering play mode. Returns { playing, sound, volume }. Fire-and-forget via Sound.Play — there is no stop control, and the volume param is echoed back but not currently applied to playback", {
         sound: z
             .string()
             .describe("Sound event or asset path to preview"),
         volume: z
             .number()
             .optional()
-            .describe("Preview volume (0-1). Defaults to 1.0"),
+            .describe("Preview volume (0-1). Defaults to 1.0 (echoed in the response but not currently applied to playback)"),
     }, async (params) => {
         const res = await bridge.send("play_sound_preview", params);
         if (!res.success) {

package/dist/tools/audit.d.ts

@@ -0,0 +1,8 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BridgeClient } from "../transport/bridge-client.js";
+/**
+ * Project audit & batch operation tools (v2 relaunch wave 1, Batch 51):
+ * find_broken_references, batch_set_property, describe_project.
+ */
+export declare function registerAuditTools(server: McpServer, bridge: BridgeClient): void;
+//# sourceMappingURL=audit.d.ts.map