@el4cteo/rbx-studio-mcp 0.6.1 → 0.6.7

package/dist/tools/world.js

@@ -1,5 +1,9 @@
 import { z } from "zod";
+import { grantAssets, publishPlace, uploadAsset } from "../lib/cloudassets.js";
+import { ToolError } from "../lib/errors.js";
 import { json, table, text, textOf } from "../lib/format.js";
+import { assetQuotas, restartServers } from "../lib/liveops.js";
+import { requireCredentials, requirePlace, requireUniverse } from "../lib/opencloud.js";
 import { defineTool } from "../lib/tool.js";
 /** Roblox's toolbox search. Public, unauthenticated, and the same index Studio's own asset browser uses. */
 /** Segmentation runs the same slow generation backend `generate` does. */
@@ -15,28 +19,96 @@ const CATEGORIES = { model: 10, decal: 13, mesh: 40, audio: 3 };
  * while a plugin making outbound HTTP needs the user to approve each domain in
  * Plugin Management. Searching here means it works the moment the server starts.
  */
-async function searchCreatorStore(keyword, category, limit) {
+/**
+ * Pages to pull before filtering gives up looking for more.
+ *
+ * Filtering happens here rather than at Roblox (see below), so a strict filter
+ * over one page of thirty can return nothing while the good results sit on page
+ * two. Four pages is enough to find script-free models for any ordinary search
+ * without turning one call into a crawl of the whole index.
+ */
+const MAX_PAGES = 4;
+/**
+ * Searches the Creator Store from the server rather than the plugin.
+ *
+ * Node already has internet access and these endpoints answer unauthenticated,
+ * while a plugin making outbound HTTP needs the user to approve each domain in
+ * Plugin Management. Searching here means it works the moment the server starts.
+ *
+ * Filtering and ranking are done HERE, on purpose. The endpoint accepts
+ * `sortType` and `creatorFilter` and ignores both — measured, Relevance,
+ * MostTaken, Favorited and Updated returned byte-identical results for the same
+ * keyword, as did a Roblox-only creator filter. Passing them through would have
+ * looked like sorting and done nothing, which is worse than not offering it. So
+ * the only server-side lever that works is the cursor, and everything else is
+ * decided from the details each result carries.
+ */
+async function searchCreatorStore(keyword, category, limit, filters = {}) {
     const categoryId = CATEGORIES[category] ?? 10;
-    const url = `${TOOLBOX_SEARCH}/${categoryId}?keyword=${encodeURIComponent(keyword)}` +
-        `&limit=${Math.min(limit, 30)}&sortType=Relevance`;
-    const found = await fetch(url, { signal: AbortSignal.timeout(15_000) });
-    if (!found.ok) {
-        throw new Error(`Creator Store search failed (${found.status}). Roblox may be rate-limiting.`);
-    }
-    const results = (await found.json());
-    const ids = (results.data ?? []).map((entry) => entry.id).slice(0, limit);
-    if (ids.length === 0)
-        return [];
-    // Search returns bare ids; everything worth showing — name, creator, whether
-    // it carries scripts — needs the second call.
-    const detailed = await fetch(`${TOOLBOX_DETAILS}?assetIds=${ids.join(",")}`, {
-        signal: AbortSignal.timeout(15_000),
-    });
-    if (!detailed.ok) {
-        throw new Error(`Could not read asset details (${detailed.status}).`);
+    const kept = [];
+    let cursor = "";
+    let scanned = 0;
+    let total;
+    for (let page = 0; page < MAX_PAGES && kept.length < limit; page += 1) {
+        const url = `${TOOLBOX_SEARCH}/${categoryId}?keyword=${encodeURIComponent(keyword)}` +
+            `&limit=30${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`;
+        const found = await fetch(url, { signal: AbortSignal.timeout(15_000) });
+        if (!found.ok) {
+            throw new Error(`Creator Store search failed (${found.status}). Roblox may be rate-limiting.`);
+        }
+        const results = (await found.json());
+        total = total ?? results.totalResults;
+        const ids = (results.data ?? []).map((entry) => entry.id);
+        if (ids.length === 0)
+            break;
+        scanned += ids.length;
+        // Search returns bare ids; everything worth showing — name, creator, script
+        // count, price — needs the second call.
+        const detailed = await fetch(`${TOOLBOX_DETAILS}?assetIds=${ids.join(",")}`, {
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (!detailed.ok) {
+            throw new Error(`Could not read asset details (${detailed.status}).`);
+        }
+        const payload = (await detailed.json());
+        for (const entry of payload.data ?? []) {
+            if (filters.excludeScripts && entry.asset?.hasScripts)
+                continue;
+            if (filters.verifiedOnly && !entry.creator?.isVerifiedCreator)
+                continue;
+            if (filters.freeOnly && entry.fiatProduct?.isFree === false)
+                continue;
+            if (filters.minVotes !== undefined && (entry.voting?.voteCount ?? 0) < filters.minVotes) {
+                continue;
+            }
+            if (filters.maxTriangles !== undefined) {
+                const triangles = entry.asset?.modelTechnicalDetails?.objectMeshSummary?.triangles;
+                if (triangles !== undefined && triangles > filters.maxTriangles)
+                    continue;
+            }
+            kept.push(entry);
+        }
+        cursor = results.nextPageCursor ?? "";
+        if (!cursor)
+            break;
     }
-    const payload = (await detailed.json());
-    return payload.data ?? [];
+    /*
+     * Ranked by approval WEIGHTED BY how many people voted.
+     *
+     * The raw percentage is what the API gives and it is close to meaningless on
+     * its own: 82% of 5000 votes and 100% of 2 votes sort the wrong way round
+     * every time, and the second is the one nobody should be inserting into their
+     * game. Pulling the percentage toward 50 in proportion to how little evidence
+     * there is behind it costs nothing and puts the well-used models first.
+     */
+    const score = (entry) => {
+        const percent = entry.voting?.upVotePercent ?? 50;
+        const votes = entry.voting?.voteCount ?? 0;
+        const confidence = votes / (votes + 50);
+        return 50 + (percent - 50) * confidence;
+    };
+    kept.sort((a, b) => score(b) - score(a));
+    return { items: kept.slice(0, limit), scanned, total };
 }
 export function registerWorldTools(context) {
     const { bridge } = context;
@@ -70,15 +142,44 @@ export function registerWorldTools(context) {
             "Roblox returns bare grey MeshParts, so a brick wall with a hole cut in " +
             "it would otherwise come back as a grey slab - correct geometry that " +
             "looks like a mistake.\n\n" +
+            "`mesh` reads the real triangle and vertex counts of MeshParts, which is " +
+            "the only way to tell a 40,000-triangle tree from a 400-triangle one — " +
+            "they are identical in the Explorer and in Properties, and the difference " +
+            "is whether the place runs on a phone. It also reports mesh size against " +
+            "part size: the same triangles stretched over a bigger object is the usual " +
+            "reason a model costs more than it looks like it should.\n\n" +
+            "`mesh` only works on meshes the signed-in Studio user or the experience " +
+            "owner OWNS. Roblox refuses to open anyone else's, so a model inserted " +
+            "from the Creator Store cannot be measured this way — the tool says which " +
+            "parts were skipped rather than failing the whole batch.\n\n" +
+            "`mirror` flips instances across a plane and has no engine API behind " +
+            "it — Studio simply cannot do this, which is why people ask for it. " +
+            "Mirroring about the middle of the selection is the default, because " +
+            "mirroring a building at x=200 about the world origin puts it 400 " +
+            "studs away rather than flipping it in place. It COPIES by default; " +
+            "pass `copy: false` to flip the originals. MeshParts move and rotate " +
+            "correctly but their meshes are not remade, so an asymmetric mesh " +
+            "still reads the same way round.\n\n" +
             "`segment` runs Roblox's Cube model and takes tens of seconds; the rest " +
             "are fast. Each call is one undo step.",
         inputSchema: {
             op: z
-                .enum(["union", "subtract", "intersect", "fragment", "sweep", "segment"])
+                .enum(["union", "subtract", "intersect", "fragment", "sweep", "segment", "mesh", "mirror"])
                 .describe("'union' merges, 'subtract' cuts `with` out of `path`, 'intersect' " +
                 "keeps only the overlap, 'fragment' shatters into debris, 'sweep' " +
                 "builds a motion volume, 'segment' cuts a mesh into named parts."),
             path: z.string().describe("The part being operated on - the one cut from, for subtract."),
+            about: z
+                .string()
+                .optional()
+                .describe('mirror only: the plane position, e.g. "0, 0, 0". Defaults to ' +
+                "the middle of what is being mirrored, which flips it in place."),
+            copy: z
+                .boolean()
+                .optional()
+                .describe("mirror only: leave the originals and add mirrored copies. True by " +
+                "default — that is what builds a symmetrical structure from half " +
+                "of one. False flips the originals in place."),
             with: z
                 .array(z.string())
                 .max(50)
@@ -117,7 +218,9 @@ export function registerWorldTools(context) {
             axis: z
                 .string()
                 .optional()
-                .describe('sweep only: axis to spin around, e.g. "0, 1, 0". Defaults to up.'),
+                .describe('sweep: axis to spin around, e.g. "0, 1, 0" (defaults to up). ' +
+                'mirror: which axis to flip across — "X", "Y" or "Z", ' +
+                "defaulting to X."),
             pivot: z
                 .string()
                 .optional()
@@ -176,10 +279,41 @@ export function registerWorldTools(context) {
                 .boolean()
                 .default(false)
                 .describe("Return disconnected chunks as separate parts rather than one."),
+            paths: z
+                .array(z.string())
+                .max(50)
+                .optional()
+                .describe("mesh only: the MeshParts to read geometry from."),
             studioId: z.string().optional().describe("Target Studio; omit for the active one."),
         },
         destructive: true,
     }, async (args) => {
+        if (args.op === "mirror") {
+            const paths = args.paths ?? (args.path !== undefined ? [args.path] : []);
+            if (paths.length === 0) {
+                return text("mirror needs `paths` — the instances to flip.");
+            }
+            return json(await bridge.call("geometry.mirror", { paths, axis: args.axis, about: args.about, copy: args.copy }, { studioId: args.studioId, timeoutMs: 60_000 }));
+        }
+        if (args.op === "mesh") {
+            const paths = args.paths ?? (args.path !== undefined ? [args.path] : []);
+            if (paths.length === 0) {
+                return text('mesh needs `paths` — the MeshParts to read, e.g. ["Workspace.Tree"].');
+            }
+            const read = await bridge.call("geometry.mesh", { paths }, 
+            // Each part is a separate download-and-open, so a batch of twenty is
+            // twenty round trips to Roblox's asset servers.
+            { studioId: args.studioId, timeoutMs: 120_000 });
+            if (read.items.length === 0) {
+                return text(read.failures.length > 0
+                    ? `Nothing readable:\n  ${read.failures.join("\n  ")}`
+                    : "No MeshParts in that list.");
+            }
+            const rendered = textOf(table(["name", "triangles", "vertices", "meshSize", "partSize", "renderFidelity", "collisionFidelity"], read.items, { more: `${read.totalTriangles} triangles across ${read.items.length} part(s)` }));
+            return text(read.failures.length > 0
+                ? `${rendered}\n\nSkipped:\n  ${read.failures.join("\n  ")}`
+                : rendered);
+        }
         // `segment` is GenerationService, not GeometryService - the same job from
         // the caller's side, a different service underneath, and far slower.
         if (args.op === "segment") {
@@ -261,13 +395,32 @@ export function registerWorldTools(context) {
         title: "Creator Store",
         description: "Searches Roblox's Creator Store and inserts models into the place.\n\n" +
             "`search` looks through the same public index Studio's own asset browser " +
-            "uses and returns ids with names, creators, vote ratios and — the part " +
-            "that matters — whether the model contains scripts. `insert` puts one " +
-            "into the place by id.\n\n" +
+            "uses. It reports script COUNT, triangles, whether the creator is " +
+            "verified, whether the asset is free, and what Roblox thinks it is " +
+            "(\"Door/Furniture\"). `insert` puts one into the place by id.\n\n" +
+            "Results are ranked by approval WEIGHTED BY vote count, because the raw " +
+            "percentage lies: 100% from two voters outranks 82% from five thousand " +
+            "unless the count is taken into account. The vote count is shown beside " +
+            "the percentage for the same reason.\n\n" +
+            "Filters — `excludeScripts`, `maxTriangles`, `verifiedOnly`, `freeOnly`, " +
+            "`minVotes` — are applied here, not by Roblox, and several pages are " +
+            "fetched to fill the results. Roblox's own sort and creator filters are " +
+            "accepted by the endpoint and silently ignored, so they are not offered.\n\n" +
             "ALWAYS check `hasScripts` before inserting. Free models carrying " +
             "scripts are the oldest hazard on the platform, and a model dropped into " +
             "someone's game can run whatever it likes. The insert reports the script " +
             "count again, and names them, so it can still be undone.\n\n" +
+            "`peek` is the safer half of that: it loads the asset in memory WITHOUT " +
+            "putting it in the place and tells you exactly what is inside — every " +
+            "class, every script by name. Nothing is parented, so there is nothing " +
+            "to undo. Use it whenever `hasScripts` says YES and the model still " +
+            "looks worth having.\n\n" +
+            "Audio searches take a different path from everything else here. They go " +
+            "to the engine's own audio index, so results carry duration, artist and " +
+            "whether the clip is music or a sound effect — the fields that actually " +
+            "decide which sound you want. They return SOUND EFFECTS by default; pass " +
+            '`audioType: "Music"` for tracks. Filter with `minDuration` / ' +
+            "`maxDuration` — a footstep is under a second and a music bed is minutes.\n\n" +
             "Only public assets can be inserted. A private or deleted id fails with " +
             "a message saying so rather than inserting nothing quietly.\n\n" +
             "`bake` is unrelated to the Creator Store and does not upload anything. " +
@@ -281,19 +434,162 @@ export function registerWorldTools(context) {
             "against a RUNNING playtest server session: pass that `studioId`, and " +
             "baking a mesh the game just built is what lets clients see it.\n\n" +
             "It does not help `generate` at all. Generated meshes hold opaque " +
-            "content, which the engine refuses to bake.",
+            "content, which the engine refuses to bake.\n\n" +
+            "THE OTHER DIRECTION: `upload` sends a local file TO Roblox and " +
+            "gives you the asset id. Audio, an image, a 3D model or a video, " +
+            "picked by extension — .mp3/.ogg/.wav/.flac, .png/.jpg/.bmp/.tga, " +
+            ".fbx/.gltf/.glb, .mp4/.mov. This closes the one hole nothing else " +
+            "here covers: a sound effect sitting in a folder on disk used to " +
+            "need Studio's import dialog before anything could reference it.\n\n" +
+            "Uploads are moderated and count against a real monthly quota. Do not " +
+            "guess what it is — Roblox's own guide and the live API disagree, and " +
+            "the account's verification level changes it. Ask `op=\"quota\"`. Do " +
+            "not upload speculatively, and do not re-upload to retry: the first " +
+            "one probably worked.\n\n" +
+            "`grant` gives a game or a person permission to use assets you own. " +
+            "You do NOT need this for your own assets in your own game — those " +
+            "always work. It is for a collaborator's place, or a group game you " +
+            "do not own. A grant to a game is PERMANENT; Roblox provides no way " +
+            "to revoke one, so it needs `confirm: true`.\n\n" +
+            "`publish` sends a .rbxl or .rbxlx from disk to a place. It SAVES a " +
+            "new version by default and only goes live with `confirm: true`. " +
+            "Note a real limitation: Roblox's publishing API does not update " +
+            "EditableImage, EditableMesh, PartOperation, SurfaceAppearance or " +
+            "BaseWrap instances, and reports success anyway — publish from " +
+            "Studio if the place uses any of those.\n\n" +
+            "Publishing alone does NOT move anyone already playing — they stay " +
+            "on their server running the old code until it empties. Pass " +
+            "`restart: true` to roll live servers onto the new version, which " +
+            "bleeds them off over 10 minutes rather than dropping players.\n\n" +
+            "`quota` reports how many uploads are left before Roblox starts " +
+            "refusing them, per asset type, read from the account itself. Check it " +
+            "before a batch rather than discovering the ceiling halfway through.\n\n" +
+            "All of these need an Open Cloud API key. The user sets it once by " +
+            "typing `cloud` in the Studio panel; never ask them to paste a key " +
+            "into this conversation.",
         inputSchema: {
             op: z
-                .enum(["search", "insert", "bake"])
-                .describe("'search' finds assets, 'insert' adds one to the place, 'bake' makes " +
-                "in-memory mesh and image data replicate."),
+                .enum(["search", "peek", "insert", "bake", "upload", "grant", "publish", "quota"])
+                .describe("'search' finds assets, 'peek' shows what is inside one without " +
+                "inserting it, 'insert' adds one to the place, 'bake' makes " +
+                "in-memory mesh and image data replicate, 'upload' sends a " +
+                "local file to Roblox, 'grant' shares one you own with " +
+                "another game or person, 'publish' pushes a place file live."),
+            file: z
+                .string()
+                .optional()
+                .describe("upload/publish: path to the file on disk. Omit on `upload` to " +
+                "check whether the credentials are set up without sending " +
+                "anything."),
+            description: z
+                .string()
+                .optional()
+                .describe("upload only: public description. Moderated."),
+            assetType: z
+                .enum(["Audio", "Decal", "Model", "Video"])
+                .optional()
+                .describe("upload only: override the type derived from the extension. " +
+                "Rarely right — Roblox validates the type against the file's " +
+                "real content."),
+            insertAs: z
+                .string()
+                .optional()
+                .describe("upload only: put the finished asset in the place at this " +
+                "parent path once it is approved. Decals and Models only — an " +
+                "audio id belongs in an AudioPlayer, so use `audio " +
+                "op=\"graph\"` with the id this returns."),
+            assetIds: z
+                .array(z.number().int())
+                .max(50)
+                .optional()
+                .describe("grant only: the assets to share. You must own them."),
+            subjectType: z
+                .enum(["Universe", "User", "Group"])
+                .optional()
+                .describe("grant only: who gets access. 'Universe' is a game and is the " +
+                "usual one. Defaults to 'Universe'."),
+            subjectId: z
+                .string()
+                .optional()
+                .describe("grant only: the universe, user or group id. Omit for a " +
+                "Universe grant to use the one set with `cloud universe <id>`."),
+            universeId: z.string().optional().describe("publish only: which game. Omit to use `cloud universe`."),
+            placeId: z.string().optional().describe("publish only: which place. Omit to use `cloud place`."),
+            restart: z
+                .boolean()
+                .optional()
+                .describe("publish only: also roll live servers onto the new version. " +
+                "Without this, players already in a server keep running the " +
+                "old code until it empties."),
+            stripScripts: z
+                .boolean()
+                .optional()
+                .describe("insert only: delete every Script, LocalScript and ModuleScript " +
+                "from the asset on the way in. The safe way to take geometry " +
+                "from a free model without taking whatever its scripts do."),
+            confirm: z
+                .boolean()
+                .optional()
+                .describe("Required to make a `publish` go live rather than only save, " +
+                "and required for `grant`, whose effect Roblox cannot undo."),
             keyword: z.string().optional().describe("search only: what to look for, e.g. \"medieval door\"."),
             category: z
                 .enum(["model", "decal", "mesh", "audio"])
                 .default("model")
                 .describe("search only: what kind of asset. Only models insert as instances."),
             limit: z.number().int().min(1).max(20).default(8).describe("search only: how many results."),
-            assetId: z.number().int().positive().optional().describe("insert only: the asset id to insert."),
+            excludeScripts: z
+                .boolean()
+                .default(false)
+                .describe("search only: drop every result that contains scripts. The single " +
+                "safest filter — a free model's scripts run with your game's full " +
+                "permissions."),
+            maxTriangles: z
+                .number()
+                .int()
+                .min(1)
+                .optional()
+                .describe("search only: drop models heavier than this. A prop you place fifty " +
+                "times wants to be in the hundreds, not the tens of thousands."),
+            verifiedOnly: z
+                .boolean()
+                .default(false)
+                .describe("search only: only results from verified creators."),
+            freeOnly: z
+                .boolean()
+                .default(false)
+                .describe("search only: drop paid assets, which cannot just be inserted."),
+            minVotes: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe("search only: require at least this many votes. Filters out models " +
+                "with a perfect score from three people."),
+            minDuration: z
+                .number()
+                .min(0)
+                .optional()
+                .describe("audio search only: shortest clip to return, in seconds."),
+            maxDuration: z
+                .number()
+                .min(0)
+                .optional()
+                .describe("audio search only: longest clip to return, in seconds. Set it to 3 " +
+                "or so for effects — otherwise full-length music dominates the results."),
+            audioType: z
+                .enum(["SoundEffect", "Music"])
+                .default("SoundEffect")
+                .describe("audio search only. Defaults to SoundEffect, which is what a noise in " +
+                'a game is. Ask for "Music" only when you want a track — the engine\'s ' +
+                'own default is Music, and it makes "footstep" return three-minute ' +
+                "ambient songs with footsteps in the title."),
+            assetId: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe("insert and peek only: the asset id."),
             parent: z.string().optional().describe("insert only: where to put it. Defaults to Workspace."),
             position: z
                 .string()
@@ -309,28 +605,215 @@ export function registerWorldTools(context) {
         },
         destructive: false,
     }, async (args) => {
+        if (args.op === "peek") {
+            if (!args.assetId)
+                return text("peek needs an `assetId`.");
+            const inside = await bridge.call("assets.peek", { assetId: args.assetId }, { studioId: args.studioId, timeoutMs: 60_000 });
+            const lines = [
+                `Asset ${inside.assetId}: ${inside.descendants} instances, nothing inserted.`,
+                "",
+                `Top level: ${inside.roots.join(", ")}`,
+                "",
+                textOf(table(["className", "count"], inside.classes)),
+            ];
+            lines.push(inside.scriptCount === 0
+                ? "\nNo scripts — safe to insert."
+                : `\n${inside.scriptCount} script(s), and inserting runs them:\n  ` +
+                    inside.scripts.join("\n  ") +
+                    "\nRead them with `script_read` after inserting, or leave this asset alone.");
+            return text(lines.join("\n"));
+        }
+        if (args.op === "search" && args.category === "audio") {
+            if (!args.keyword)
+                return text("search needs a `keyword`.");
+            const found = await bridge.call("assets.audio", {
+                keyword: args.keyword,
+                limit: args.limit,
+                minDuration: args.minDuration,
+                maxDuration: args.maxDuration,
+                audioType: args.audioType,
+            }, { studioId: args.studioId, timeoutMs: 45_000 });
+            if (found.items.length === 0) {
+                return text(`No audio matched "${args.keyword}".` +
+                    (args.minDuration !== undefined || args.maxDuration !== undefined
+                        ? " The duration filter may be too narrow — try it without one."
+                        : ""));
+            }
+            return text(textOf(table(["assetId", "title", "artist", "duration", "audioType", "endorsed"], found.items, {
+                more: `${found.audioType}s only; duration in seconds; use the assetId as a ` +
+                    "Sound's SoundId" +
+                    (found.audioType === "SoundEffect"
+                        ? '. Pass audioType="Music" for tracks.'
+                        : "."),
+            })));
+        }
         if (args.op === "search") {
             if (!args.keyword)
                 return text("search needs a `keyword`.");
-            const found = await searchCreatorStore(args.keyword, args.category, args.limit);
-            if (found.length === 0) {
-                return text(`Nothing matched "${args.keyword}" in ${args.category}s.`);
+            const found = await searchCreatorStore(args.keyword, args.category, args.limit, {
+                excludeScripts: args.excludeScripts,
+                maxTriangles: args.maxTriangles,
+                verifiedOnly: args.verifiedOnly,
+                freeOnly: args.freeOnly,
+                minVotes: args.minVotes,
+            });
+            if (found.items.length === 0) {
+                const filtered = args.excludeScripts || args.verifiedOnly || args.freeOnly || args.maxTriangles || args.minVotes;
+                return text(`Nothing matched "${args.keyword}" in ${args.category}s` +
+                    (filtered
+                        ? `. ${found.scanned} result(s) were checked and every one was filtered out — loosen a filter.`
+                        : "."));
             }
-            const rows = found.map((entry) => ({
+            const rows = found.items.map((entry) => ({
                 assetId: entry.asset?.id ?? 0,
                 name: entry.asset?.name ?? "?",
-                creator: entry.creator?.name ?? "?",
-                approval: entry.voting?.upVotePercent ? `${entry.voting.upVotePercent}%` : "—",
-                hasScripts: entry.asset?.hasScripts ? "YES" : "no",
+                creator: (entry.creator?.name ?? "?") + (entry.creator?.isVerifiedCreator ? " ✓" : ""),
+                /*
+                 * Votes shown beside the percentage, never alone. "100%" is what two
+                 * friends upvoting looks like, and it sorts above a model used by
+                 * thousands unless the count is on screen next to it.
+                 */
+                approval: entry.voting?.upVotePercent !== undefined
+                    ? `${entry.voting.upVotePercent}% (${entry.voting.voteCount ?? 0})`
+                    : "—",
+                scripts: entry.asset?.hasScripts ? (entry.asset.scriptCount ?? "yes") : "no",
                 triangles: entry.asset?.modelTechnicalDetails?.objectMeshSummary?.triangles ?? "—",
+                free: entry.fiatProduct?.isFree === false ? "PAID" : "free",
+                kind: (entry.asset?.objectTypes ?? []).join("/") || "—",
+            }));
+            const risky = rows.filter((row) => row.scripts !== "no");
+            const paid = rows.filter((row) => row.free === "PAID");
+            const notes = [];
+            notes.push(`${found.items.length} shown of ${found.scanned} checked` +
+                (found.total !== undefined ? ` (${found.total} exist)` : "") +
+                "; ranked by approval weighted by vote count.");
+            if (risky.length > 0) {
+                notes.push(`${risky.length} contain scripts (${risky.map((r) => r.name).join(", ")}). ` +
+                    "Inserting one runs whatever its author put in it — use `peek` to read them " +
+                    "first, or pass excludeScripts.");
+            }
+            else {
+                notes.push("None of these contain scripts.");
+            }
+            if (paid.length > 0) {
+                notes.push(`${paid.length} are PAID and cannot simply be inserted: ${paid
+                    .map((r) => r.name)
+                    .join(", ")}.`);
+            }
+            return text(textOf(table(["assetId", "name", "creator", "approval", "scripts", "triangles", "free", "kind"], rows)) +
+                "\n\n" +
+                notes.join("\n"));
+        }
+        if (args.op === "quota") {
+            return json(await assetQuotas(await requireCredentials()));
+        }
+        if (args.op === "upload") {
+            if (!args.file) {
+                const { credentialStatus } = await import("../lib/credentials.js");
+                const status = await credentialStatus();
+                if (!status.hasKey || status.creatorId === null) {
+                    throw new ToolError("NO_CREDENTIALS", "No Open Cloud key is set up, so nothing can be uploaded.", "Ask the user to type `cloud` in the Studio panel \u2014 it walks " +
+                        "through creating the key and stores it safely. Never ask them " +
+                        "to paste a key into this conversation.");
+                }
+                return text(`Ready to upload: key set, uploading as ${status.creatorField} ` +
+                    `${status.creatorId}. Call again with \`file\`.`);
+            }
+            const credentials = await requireCredentials();
+            const uploaded = await uploadAsset(credentials, {
+                file: args.file,
+                name: args.name,
+                description: args.description,
+                assetType: args.assetType,
+            });
+            const assetId = String(uploaded["assetId"]);
+            const approved = uploaded["approved"] === true;
+            /*
+             * Only inserted once Roblox says it is approved. Putting a rejected
+             * asset into the place leaves an instance pointing at nothing, which
+             * reads as a bug here rather than as a moderation decision.
+             */
+            if (args.insertAs && approved) {
+                if (uploaded["assetType"] === "Audio") {
+                    uploaded["inserted"] = false;
+                    uploaded["note"] =
+                        "Audio is not inserted on its own \u2014 the id goes into an " +
+                            `AudioPlayer. Build one with \`audio op="graph" ` +
+                            `asset="rbxassetid://${assetId}"\`.`;
+                }
+                else if (uploaded["assetType"] === "Decal") {
+                    uploaded["inserted"] = await bridge.call("instances.create", {
+                        instances: [
+                            {
+                                className: "Decal",
+                                name: args.name ?? "Decal",
+                                parent: args.insertAs,
+                                properties: {
+                                    Texture: { value: `rbxassetid://${assetId}`, type: "ContentId" },
+                                },
+                            },
+                        ],
+                    }, { studioId: args.studioId, timeoutMs: 30_000 });
+                }
+                else {
+                    uploaded["inserted"] = await bridge.call("assets.insert", { assetId: Number(assetId), parent: args.insertAs }, { studioId: args.studioId, timeoutMs: 90_000 });
+                }
+            }
+            return json(uploaded, approved
+                ? `Use it as rbxassetid://${assetId}.`
+                : `Moderation says ${uploaded["moderation"]}. The id exists but may ` +
+                    "not load until review finishes.");
+        }
+        if (args.op === "grant") {
+            if (!args.assetIds || args.assetIds.length === 0) {
+                throw new ToolError("BAD_PARAMS", "grant needs `assetIds`.");
+            }
+            const subjectType = args.subjectType ?? "Universe";
+            const subjectId = subjectType === "Universe"
+                ? await requireUniverse(args.subjectId)
+                : args.subjectId;
+            if (!subjectId) {
+                throw new ToolError("BAD_PARAMS", `grant to a ${subjectType} needs a \`subjectId\`.`);
+            }
+            if (args.confirm !== true) {
+                throw new ToolError("NEEDS_CONFIRM", "Granting a game access to an asset is permanent.", "Roblox provides no way to revoke it. Pass confirm: true once you " +
+                    "are sure of the asset ids and the subject.");
+            }
+            const credentials = await requireCredentials();
+            return json(await grantAssets(credentials, {
+                assetIds: args.assetIds,
+                subjectType,
+                subjectId,
             }));
-            const risky = rows.filter((row) => row.hasScripts === "YES");
-            return text(textOf(table(["assetId", "name", "creator", "approval", "hasScripts", "triangles"], rows)) +
-                (risky.length > 0
-                    ? `\n\n${risky.length} of these contain scripts (${risky
-                        .map((r) => r.name)
-                        .join(", ")}). Inserting one runs whatever its author put in it — prefer a script-free model unless the scripts are the point.`
-                    : "\n\nNone of these contain scripts."));
+        }
+        if (args.op === "publish") {
+            if (!args.file)
+                throw new ToolError("BAD_PARAMS", "publish needs a `file` (.rbxl or .rbxlx).");
+            const credentials = await requireCredentials();
+            const universeId = await requireUniverse(args.universeId);
+            const placeId = await requirePlace(args.placeId);
+            const published = await publishPlace(credentials, {
+                file: args.file,
+                universeId,
+                placeId,
+                publish: args.confirm === true,
+            });
+            /*
+             * Restarting a version that was only SAVED would roll servers onto
+             * the version before it, which is the opposite of what was asked
+             * for. So the two flags are checked together rather than
+             * separately.
+             */
+            if (args.restart === true) {
+                published['restart'] =
+                    args.confirm === true
+                        ? await restartServers(credentials, {
+                            universeId,
+                            placeIds: [Number(placeId)],
+                        })
+                        : "Not restarted: the file was only saved, not published. A restart now would roll servers onto the PREVIOUS version.";
+            }
+            return json(published);
         }
         if (args.op === "bake") {
             if (!args.paths || args.paths.length === 0) {
@@ -366,6 +849,7 @@ export function registerWorldTools(context) {
             parent: args.parent,
             position: args.position,
             name: args.name,
+            stripScripts: args.stripScripts,
         }, 
         // Downloading an asset goes out to Roblox and back.
         { studioId: args.studioId, timeoutMs: 90_000 });
@@ -428,14 +912,108 @@ export function registerWorldTools(context) {
             "Groups are not undoable and not scoped to a session: `remove` when one " +
             "was created to try something and is no longer wanted, rather than " +
             "leaving it registered in the place indefinitely. The built-in " +
-            "\"Default\" group cannot be removed.",
+            "\"Default\" group cannot be removed.\n\n" +
+            "Groups belong to a world, not to the place. The Workspace is the " +
+            "default and is what nearly every question is about; a `WorldModel` " +
+            "inside a ViewportFrame keeps its own separate registry, so pass " +
+            "`worldModel` to reach that one. A group of the same name in each is " +
+            "two different groups.\n\n" +
+            "THE SAME TOOL ANSWERS WHAT IS ACTUALLY THERE. `cast` fires a ray, " +
+            "block or sphere and reports the first thing it meets — the part, the " +
+            "hit point, the surface normal, the material and the distance. " +
+            "`overlap` lists everything inside a box, a radius, or overlapping " +
+            "an existing part.\n\n" +
+            "That is the one question the Explorer cannot answer. A path tells " +
+            "you an instance exists and where its pivot sits; it does not tell " +
+            "you the door frame is clipping into the wall, that the spawn is " +
+            "buried a stud inside the floor, or that nothing stands between the " +
+            "turret and the player. Geometry wrong in exactly those ways looks " +
+            "perfect in `inspect`.\n\n" +
+            "The queries live here because they ARE collision queries: they " +
+            "honour the very groups the other half of this tool manages. A cast " +
+            "run in the wrong `collisionGroup` reports a clear path through a " +
+            "wall the player cannot walk through — a wrong answer " +
+            "indistinguishable from a right one. A miss comes back as " +
+            "`hit: false`, which is a real answer and usually the one being " +
+            "checked for.",
         inputSchema: {
             action: z
-                .enum(["list", "create", "assign", "collidable", "remove"])
+                .enum(["list", "create", "assign", "collidable", "remove", "cast", "overlap"])
                 .default("list")
-                .describe("'list' shows existing groups and changes nothing. 'remove' " +
-                "unregisters a group entirely — not the same as un-assigning " +
-                "parts from it."),
+                .describe("Groups: 'list' shows them and changes nothing, then 'create', " +
+                "'assign', 'collidable', 'remove' (which unregisters a group " +
+                "entirely — not the same as un-assigning parts). Queries: " +
+                "'cast' fires a shape and reports the first hit, 'overlap' " +
+                "lists what is inside a volume."),
+            shape: z
+                .enum(["ray", "block", "sphere"])
+                .optional()
+                .describe("cast only: 'ray' is a line and the usual choice. 'block' and " +
+                "'sphere' sweep a volume along the same path — use them when " +
+                "the thing moving has width, e.g. whether a character fits " +
+                "through a gap rather than whether a point does."),
+            from: z.string().optional().describe('cast only: where the cast starts, e.g. "12, 0, 5".'),
+            to: z
+                .string()
+                .optional()
+                .describe("cast only: a point to aim at. Use this for sightlines — it saves " +
+                "working out a direction vector, which is where sign errors live."),
+            direction: z
+                .string()
+                .optional()
+                .describe('cast only: which way to go, e.g. "0, -1, 0" for down. Used with `distance`.'),
+            distance: z
+                .number()
+                .optional()
+                .describe("cast only: how far along `direction`. Defaults to 100."),
+            size: z
+                .string()
+                .optional()
+                .describe('cast shape="block" or overlap region="box": the volume size.'),
+            radius: z
+                .number()
+                .optional()
+                .describe('cast shape="sphere" or overlap region="radius": the radius.'),
+            region: z
+                .enum(["box", "radius", "part"])
+                .optional()
+                .describe("overlap only: 'box' and 'radius' need `at`; 'part' takes " +
+                "`path` and reports what overlaps that part — the fastest way " +
+                "to find things clipping through each other. Defaults to 'box'."),
+            at: z.string().optional().describe('overlap only: the centre, for region "box" or "radius".'),
+            path: z.string().optional().describe('overlap region="part" only: the part to test against.'),
+            only: z
+                .array(z.string())
+                .optional()
+                .describe("cast/overlap: consider ONLY these instances and their descendants."),
+            ignore: z
+                .array(z.string())
+                .optional()
+                .describe("cast/overlap: skip these and their descendants. The usual case " +
+                "is the character doing the looking, which otherwise blocks its " +
+                "own cast at zero distance."),
+            collisionGroup: z
+                .string()
+                .optional()
+                .describe("cast/overlap: run the query as if from a part in this group. " +
+                "Required for a truthful answer in any place that uses groups."),
+            respectCanCollide: z
+                .boolean()
+                .optional()
+                .describe("cast/overlap: skip parts with CanCollide off. Off by default, " +
+                "matching the engine — leave it off to ask what is there, turn " +
+                "it on to ask what would stop a player."),
+            ignoreWater: z
+                .boolean()
+                .optional()
+                .describe("cast only: pass through terrain water instead of hitting it."),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(500)
+                .optional()
+                .describe("overlap only: how many parts to list. Defaults to 50."),
             group: z.string().optional().describe("The group's name. Required for everything but list."),
             paths: z
                 .array(z.string())
@@ -447,22 +1025,68 @@ export function registerWorldTools(context) {
                 .boolean()
                 .default(true)
                 .describe("collidable only: whether the two groups collide. False makes them pass through."),
+            worldModel: z
+                .string()
+                .optional()
+                .describe("Path to a WorldModel whose own collision groups this call is " +
+                "about, e.g. \"StarterGui.Preview.Viewport.WorldModel\". Omit " +
+                "for the Workspace, which is what you want unless the parts in " +
+                "question live inside a ViewportFrame."),
             studioId: z.string().optional().describe("Target Studio; omit for the active one."),
         },
         destructive: false,
     }, async (args) => {
+        if (args.action === "cast" || args.action === "overlap") {
+            const query = await bridge.call(args.action === "cast" ? "spatial.cast" : "spatial.overlap", {
+                shape: args.shape,
+                from: args.from,
+                to: args.to,
+                direction: args.direction,
+                distance: args.distance,
+                size: args.size,
+                radius: args.radius,
+                region: args.region,
+                at: args.at,
+                path: args.path,
+                only: args.only,
+                ignore: args.ignore,
+                collisionGroup: args.collisionGroup,
+                respectCanCollide: args.respectCanCollide,
+                ignoreWater: args.ignoreWater,
+                limit: args.limit,
+                worldModel: args.worldModel,
+            }, { studioId: args.studioId, timeoutMs: 30_000 });
+            if (args.action === "cast" && query["hit"] === false) {
+                return json(query, "Nothing was hit. If that is a surprise: a `direction` pointing " +
+                    "the wrong way, a `distance` shorter than the gap, or an " +
+                    "`only` filter excluding what you meant to find.");
+            }
+            return json(query);
+        }
         const response = await bridge.call("world.collision", {
             action: args.action,
             group: args.group,
             paths: args.paths,
             with: args.with,
             collidable: args.collidable,
+            worldModel: args.worldModel,
         }, { studioId: args.studioId });
         if (args.action === "list") {
             const groups = response.groups ?? [];
+            const where = response.world ?? "Workspace";
             if (groups.length === 0)
-                return text("No collision groups are registered.");
-            return text(textOf(table(["name", "mask"], groups)));
+                return text(`No collision groups are registered in ${where}.`);
+            return text(textOf(table(["name", "passes through", "mask"], groups.map((group) => ({
+                name: group.name,
+                "passes through": group.passesThrough ?? "?",
+                mask: group.mask,
+            })), {
+                // The ceiling is low enough to hit, and a caller registering
+                // groups in a loop has no other way to find out where it is.
+                more: response.max === undefined
+                    ? where
+                    : `${where}: ${groups.length} of ${response.max} groups used`,
+            })));
         }
         return json(response);
     });