@el4cteo/rbx-studio-mcp 0.1.0

package/dist/tools/instances.js

@@ -0,0 +1,261 @@
+import { z } from "zod";
+import { propertiesOf, suggestClass, suggestProperty } from "../lib/apidump.js";
+import { ToolError } from "../lib/errors.js";
+import { table } from "../lib/format.js";
+import { defineTool } from "../lib/tool.js";
+const propertyBag = z
+    .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
+    .optional()
+    .describe('Properties to set, as name → value. Values are written the way Studio\'s ' +
+    'Properties panel shows them: "12, 0, 5" for a Vector3, "0.2, 0.6, 1" for ' +
+    'a Color3, "Neon" or "Enum.Material.Neon" for an enum, true/false for a bool.');
+const attributeBag = z
+    .record(z.string(), z.union([z.string(), z.number(), z.boolean()]))
+    .optional()
+    .describe("Attributes to set, as name → value. An empty string removes one.");
+const tagSpec = z
+    .object({
+    add: z.array(z.string()).optional().describe("CollectionService tags to add."),
+    remove: z.array(z.string()).optional().describe("Tags to remove."),
+})
+    .optional()
+    .describe("CollectionService tags to add or remove.");
+/**
+ * Resolves each property to its declared type, refusing unknown ones.
+ *
+ * This is the reason the server holds a live API dump. A misspelled property
+ * would otherwise reach Studio, fail there, and come back as an engine message
+ * with no idea what was meant; here it is caught before the round trip and
+ * answered with the closest real names.
+ */
+async function resolveProperties(className, properties, where) {
+    if (!properties || Object.keys(properties).length === 0)
+        return undefined;
+    const known = await propertiesOf(className);
+    // No dump (offline, or a class too new for the cached copy) means passing the
+    // values through untyped is better than refusing work we cannot check.
+    if (known.length === 0)
+        return undefined;
+    const byName = new Map(known.map((property) => [property.name, property]));
+    const resolved = {};
+    for (const [name, value] of Object.entries(properties)) {
+        const info = byName.get(name);
+        if (!info) {
+            const suggestions = await suggestProperty(className, name);
+            throw new ToolError("UNKNOWN_PROPERTY", `${className} has no property "${name}" (${where}).`, suggestions.length > 0
+                ? `Did you mean: ${suggestions.join(", ")}?`
+                : `Call \`inspect\` with detail "full" on an existing ${className} to see ` +
+                    "its properties.");
+        }
+        resolved[name] = { value, type: info.valueType };
+    }
+    return resolved;
+}
+async function assertCreatable(className) {
+    const known = await propertiesOf(className);
+    if (known.length > 0)
+        return;
+    const suggestions = await suggestClass(className);
+    if (suggestions.length > 0) {
+        throw new ToolError("UNKNOWN_CLASS", `"${className}" is not a Roblox class.`, `Did you mean: ${suggestions.join(", ")}?`);
+    }
+}
+const createSpec = z.lazy(() => z.object({
+    parent: z
+        .string()
+        .optional()
+        .describe('Where to put it, e.g. "Workspace". Required at the top level only.'),
+    className: z
+        .string()
+        .describe('Concrete class to create, e.g. "Part", "Folder", "Model", "SpawnLocation".'),
+    name: z.string().optional().describe("Name for the new instance."),
+    properties: propertyBag,
+    attributes: attributeBag,
+    tags: tagSpec,
+    children: z
+        .array(createSpec)
+        .optional()
+        .describe("Instances to create inside this one. Build a whole model in one call " +
+        "rather than creating a parent and then addressing it by a path you " +
+        "have to guess."),
+}));
+/** Walks the create tree, replacing each property bag with typed specs. */
+async function typeCreateSpec(spec, where) {
+    await assertCreatable(spec.className);
+    return {
+        parent: spec.parent,
+        className: spec.className,
+        name: spec.name,
+        properties: await resolveProperties(spec.className, spec.properties, where),
+        attributes: spec.attributes,
+        tags: spec.tags,
+        children: spec.children
+            ? await Promise.all(spec.children.map((child, index) => typeCreateSpec(child, `${where} > ${spec.className}.children[${index}]`)))
+            : undefined,
+    };
+}
+function undoNote(response) {
+    return response.undoStep
+        ? `one undo step, "${response.undoStep}"`
+        : "Studio would not open an undo recording, so this is not undoable as one step";
+}
+export function registerInstanceTools(context) {
+    const { bridge } = context;
+    defineTool(context, {
+        name: "create",
+        title: "Create instances",
+        description: "Creates instances with their properties, attributes and tags set at " +
+            "creation, as one undoable step.\n\n" +
+            "Nest with `children` to build a whole model in a single call. That is " +
+            "both faster and safer than creating a parent and then addressing it: a " +
+            "new instance's path is not knowable until it exists, and same-named " +
+            "siblings make guessing it unreliable.\n\n" +
+            "Property names are checked against the live Roblox API dump before " +
+            "anything is sent to Studio, so a typo comes back with the closest real " +
+            "names rather than an engine error.\n\n" +
+            "Use `script_create` for Script, LocalScript and ModuleScript — it takes " +
+            "source directly.",
+        inputSchema: {
+            instances: z
+                .array(createSpec)
+                .min(1)
+                .max(100)
+                .describe("Instances to create together as one undoable step."),
+            studioId: z.string().optional().describe("Target Studio; omit for the active one."),
+        },
+    }, async (args) => {
+        const specs = await Promise.all(args.instances.map((spec, index) => typeCreateSpec(spec, `instances[${index}]`)));
+        const response = await bridge.call("instances.create", { instances: specs }, { studioId: args.studioId, timeoutMs: 30_000 });
+        return table(["path", "className"], response.items, { more: undoNote(response) });
+    });
+    defineTool(context, {
+        name: "modify",
+        title: "Modify instances",
+        description: "Sets properties, attributes and tags on existing instances, as one " +
+            "undoable step.\n\n" +
+            "Each entry takes a list of `paths`, so one entry can apply the same " +
+            "change to many instances — anchoring 200 parts is one entry, not 200. " +
+            "Combine with `find` to build the path list.\n\n" +
+            "The batch is all-or-nothing: if any value is rejected the recording is " +
+            "cancelled and every instance reverts, rather than leaving the place " +
+            "half-changed.\n\n" +
+            "Values use the same notation the Properties panel shows — see the " +
+            "`properties` field. To change a script's code use `script_edit`.",
+        inputSchema: {
+            targets: z
+                .array(z.object({
+                paths: z
+                    .array(z.string())
+                    .min(1)
+                    .describe('Instances to change, e.g. ["Workspace.Part[3]", "Workspace.Wall"].'),
+                properties: propertyBag,
+                attributes: attributeBag,
+                tags: tagSpec,
+            }))
+                .min(1)
+                .max(100)
+                .describe("Changes to apply together as one undoable step."),
+            studioId: z.string().optional().describe("Target Studio; omit for the active one."),
+        },
+        destructive: true,
+    }, async (args) => {
+        // Property types depend on each instance's actual class, which is only
+        // known once Studio answers, so classes are probed first — the same
+        // two-pass shape `inspect` uses.
+        const needsTypes = args.targets.some((target) => target.properties && Object.keys(target.properties).length > 0);
+        let targets = args.targets;
+        if (needsTypes) {
+            const probe = await bridge.call("discover.inspect", { paths: args.targets.flatMap((target) => target.paths), includeChildren: false }, { studioId: args.studioId });
+            // Correlated on the path we asked about, not the one that came back. The
+            // canonical path carries an index where a name is shared, so matching on
+            // it silently found nothing for exactly the ambiguous paths that most
+            // need checking — and the properties were then dropped without a word.
+            const classOf = new Map(probe.items.map((item) => [item.requested ?? item.path, item.className]));
+            targets = await Promise.all(args.targets.map(async (target, index) => {
+                if (!target.properties)
+                    return target;
+                const classes = [
+                    ...new Set(target.paths.map((path) => classOf.get(path)).filter(Boolean)),
+                ];
+                if (classes.length === 0) {
+                    throw new ToolError("UNRESOLVED_TARGET", `Could not read the class of any path in targets[${index}].`, "Check the paths with `find` or `tree`. Properties are typed from " +
+                        "the class, so nothing was changed rather than guessing.");
+                }
+                // Paths in one entry can span classes and the property must exist on
+                // every one, so each is checked. The types agree across classes that
+                // share a property, so the last resolution stands for all of them.
+                let properties;
+                for (const className of classes) {
+                    properties = await resolveProperties(className, target.properties, `targets[${index}]`);
+                }
+                return { ...target, properties };
+            }));
+        }
+        const response = await bridge.call("instances.modify", { targets }, { studioId: args.studioId, timeoutMs: 30_000 });
+        return table(["path", "className", "changed"], response.items, {
+            more: undoNote(response),
+        });
+    });
+    defineTool(context, {
+        name: "delete",
+        title: "Delete instances",
+        description: "Destroys instances and everything inside them, as one undoable step.\n\n" +
+            "Deleting a container deletes its whole subtree, so the response reports " +
+            "how many descendants went with each one — check it before telling the " +
+            "user what happened.\n\n" +
+            "Services cannot be deleted and are refused. Paths shift when same-named " +
+            "siblings are removed, so read fresh paths from `find` or `tree` before a " +
+            "second delete rather than reusing indexes from an earlier call.",
+        inputSchema: {
+            paths: z
+                .array(z.string())
+                .min(1)
+                .max(200)
+                .describe('Instances to destroy, e.g. ["Workspace.OldModel"].'),
+            studioId: z.string().optional().describe("Target Studio; omit for the active one."),
+        },
+        destructive: true,
+    }, async (args) => {
+        const response = await bridge.call("instances.delete", { paths: args.paths }, { studioId: args.studioId, timeoutMs: 30_000 });
+        return table(["path", "className", "descendants"], response.items, {
+            more: undoNote(response),
+        });
+    });
+    defineTool(context, {
+        name: "move",
+        title: "Move or clone instances",
+        description: "Reparents instances, or clones them into a new parent, as one undoable " +
+            "step.\n\n" +
+            'Set `mode: "clone"` to copy instead of move — that is how to duplicate ' +
+            "something, optionally renaming it in the same call.\n\n" +
+            "Moving an instance into itself or its own descendant is refused: it " +
+            "silently detaches the branch from the data model and undo does not " +
+            "bring it back.",
+        inputSchema: {
+            items: z
+                .array(z.object({
+                path: z.string().describe("Instance to move or clone."),
+                to: z.string().describe("New parent's path."),
+                mode: z
+                    .enum(["move", "clone"])
+                    .default("move")
+                    .describe("'move' reparents the original; 'clone' leaves it and copies."),
+                name: z
+                    .string()
+                    .optional()
+                    .describe("Rename it as part of the same step. Useful with clone."),
+            }))
+                .min(1)
+                .max(200)
+                .describe("Moves to apply together as one undoable step."),
+            studioId: z.string().optional().describe("Target Studio; omit for the active one."),
+        },
+        destructive: true,
+    }, async (args) => {
+        const response = await bridge.call("instances.move", { items: args.items }, { studioId: args.studioId, timeoutMs: 30_000 });
+        return table(["path", "className", "cloned"], response.items, {
+            more: undoNote(response),
+        });
+    });
+}
+//# sourceMappingURL=instances.js.map

