sbox-mcp-server 2.0.0 → 2.1.0

package/dist/tools/roundui.js

@@ -0,0 +1,88 @@
+import { z } from "zod";
+/**
+ * Round-flow & UI pack — three tools:
+ *
+ *   - create_round_timer_hud   Razor screen HUD showing round/phase time remaining;
+ *                              binds at runtime (TypeLibrary reflection) to whichever
+ *                              shipped round machine exists — no code coupling
+ *   - scaffold_map_vote_flow   end-of-round map vote: [Rpc.Host] ballots, [Sync]
+ *                              NetList tallies, countdown, deterministic tie-break,
+ *                              winner -> Scene.LoadFromFile, plus a Razor vote panel
+ *   - add_panel_buildhash      FILE-EDIT tool (not a scaffold): patches an existing
+ *                              .razor to add the BuildHash() override razor_lint
+ *                              flags as missing
+ *
+ * All are file-mutating (refused during play mode by the bridge dispatch). The
+ * Razor output is razor_lint-safe by construction (BuildHash override, no
+ * switch-expressions or non-ASCII in @code, class-selector SCSS roots), modeled
+ * on create_leaderboard_panel / the UI-feedback pack.
+ */
+export function registerRoundUiTools(server, bridge) {
+    // ── create_round_timer_hud ────────────────────────────────────────
+    server.tool("create_round_timer_hud", "Generate a Razor screen-panel HUD (.razor + .razor.scss) showing the active round/phase time remaining as mm:ss with the phase/state name above it. NO code coupling to your round machine: at runtime it discovers one by TypeLibrary property reflection — same-GameObject components first, then the whole scene, re-scanning every 2s while unbound — matching either shipped machine shape: create_round_phase_machine output (a [Sync] TimeUntil 'PhaseTimer' + 'CurrentPhase' enum for the label) or create_round_state_machine output (a manager with 'StateIndex' + 'Current', whose active state carries a [Sync] TimeUntil 'TimeLeft' + 'Identifier'). First matching component wins; any hand-written machine exposing those member names also binds. Adaptive BuildHash folds the WHOLE second remaining so the panel re-renders at 1 Hz, not every frame. Optional low-time warning: at/below lowTimeSeconds the clock gets the 'low' CSS class (red by default). Shows '--:--' (and fades out via the 'unbound' class) until a machine exists. Returns { created, razorPath, scssPath, className, lowTimeSeconds, note, nextSteps }. Renders NOTHING without a ScreenPanel host: follow with trigger_hotload, then add_screen_panel, then add_component_with_properties (component=className) on the same object; verify with capture_view (renderUI=true) in play mode.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated panel. Defaults to 'RoundTimerHud'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .razor + .razor.scss. Defaults to 'Code/UI'"),
+        lowTimeSeconds: z
+            .number()
+            .optional()
+            .describe("Remaining-seconds threshold at/below which the clock gets the 'low' warning class (clamped to >= 0; 0 disables). Editable per-instance via the LowTimeSeconds [Property]. Defaults to 10"),
+    }, async (params) => {
+        const res = await bridge.send("create_round_timer_hud", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── scaffold_map_vote_flow ────────────────────────────────────────
+    server.tool("scaffold_map_vote_flow", "Scaffold an end-of-round map vote. Three files: <Name>.cs (sealed host-authoritative controller) + <Name>Panel.razor + <Name>Panel.razor.scss (vote UI: one button per map, live tallies, countdown, own-pick highlight, winner banner). Flow: host calls StartVote() (usually from a post-round phase/state, or set the AutoStart [Property]) -> clients click -> votes route client-to-host via [Rpc.Host] SubmitVote with the caller re-resolved HOST-SIDE from Rpc.Caller (null-checked — Connection has no IsValid on this SDK) and the map index re-validated (re-votes overwrite, keyed by SteamId) -> tallies replicate via [Sync(FromHost)] NetList<int> -> when the [Sync] TimeUntil countdown expires the host picks the winner (most votes; ties break deterministically via one LCG scramble of a time seed — no System.Random) -> after resultLingerSeconds the HOST calls Scene.LoadFromFile(winner) (API verified live on this SDK; clients follow via the scene networking layer — verify the client hand-off in a real multi-client session). Static event OnVoteFinished(sceneFile) fires on every machine. Returns { created, componentPath, razorPath, scssPath, className, panelClassName, maps, voteDurationSeconds, resultLingerSeconds, autoStart, note, nextSteps }. REQUIREMENTS: the controller must sit on a NETWORK-SPAWNED object in multiplayer or [Sync] never replicates; if maps is omitted the MapScenes list is generated EMPTY and StartVote() refuses with a warning until you fill it in the inspector. Follow with trigger_hotload, attach via add_component_with_properties, host the panel under add_screen_panel.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the controller; the panel is generated as <Name>Panel. Defaults to 'MapVote'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs + .razor + .razor.scss. Defaults to 'Code'"),
+        maps: z
+            .array(z.string())
+            .optional()
+            .describe("Scene files to vote between, e.g. [\"scenes/arena.scene\", \"scenes/docks.scene\"] (find them with list_scenes). Baked into the MapScenes [Property] list, editable later in the inspector. Defaults to an EMPTY list (StartVote() then refuses until it's filled)"),
+        voteDurationSeconds: z
+            .number()
+            .optional()
+            .describe("Seconds the vote stays open once StartVote() is called (clamped to >= 3). Defaults to 20"),
+        resultLingerSeconds: z
+            .number()
+            .optional()
+            .describe("Seconds the winner banner shows before the host loads the winning scene (clamped to >= 0). Defaults to 4"),
+        autoStart: z
+            .boolean()
+            .optional()
+            .describe("Start the vote automatically on spawn (host only). Usually false — call StartVote() from your round machine's post-round state instead. Defaults to false"),
+    }, async (params) => {
+        const res = await bridge.send("scaffold_map_vote_flow", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── add_panel_buildhash ───────────────────────────────────────────
+    server.tool("add_panel_buildhash", "PATCH an existing .razor file (razor_lint's companion FIXER — razor_lint flags 'PanelComponent without BuildHash', this adds it). NOT a scaffold: it EDITS the file in place, inserting 'protected override int BuildHash() => System.HashCode.Combine( ... )' at the end of the first @code block, folding the fields and auto-properties declared there. HEURISTIC string/regex parsing — review the diff: computed (=>) properties, statics, consts, events and Action/Func members are skipped; reference-typed members fold by REFERENCE (a mutated List re-renders only if Count-style state is also folded); TimeSince/TimeUntil/RealTimeSince/RealTimeUntil members fold as whole seconds (1 Hz re-render, not every frame); braces inside @code string literals can confuse the block parser. If no members are found a '=> 0' stub with a TODO is inserted (silences the lint but does NOT re-render — replace it). Returns { patched, path, hashedMembers[], buildHash, note } on success, { alreadyPresent: true, path } when a BuildHash already exists (file left UNCHANGED — extend it by hand), or { error } for non-PanelComponent files, missing @code, or a path outside the project. Follow with trigger_hotload, then razor_lint to confirm the finding cleared.", {
+        path: z
+            .string()
+            .describe("Project-relative path to the .razor file to patch, e.g. 'Code/UI/MyHud.razor' (from razor_lint's finding.file or list_project_files). Must '@inherits PanelComponent'; .razor.scss files are rejected"),
+    }, async (params) => {
+        const res = await bridge.send("add_panel_buildhash", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+}
+//# sourceMappingURL=roundui.js.map

package/dist/tools/statsachievements.d.ts

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

package/dist/tools/statsachievements.js

@@ -0,0 +1,243 @@
+import { z } from "zod";
+/**
+ * Stats & Achievements pack — five scaffolds:
+ *
+ *   - add_leaderboard_stat        batched write-side stat reporter (Stats.Increment)
+ *   - create_achievement_set      achievement engine + unlock toast HUD (razor)
+ *   - add_achievement_trigger     trigger zone firing Progress/Unlock (creates a GO)
+ *   - create_speedrun_leaderboard timer + min-aggregation submit + friends-filter panel
+ *   - create_elo_rating_system    host-authoritative elo math + persisted ratings
+ *
+ * The write-side partners of create_leaderboard_panel (the read side). All are
+ * file/scene-mutating and refused during play mode by the bridge dispatch.
+ * Sandbox.Services APIs used by the generated code were verified live via
+ * describe_type (Stats.Increment/SetValue/Flush, Leaderboards.GetFromStat ->
+ * Board2.SetFriendsOnly/SetAggregationMin/SetSortAscending/Refresh(token)).
+ */
+// A 3D vector accepted as EITHER an object {x,y,z} OR a comma string "x,y,z".
+// The value is passed through to the bridge unchanged; the C# handler parses
+// both forms (C# is the source of truth for parsing).
+const Vector3Object = z.object({
+    x: z.number().describe("X coordinate"),
+    y: z.number().describe("Y coordinate"),
+    z: z.number().describe("Z coordinate"),
+});
+const Vector3Schema = z
+    .union([
+    Vector3Object,
+    z.string().describe('Comma string "x,y,z", e.g. "0,0,200"'),
+])
+    .describe('3D vector — object {x,y,z} OR comma string "x,y,z"');
+export function registerStatsAchievementsTools(server, bridge) {
+    // ── add_leaderboard_stat ──────────────────────────────────────────
+    server.tool("add_leaderboard_stat", "Generate a batched write-side stat reporter component for Sandbox.Services.Stats — the write partner of create_leaderboard_panel. Gameplay code calls the static <Name>.Report(\"kills\", 1) from anywhere; amounts accumulate locally and flush as Stats.Increment deltas on a timer (default every 12 s, also on disable/destroy). Baseline-delta bookkeeping means a partial flush retries the un-sent remainder instead of double-counting, and deltas larger than maxChunk are sent in chunks. Returns { created, path, className, placedOn, note, nextSteps }. Place ONE in the scene after trigger_hotload (add_component_to_new_object), or pass targetId to attach immediately when the type is already compiled. Stats are PER LOCAL PLAYER (each client reports its own) and only exist on leaderboards once the stat is registered for the project ident on sbox.game. Fails if the file already exists.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated component. Defaults to 'StatReporter'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        flushIntervalSeconds: z
+            .number()
+            .optional()
+            .describe("Seconds between batched flushes to the backend. Defaults to 12, clamped to >= 1"),
+        maxChunk: z
+            .number()
+            .optional()
+            .describe("Largest amount sent in a single Stats.Increment call; bigger deltas are chunked. Defaults to 1000, clamped to >= 1"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of a GameObject to attach to (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("add_leaderboard_stat", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── create_achievement_set ────────────────────────────────────────
+    server.tool("create_achievement_set", "Generate an achievement engine: a component with an AchievementDef list (id/title/description/target), per-achievement progress persisted via FileSystem.Data JSON (survives restarts), Progress(id, amount) / Unlock(id) API on a static Instance, a static OnAchievementUnlocked event, and an optional Stats.Increment mirror ('ach-<id>' += 1) on unlock. Also emits a Razor unlock-toast HUD (<Name>Toast.razor + .razor.scss, razor_lint clean) unless makeToast=false. Returns { created, path, className, toastRazorPath, toastScssPath, toastClassName, achievements, placedOn, note, nextSteps }. Ids are sanitized to [a-z0-9_-]; omitting achievements bakes 3 editable samples. After trigger_hotload: place ONE set in the scene, and host the toast under a ScreenPanel (add_screen_panel). Pair with add_achievement_trigger for world-trigger unlocks. LOCAL-only: achievements belong to each client's local player. Fails if the .cs or toast .razor already exists.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated engine component (toast panel becomes <name>Toast). Defaults to 'AchievementSet'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for all generated files. Defaults to 'Code'"),
+        achievements: z
+            .array(z.object({
+            id: z.string().describe("Stable id, sanitized to [a-z0-9_-] (used in the save file and the mirrored stat name)"),
+            title: z.string().describe("Display title shown in the toast"),
+            description: z.string().optional().describe("Short description shown in the toast"),
+            target: z.number().optional().describe("Progress value that unlocks it. Defaults to 1, clamped to >= 1"),
+        }))
+            .optional()
+            .describe("Achievement definitions baked into the component. Omit for 3 editable samples (first_steps, collector, veteran)"),
+        fileName: z
+            .string()
+            .optional()
+            .describe("Save file name inside FileSystem.Data. Defaults to 'achievements.json'"),
+        mirrorToStats: z
+            .boolean()
+            .optional()
+            .describe("Mirror each unlock into Sandbox.Services.Stats as 'ach-<id>' += 1. Defaults to true"),
+        makeToast: z
+            .boolean()
+            .optional()
+            .describe("Also emit the <name>Toast.razor + .razor.scss unlock toast HUD. Defaults to true"),
+        toastSeconds: z
+            .number()
+            .optional()
+            .describe("Seconds each unlock toast stays on screen. Defaults to 4, clamped to >= 0.5"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of a GameObject to attach the engine to (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_achievement_set", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── add_achievement_trigger ───────────────────────────────────────
+    server.tool("add_achievement_trigger", "SCENE-MUTATING: generate a data-driven achievement trigger-zone component AND create its GameObject now (named zone with a sized BoxCollider, IsTrigger=true, at the given position). When an object tagged triggerTag enters, the component calls <achievementSetClass>.Instance.Progress(achievementId, amount) — or Unlock() when unlock=true — with a once-only latch and optional destroy-after-fire. Returns { created, path, className, achievementSetClass, achievementId, gameObject, attached, note, nextSteps }. The generated component only attaches to the zone after trigger_hotload — until then `attached` is false and nextSteps carries the exact add_component_with_properties follow-up. The generated code references the set class BY NAME: run create_achievement_set first or the project will not compile (the result warns via `note`). Re-running with the same name fails unless reuseClass=true, which skips codegen and just places another zone (attaching + configuring immediately since the class is already compiled). Refused during play mode.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated trigger component. Defaults to 'AchievementTrigger'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        achievementSetClass: z
+            .string()
+            .optional()
+            .describe("Class name of the achievement set the zone reports to (from create_achievement_set). Defaults to 'AchievementSet'"),
+        achievementId: z
+            .string()
+            .describe("Id of the achievement to progress/unlock (sanitized to [a-z0-9_-])"),
+        amount: z
+            .number()
+            .optional()
+            .describe("Progress amount added per fire (ignored when unlock=true). Defaults to 1"),
+        unlock: z
+            .boolean()
+            .optional()
+            .describe("Call Unlock() instead of Progress(). Defaults to false"),
+        triggerTag: z
+            .string()
+            .optional()
+            .describe("Tag the entering object must carry (put it on the player via set_tags). Defaults to 'player'"),
+        onceOnly: z
+            .boolean()
+            .optional()
+            .describe("Only the first tagged entry fires. Defaults to true"),
+        destroyAfterFire: z
+            .boolean()
+            .optional()
+            .describe("Destroy the zone GameObject after firing. Defaults to false"),
+        createObject: z
+            .boolean()
+            .optional()
+            .describe("Create the zone GameObject now (with BoxCollider). Defaults to true; false = code-gen only"),
+        objectName: z
+            .string()
+            .optional()
+            .describe("Name for the zone GameObject. Defaults to '<name>Zone'"),
+        position: Vector3Schema.optional().describe("World position of the zone GameObject"),
+        scale: z
+            .union([z.number(), Vector3Schema])
+            .optional()
+            .describe('BoxCollider size — uniform number, object {x,y,z}, or comma string "x,y,z". Defaults to 100,100,100'),
+        reuseClass: z
+            .boolean()
+            .optional()
+            .describe("If the .cs already exists, skip codegen and just place another zone with the existing class. Defaults to false"),
+    }, async (params) => {
+        const res = await bridge.send("add_achievement_trigger", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── create_speedrun_leaderboard ───────────────────────────────────
+    server.tool("create_speedrun_leaderboard", "Generate a speedrun timer component plus a leaderboard display panel. The timer (<Name>.cs) is TimeSince-based with a static Instance: StartTimer() at run start, StopTimer() at the finish (pairs with a trigger zone), ResetTimer() to abort. StopTimer persists the local best via FileSystem.Data and submits Stats.SetValue(statName, seconds) ONLY when the run beats it — configure the stat with MIN aggregation on sbox.game so the global board keeps best times. The panel (<Name>Panel.razor + .razor.scss, razor_lint clean) fetches via Leaderboards.GetFromStat with min aggregation + ascending sort, has a clickable Friends-only filter button, and overlays a local-best row read from the same save file. Returns { created, path, className, panelRazorPath, panelScssPath, panelClassName, statName, placedOn, note, nextSteps }. After trigger_hotload: place ONE timer (add_component_to_new_object or targetId) and host the panel under a ScreenPanel/WorldPanel (add_screen_panel). maxRows clamps to 1..50; makePanel=false skips the panel files. Fails if the .cs or panel .razor already exists.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated timer component (panel becomes <name>Panel). Defaults to 'SpeedrunTimer'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for all generated files. Defaults to 'Code'"),
+        statName: z
+            .string()
+            .optional()
+            .describe("Sandbox.Services stat the best time is written to (sanitized to [a-z0-9_-]). Defaults to 'best_time'"),
+        fileName: z
+            .string()
+            .optional()
+            .describe("Save file name inside FileSystem.Data for the local best. Defaults to 'speedrun.json'"),
+        title: z
+            .string()
+            .optional()
+            .describe("Panel title text. Defaults to 'Best Times'"),
+        maxRows: z
+            .number()
+            .optional()
+            .describe("Leaderboard rows fetched/shown. Defaults to 10, clamped to 1..50"),
+        makePanel: z
+            .boolean()
+            .optional()
+            .describe("Also emit the <name>Panel.razor + .razor.scss display panel. Defaults to true"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of a GameObject to attach the timer to (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_speedrun_leaderboard", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── create_elo_rating_system ──────────────────────────────────────
+    server.tool("create_elo_rating_system", "Generate a self-contained, host-authoritative elo rating component: standard elo math (expected = 1/(1+10^((Rb-Ra)/400)), delta = K * (score - expected)) with a [Property] K-factor, ratings in a [Sync(SyncFlags.FromHost)] NetDictionary<long,float> keyed by SteamId, and host-side persistence via FileSystem.Data JSON. API on a static Instance: ReportMatch(winnerSteamId, loserSteamId) for 1v1 and ReportTeamMatch(winnerIds, loserIds) for teams (team-average elo, uniform delta per member) — both are IsProxy-guarded no-ops on clients; GetRating(steamId) works anywhere (unknown players = defaultRating); the static OnRatingChanged(steamId, newRating) fires on EVERY machine via an [Rpc.Broadcast]. Returns { created, path, className, kFactor, defaultRating, placedOn, note, nextSteps }. After trigger_hotload: place ONE in the scene and network its GameObject (network_spawn) or the [Sync] never replicates. Only the HOST's disk holds the ratings ledger. Fails if the file already exists.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated component. Defaults to 'EloRatingSystem'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        kFactor: z
+            .number()
+            .optional()
+            .describe("Elo K-factor — how far one result moves ratings (32 = fast, 16 = stable). Defaults to 32, clamped to >= 1"),
+        defaultRating: z
+            .number()
+            .optional()
+            .describe("Rating assigned to players with no recorded matches. Defaults to 1000"),
+        fileName: z
+            .string()
+            .optional()
+            .describe("Save file name inside FileSystem.Data (host-side ledger). Defaults to 'elo_ratings.json'"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of a GameObject to attach to (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("create_elo_rating_system", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+}
+//# sourceMappingURL=statsachievements.js.map

package/dist/tools/worldrender.d.ts

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

package/dist/tools/worldrender.js

@@ -0,0 +1,183 @@
+import { z } from "zod";
+/**
+ * World & Render family — three tools:
+ *
+ *   - add_water_body            WaterVolume physics volume + trigger BoxCollider
+ *                               footprint + optional tinted visual surface
+ *   - add_render_target_camera  secondary camera → render-target texture →
+ *                               display surface (CCTV / mirror / portal)
+ *   - add_daynight_sun          codegen sun/sky driver bound to the component
+ *                               generated by create_day_night_clock
+ *
+ * add_water_body is scene-direct; the other two generate a sealed game-code
+ * component (hotload to compile). All three are scene/file-mutating and are
+ * refused during play mode by the bridge dispatch.
+ */
+// Colour / vector accepted as EITHER an object OR a comma string, passed
+// through unchanged. The C# handler parses both forms (source of truth). See
+// the cross-language vector/color contract.
+const ColorObject = z.object({
+    r: z.number().min(0).describe("Red, 0-1"),
+    g: z.number().min(0).describe("Green, 0-1"),
+    b: z.number().min(0).describe("Blue, 0-1"),
+    a: z.number().min(0).max(1).optional().describe("Alpha, 0-1 (default 1)"),
+});
+const ColorSchema = z
+    .union([
+    ColorObject,
+    z.string().describe('Comma string "r,g,b,a", e.g. "1,0,0,1"'),
+])
+    .describe('RGBA colour — object {r,g,b,a} (0-1) OR comma string "r,g,b,a"');
+const Vector3Object = z.object({ x: z.number(), y: z.number(), z: z.number() });
+const Vector3Schema = z
+    .union([
+    Vector3Object,
+    z.string().describe('Comma string "x,y,z", e.g. "0,0,200"'),
+])
+    .describe('World position — object {x,y,z} OR comma string "x,y,z"');
+const RotationSchema = z
+    .object({ pitch: z.number(), yaw: z.number(), roll: z.number() })
+    .describe("Rotation {pitch,yaw,roll} in degrees");
+export function registerWorldRenderTools(server, bridge) {
+    // ── add_water_body ───────────────────────────────────────────────
+    server.tool("add_water_body", "Create a swimmable/buoyant water region: a GameObject with a WaterVolume (s&box's buoyancy + drag physics volume, region defined by a trigger BoxCollider sized to `size`) plus, by default, a simple flat translucent-blue surface box at the water line so it's visible. HONEST LIMIT: the visual is a tinted dev-box stand-in, NOT a Gerstner/water shader — the dev material may render the tint opaque; swap in a real water material later. Only the WaterVolume properties you pass are set (engine defaults otherwise). Returns {created, gameObject{id,...}, size, appliedProperties[], surface{id,...}|null, note, nextSteps[]}. Next: start_play and drop a physics prop in to verify buoyancy; tune FluidDensity/LinearDrag/WaveAmplitude etc. with set_property on the WaterVolume. Scene-mutating — refused during play mode.", {
+        name: z
+            .string()
+            .optional()
+            .describe("GameObject name. Defaults to 'Water'"),
+        position: Vector3Schema.optional().describe("World position of the volume's CENTRE (the surface sits at z + size.z/2 + surfaceOffset)"),
+        size: z
+            .string()
+            .optional()
+            .describe("Full extents of the volume as 'x,y,z' world units. Defaults to '512,512,128'"),
+        density: z
+            .number()
+            .optional()
+            .describe("WaterVolume.FluidDensity — higher = more buoyant. Engine default when omitted"),
+        linearDrag: z
+            .number()
+            .optional()
+            .describe("WaterVolume.LinearDrag on submerged bodies. Engine default when omitted"),
+        angularDrag: z
+            .number()
+            .optional()
+            .describe("WaterVolume.AngularDrag on submerged bodies. Engine default when omitted"),
+        waveAmplitude: z
+            .number()
+            .optional()
+            .describe("WaterVolume.WaveAmplitude — physics wave height (does NOT animate the visual surface)"),
+        waveFrequency: z
+            .number()
+            .optional()
+            .describe("WaterVolume.WaveFrequency — physics wave frequency"),
+        fluidVelocity: Vector3Schema.optional().describe("WaterVolume.FluidVelocity — current/flow direction and speed, world units/s"),
+        surfaceOffset: z
+            .number()
+            .optional()
+            .describe("WaterVolume.SurfaceOffset — shifts the water line relative to the top of the box"),
+        visualSurface: z
+            .boolean()
+            .optional()
+            .describe("Create the tinted surface box child. Defaults to true"),
+        surfaceColor: ColorSchema.optional().describe("Tint of the visual surface. Defaults to translucent blue (0.15,0.35,0.55,0.6)"),
+        parentId: z.string().optional().describe("GUID of a parent GameObject"),
+    }, async (params) => {
+        const res = await bridge.send("add_water_body", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── add_render_target_camera ─────────────────────────────────────
+    server.tool("add_render_target_camera", "CCTV / security monitor / mirror / simple portal: creates a secondary camera (IsMainCamera=false, Priority param) positioned/rotated or aimed at a target object, a display surface (scaled box with a ModelRenderer), and GENERATES a sealed wiring component that at runtime creates the render-target Texture (Texture.CreateRenderTarget builder), assigns camera.RenderTarget and sets the texture onto an anonymous complex-shader material on the display (attribute 'Color' = albedo; the screen is scene-lit, not emissive/unlit). Returns {created, camera{id,...}, display{id,...}|null, className, path, generatedCode, attachedAndWired, resolution, nextSteps[]}. FIRST call generates the .cs → follow nextSteps: trigger_hotload, then add_component_with_properties on the display with properties {SourceCamera: <camera GUID>}; a REPEAT call reusing the same `name` after the hotload attaches AND wires everything automatically (attachedAndWired=true). The feed only renders in play mode — verify with start_play + capture_view. If `name`'s .cs file exists but isn't compiled yet, the call errors — hotload first. Scene/file-mutating — refused during play mode.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated wiring component. Defaults to 'RenderTargetDisplay'. Reuse the same name for extra cameras — after a hotload the class is reused and wired in one shot"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        cameraName: z
+            .string()
+            .optional()
+            .describe("GameObject name for the camera. Defaults to 'RT Camera'"),
+        position: Vector3Schema.optional().describe("World position of the camera"),
+        rotation: RotationSchema.optional().describe("World rotation of the camera"),
+        lookAtId: z
+            .string()
+            .optional()
+            .describe("GUID of a GameObject to aim the camera at (overrides rotation; from get_scene_hierarchy / find_objects)"),
+        priority: z
+            .number()
+            .optional()
+            .describe("CameraComponent.Priority (integer). Defaults to 1"),
+        fieldOfView: z
+            .number()
+            .optional()
+            .describe("Camera field of view in degrees (clamped 5-170). Engine default when omitted"),
+        resolution: z
+            .string()
+            .optional()
+            .describe("Render-target size as 'width,height' pixels (min 16). Defaults to '512,512'"),
+        backgroundColor: ColorSchema.optional().describe("Camera background colour. Engine default when omitted"),
+        createDisplay: z
+            .boolean()
+            .optional()
+            .describe("Create the display surface GameObject. Defaults to true. Pass false to wire your own surface later"),
+        displayPosition: Vector3Schema.optional().describe("World position of the display surface"),
+        displayRotation: RotationSchema.optional().describe("World rotation of the display surface"),
+        displaySize: z
+            .string()
+            .optional()
+            .describe("Display box extents as 'x,y,z' world units (thin x = a wall screen facing ±x). Defaults to '4,128,72'"),
+        attribute: z
+            .string()
+            .optional()
+            .describe("Material attribute that receives the texture. Defaults to 'Color' (albedo on the complex shader). Sanitized to [A-Za-z0-9_]"),
+    }, async (params) => {
+        const res = await bridge.send("add_render_target_camera", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+    // ── add_daynight_sun ─────────────────────────────────────────────
+    server.tool("add_daynight_sun", "Generate a sun/sky driver component for the clock made by create_day_night_clock — a COMPANION, not a replacement: the clock owns TimeOfDay, this renders it. Every frame it reads TimeOfDay/SunriseHour/SunsetHour off the clock (sibling first, else first in scene, retrying 1/s) and drives a DirectionalLight: sunrise→sunset maps to a 0-180° pitch arc (continuing below the horizon at night), LightColor runs a hardcoded gradient (warm dawn → white noon → orange dusk → dim blue night, HDR-scaled by Intensity since s&box lights have no Brightness field), and optionally lerps the SkyBox2D Tint between night blue and day white. The clock CLASS NAME is baked in as a typed reference — the call ERRORS if `clockClass` isn't found in the TypeLibrary or any project .cs (run create_day_night_clock first; a bad token would break the whole game-assembly compile). Returns {created, path, className, clockClass, sunYaw, intensity, driveSkybox, placedOn, note, nextSteps[]}. Next: trigger_hotload → attach to the DirectionalLight's GameObject → start_play, set_runtime_property TimeOfDay on the clock (6/12/20/0) + capture_view to verify the looks. File/scene-mutating — refused during play mode.", {
+        name: z
+            .string()
+            .optional()
+            .describe("Class name for the generated component. Defaults to 'DayNightSun'"),
+        directory: z
+            .string()
+            .optional()
+            .describe("Subdirectory for the generated .cs file. Defaults to 'Code'"),
+        clockClass: z
+            .string()
+            .optional()
+            .describe("Class name of the day-night clock to bind to (the `name` you gave create_day_night_clock). Defaults to 'DayNightClock'. Must already exist as a compiled type or a project .cs file"),
+        sunYaw: z
+            .number()
+            .optional()
+            .describe("Compass heading of the sun's arc in degrees. Defaults to 30"),
+        intensity: z
+            .number()
+            .optional()
+            .describe("Brightness multiplier on the colour gradient (HDR, >1 valid; intensity = colour magnitude). Defaults to 1"),
+        driveSkybox: z
+            .boolean()
+            .optional()
+            .describe("Also tint the scene's SkyBox2D between night blue and day white. Defaults to true"),
+        targetId: z
+            .string()
+            .optional()
+            .describe("GUID of a GameObject to attach to (only attaches if the type is already loaded — hotload first)"),
+    }, async (params) => {
+        const res = await bridge.send("add_daynight_sun", params);
+        if (!res.success) {
+            return { content: [{ type: "text", text: `Error: ${res.error}` }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }] };
+    });
+}
+//# sourceMappingURL=worldrender.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sbox-mcp-server",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "MCP Server for s&box game engine — enables Claude to build games through conversation",
   "type": "module",
   "main": "dist/index.js",