package/dist/tools/instances.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instances.js","sourceRoot":"","sources":["../../src/tools/instances.ts"],"names":[],"mappings":"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"}

package/dist/tools/perf.js

@@ -0,0 +1,367 @@
+import { z } from "zod";
+import { json, limitSchema, table, text, textOf } from "../lib/format.js";
+import { defineTool } from "../lib/tool.js";
+/**
+ * Whether a profiler frame belongs to a Studio plugin rather than to the place.
+ *
+ * `IsPlugin` looks like the answer and is not enough on its own: the engine sets
+ * it only on a plugin's nameless root frame, never on the frames underneath that
+ * carry the actual `Source` and the actual time. Filtering on it alone therefore
+ * strips one zero-cost row per plugin and lets every line of plugin work through
+ * -- measured, and the result was this server's own console animation sitting at
+ * the top of a profile of somebody else's game.
+ *
+ * The source prefix is the reliable signal. Plugins load from the Creator Store
+ * as `cloud_<assetId>.`, from a local file as `user_<file>.rbxmx.`, and ship with
+ * Studio as `builtin_`; a place's own scripts are named by their data model path.
+ */
+function isPluginFrame(entry) {
+    if (entry.IsPlugin === true) {
+        return true;
+    }
+    return /^(cloud_|user_|builtin_)/.test(entry.Source ?? "");
+}
+export function registerPerfTools(context) {
+    const { bridge } = context;
+    defineTool(context, {
+        name: "console",
+        title: "Read Studio output",
+        description: "Reads the Studio Output window — prints, warnings and runtime errors, " +
+            "newest last.\n\n" +
+            "This is how to find out what actually happened after a playtest or an " +
+            "`execute_luau` call. An error here usually names the script and line, " +
+            "which `script_read` can then open directly.\n\n" +
+            "Filter with `level` to see only errors, or `pattern` to follow one " +
+            "subsystem's logging. Up to 2000 lines are held, so prefer a filter over " +
+            "a large `limit`.\n\n" +
+            "Each connected session keeps its own log, recorded from the moment its " +
+            "plugin loaded — the editor session and a running playtest server do not " +
+            "share one. To read what a playtest printed, target the playtest's " +
+            "studioId (see `list_studios`); the editor's log will not have it. " +
+            "Nothing printed before the plugin loaded is recoverable, and output from " +
+            "the playtest *client* is not reachable at all, because Studio forbids " +
+            "client sessions from making HTTP requests.",
+        inputSchema: {
+            level: z
+                .enum(["print", "info", "warning", "error"])
+                .optional()
+                .describe("Only this severity. Omit for everything."),
+            pattern: z
+                .string()
+                .optional()
+                .describe('Lua pattern the message must match, e.g. "Combat" or "^%[Server%]". ' +
+                "Lua patterns escape with %, not backslash."),
+            limit: limitSchema,
+            studioId: z.string().optional().describe("Target Studio; omit for the active one."),
+        },
+        readOnly: true,
+    }, async (args) => {
+        const response = await bridge.call("perf.console", { level: args.level, pattern: args.pattern, limit: args.limit }, { studioId: args.studioId });
+        if (response.items.length === 0) {
+            // "Empty" on its own is ambiguous, and the ambiguity is the whole
+            // problem: in a playtest the plugin starts recording at the same moment
+            // the place's own scripts run, so anything logged during startup can be
+            // missed. Saying how long the window has been open lets the reader tell
+            // "nothing was logged" from "recording started after the event".
+            const window = response.recordingSeconds !== undefined
+                ? ` This session has been recording for ${response.recordingSeconds}s, ` +
+                    "since its plugin loaded; anything logged before that is not recoverable."
+                : "";
+            return text((args.level || args.pattern
+                ? "No output matched. Try dropping the filter, or run a playtest first."
+                : "Nothing has been logged in this session.") + window);
+        }
+        // An error's stack trace is indented under it rather than given its own
+        // line, so the association survives being skimmed and the trace does not
+        // read as further unrelated output.
+        const lines = response.items.map((entry) => {
+            const head = `[${entry.level}] ${entry.message}`;
+            if (!entry.stack)
+                return head;
+            const trace = entry.stack
+                .split("\n")
+                .map((line) => line.trim())
+                .filter((line) => line.length > 0)
+                .map((line) => `    at ${line}`)
+                .join("\n");
+            const origin = entry.source ? `\n    in ${entry.source}` : "";
+            return trace ? `${head}${origin}\n${trace}` : `${head}${origin}`;
+        });
+        const notes = [];
+        if (response.dropped > 0) {
+            notes.push(`showing the newest ${response.items.length} of ${response.total} matching lines`);
+        }
+        // A different loss from the one above, and the only one worth acting on:
+        // these lines are gone from the session entirely, not merely unshown.
+        if (response.evicted) {
+            notes.push(`${response.evicted} older lines have fallen out of the buffer and cannot be recovered`);
+        }
+        const trailer = notes.length > 0 ? `\n\n[${notes.join("; ")}]` : "";
+        return text(lines.join("\n") + trailer);
+    });
+    defineTool(context, {
+        name: "performance",
+        title: "Performance and memory",
+        description: "Reads the engine's own counters, and can run the script profiler.\n\n" +
+            "`snapshot` returns what the Developer Console shows: frame, physics and " +
+            "render times in milliseconds, instance and part counts, draw calls, " +
+            "network rates, and memory broken down by category. Use it to answer " +
+            "'why is this place heavy' with numbers instead of guesses.\n\n" +
+            "`profile` runs Studio's script profiler — the Script Performance window " +
+            "— for `seconds` and reports which scripts consumed CPU. It blocks for " +
+            "that long, so keep it short. It only sees code that actually runs, so " +
+            "start a playtest first; profiling an idle edit session returns nothing.\n\n" +
+            "`coverage` reports which lines of which scripts actually executed — dead " +
+            "code, untested branches, whether a fix was even reached. Pass `enable` " +
+            "first, then play, then read the coverage back FROM THE PLAYTEST session, " +
+            "not the editor: instrumenting is per data model, and the playtest is a " +
+            "different one. `enable` is remembered for the place and re-applied by " +
+            "each new session as it loads. Pass an empty `enable` array to stop.\n\n" +
+            "What it can and cannot see: instrumentation is fixed when a script is " +
+            "first compiled, so it measures modules required after that point — where " +
+            "most game logic lives — but never a script that starts with the place, " +
+            "which the data model compiles before any plugin exists. Those report 0 " +
+            "lines and are named as unmeasurable rather than counted as dead code.\n\n" +
+            "`scene` breaks the place down by what it is actually made of: instances " +
+            "by category, triangles and draw calls, and the assets holding script, " +
+            "animation and audio memory — each named, so \"2.4GB of memory\" becomes " +
+            "\"this animation is 138KB and these are the Animators using it\". It also " +
+            "reports UNPARENTED INSTANCES, which is the closest thing here to a leak " +
+            "detector: objects still alive with nothing holding them in the tree, " +
+            "invisible to `find` and to `tree` because they are in neither.\n\n" +
+            "Frame and network figures are only meaningful while something is " +
+            "running. Instance counts and memory are useful in edit mode too.",
+        inputSchema: {
+            op: z
+                .enum(["snapshot", "profile", "coverage", "scene"])
+                .default("snapshot")
+                .describe("'snapshot' reads counters now; 'profile' samples running scripts; " +
+                "'coverage' reports which lines have executed; 'scene' breaks the " +
+                "place down by what it is made of."),
+            section: z
+                .enum([
+                "composition",
+                "triangles",
+                "scriptMemory",
+                "animationMemory",
+                "audioMemory",
+                "unparented",
+            ])
+                .optional()
+                .describe("scene only: return just one section instead of all six."),
+            enable: z
+                .array(z.string())
+                .optional()
+                .describe("coverage only: scripts to start measuring. Remembered for this place " +
+                "and switched on by every session that loads afterwards, so a " +
+                "playtest instruments them before its scripts run. An empty array " +
+                "stops instrumenting."),
+            seconds: z
+                .number()
+                .int()
+                .min(1)
+                .max(30)
+                .default(5)
+                .describe("profile only: how long to sample. The call blocks for this long."),
+            frequency: z
+                .number()
+                .int()
+                .min(100)
+                .max(10000)
+                .default(1000)
+                .describe("profile only: samples per second. Higher is more precise and costlier."),
+            includePlugins: z
+                .boolean()
+                .default(false)
+                .describe("profile only: include Studio plugins in the results. Off by default " +
+                "— an idle Studio is mostly plugin activity, which buries the " +
+                "place's own scripts."),
+            studioId: z.string().optional().describe("Target Studio; omit for the active one."),
+        },
+        readOnly: true,
+    }, async (args) => {
+        if (args.op === "coverage") {
+            const response = await bridge.call("perf.coverage", { enable: args.enable }, { studioId: args.studioId });
+            if (response.raw !== undefined) {
+                return json(response.raw, "Coverage came back in an unrecognised shape, so it is shown as Studio " +
+                    "returned it rather than summarised into numbers that might be wrong.");
+            }
+            if (response.scripts.length === 0) {
+                return text((response.enabled.length > 0
+                    ? `Coverage enabled for ${response.enabled.length} script(s). `
+                    : "") +
+                    "No coverage recorded yet.\n" +
+                    "Coverage is recorded per session. If the code runs in a playtest, " +
+                    "read it back from the playtest's studioId — the editor session " +
+                    "instruments its own data model and never ran that code.\n" +
+                    `This session carried over: ${JSON.stringify(response.carriedOver ?? [])}; ` +
+                    `failed: ${JSON.stringify(response.carriedFailed ?? [])}; ` +
+                    `remembered: ${JSON.stringify(response.remembered ?? [])}.`);
+            }
+            const summary = textOf(table(["path", "coveredLines", "instrumentedLines", "percent"], response.scripts, { more: "instrumented lines only; blanks, comments and `end` are excluded" }));
+            // The percentage says how much ran; these say what did not, which is the
+            // thing anyone measuring coverage is actually looking for.
+            const misses = response.scripts
+                .filter((entry) => entry.uncoveredLines && entry.uncoveredLines.length > 0)
+                .map((entry) => `  ${entry.path}: ${entry.uncoveredLines.join(", ")}`);
+            // Reported separately from a genuine zero, because they look identical
+            // in the table and mean opposite things.
+            const unmeasured = response.scripts.filter((entry) => entry.notMeasurable);
+            const sections = [summary];
+            // An empty `enable` clears what future sessions instrument; it cannot
+            // un-instrument this one, because Luau binds coverage at first compile.
+            // Without saying so, the call looks like it did nothing at all -- it
+            // returns the same table it returned before being asked to stop.
+            if (args.enable !== undefined && args.enable.length === 0) {
+                sections.push("Coverage will not be switched on for this place again. The figures " +
+                    "above are from scripts this session already instrumented, which " +
+                    "keep reporting until it ends — instrumentation is fixed at first " +
+                    "compile and cannot be removed.");
+            }
+            if (misses.length > 0)
+                sections.push(`Lines never executed:\n${misses.join("\n")}`);
+            if (unmeasured.length > 0) {
+                sections.push(`Not measurable, reported as 0 lines: ${unmeasured.map((e) => e.path).join(", ")}.\n` +
+                    "These were already compiled when coverage was switched on, and Luau " +
+                    "keeps its first bytecode — re-running them does not help. This is " +
+                    "normal for a script that starts with the place, since nothing can " +
+                    "instrument it before the data model loads it. Coverage measures " +
+                    "modules required after instrumentation, which is where most game " +
+                    "logic lives.");
+            }
+            return text(sections.join("\n\n"));
+        }
+        if (args.op === "scene") {
+            const response = await bridge.call("perf.scene", { section: args.section }, { studioId: args.studioId, timeoutMs: 45_000 });
+            const blocks = [];
+            // Fixed order. Object key order comes back however the JSON happened to
+            // serialise, which put "unparented — 0" above the composition breakdown
+            // and made the report read differently between identical calls.
+            const ORDER = [
+                "composition",
+                "triangles",
+                "scriptMemory",
+                "animationMemory",
+                "audioMemory",
+                "unparented",
+            ];
+            const ordered = Object.entries(response).sort(([a], [b]) => ORDER.indexOf(a) - ORDER.indexOf(b));
+            for (const [name, section] of ordered) {
+                if (section.error !== undefined) {
+                    blocks.push(`${name}: unavailable (${section.error})`);
+                    continue;
+                }
+                const count = (value, unit) => `${value} ${value === 1 ? unit.replace(/s$/, "") : unit}`;
+                const heading = section.totals !== undefined
+                    ? `${name} — ${Object.entries(section.totals)
+                        .map(([key, value]) => count(value, key.toLowerCase()))
+                        .join(", ")}`
+                    : `${name} — ${count(section.total ?? 0, section.unit)}`;
+                if (section.entries.length === 0) {
+                    // A total with no breakdown is not the same as nothing at all, and
+                    // saying "(nothing)" under "90006 bytes" contradicts the line above
+                    // it. Script memory does this: the engine reports the total without
+                    // attributing it to named assets the way animation memory does.
+                    blocks.push(`${heading}\n  ${(section.total ?? 0) > 0
+                        ? "(counted, but the engine did not break it down)"
+                        : "(nothing)"}`);
+                    continue;
+                }
+                // 120, not 40. These entries are a two-level tree of categories, not a
+                // ranked list, so cutting it drops whole categories rather than the
+                // least interesting tail — the first version hid twelve of them.
+                const shown = section.entries.slice(0, 120);
+                const rows = shown
+                    .map((entry) => {
+                    const indent = "  ".repeat(entry.depth);
+                    const size = entry.size !== undefined
+                        ? ` — ${count(entry.size, section.unit)}`
+                        : entry.triangles !== undefined
+                            ? ` — ${count(entry.triangles, "triangles")}, ${count(entry.drawcalls ?? 0, "draw calls")}`
+                            : "";
+                    // Owners are what turn a number into something actionable: the
+                    // asset's size says how much, the owners say who to go and look at.
+                    const owners = entry.owners && entry.owners.length > 0
+                        ? `\n${indent}    used by ${entry.owners.slice(0, 3).join(", ")}`
+                        : "";
+                    return `${indent}${entry.name}${size}${owners}`;
+                })
+                    .join("\n");
+                const dropped = section.entries.length - shown.length;
+                blocks.push(`${heading}\n${rows}${dropped > 0 ? `\n  (${dropped} more)` : ""}`);
+            }
+            return text(blocks.join("\n\n"));
+        }
+        if (args.op === "profile") {
+            const response = await bridge.call("perf.profile", { seconds: args.seconds, frequency: args.frequency }, 
+            // The plugin blocks for the sample, so the deadline must outlast it.
+            { studioId: args.studioId, timeoutMs: (args.seconds + 20) * 1_000 });
+            const functions = response.data?.Functions ?? [];
+            if (functions.length === 0) {
+                return text(`Nothing ran during the ${response.seconds}s sample.\n` +
+                    "The profiler only sees code that executes. Start a playtest, or " +
+                    "profile while the behaviour you are investigating is happening.");
+            }
+            const ranked = [...functions]
+                .sort((a, b) => (b.TotalDuration ?? 0) - (a.TotalDuration ?? 0))
+                // A frame with no Source is a root entry -- one per script, carrying
+                // that script's total and duplicating the sourced frame directly under
+                // it. Dropping them removes the duplicate rows, and with them the only
+                // frames the engine bothers to mark IsPlugin.
+                .filter((entry) => entry.Source !== undefined)
+                .filter((entry) => (args.includePlugins ? true : !isPluginFrame(entry)))
+                .slice(0, 25)
+                .map((entry) => ({
+                source: entry.Source ?? "(engine)",
+                name: entry.Name ?? "",
+                line: entry.Line || "",
+                ms: Math.round((entry.TotalDuration ?? 0) * 1000 * 1000) / 1000,
+                plugin: isPluginFrame(entry) ? "yes" : "",
+            }));
+            if (ranked.length === 0) {
+                return text(`Every sample in ${response.seconds}s came from Studio plugins, not ` +
+                    "from this place's scripts.\n" +
+                    "No game code consumed measurable CPU. Pass `includePlugins` to see " +
+                    "the plugin activity anyway.");
+            }
+            return table(["source", "name", "line", "ms", "plugin"], ranked, {
+                more: `sampled ${response.seconds}s at ${response.frequency}Hz, ` +
+                    `slowest first, ms is total time in that function`,
+            });
+        }
+        const snapshot = await bridge.call("perf.snapshot", {}, { studioId: args.studioId });
+        // Memory is the one part that is a genuine list, and the part most often
+        // scanned for an outlier, so it gets a table instead of nested JSON.
+        const categories = snapshot.memory.categories.slice(0, 15);
+        const parts = [
+            textOf(json({
+                frame: snapshot.frame,
+                scene: snapshot.scene,
+                network: snapshot.network,
+                totalMemoryMb: snapshot.memory.totalMb,
+            })),
+        ];
+        if (categories.length > 0) {
+            parts.push("\nMemory by category (MB):\n" +
+                textOf(table(["category", "megabytes"], categories)));
+        }
+        else {
+            // An absent breakdown beside a healthy total reads as "this place uses
+            // no memory", so say which of the two reasons it is.
+            parts.push(snapshot.memory.trackingEnabled === false
+                ? "\n[No memory breakdown: Stats.MemoryTrackingEnabled is off in this session.]"
+                : `\n[No memory breakdown: ${snapshot.memory.problem ?? "Studio returned an empty one."}]`);
+        }
+        // Zeroes that mean "not measured here" look exactly like zeroes that mean
+        // "nothing to draw", and the flattering reading is the wrong one.
+        if (snapshot.renderless) {
+            parts.push("\n[This is a playtest server, which does not render: frame time, draw " +
+                "calls and triangle counts read zero because nothing measures them, " +
+                "not because the place is cheap. Physics, instance counts, network " +
+                "and memory above are real. For rendering figures, snapshot the " +
+                "editor session instead.]");
+        }
+        return text(parts.join("\n"));
+    });
+}
+//# sourceMappingURL=perf.js.map