@el4cteo/rbx-studio-mcp 0.6.1 → 0.6.7

package/plugin/src/handlers/World.luau

@@ -18,15 +18,21 @@
 local ChangeHistoryService = game:GetService("ChangeHistoryService")
 
 --[[
-	Collision groups are read and written through the Workspace, not PhysicsService.
+	Collision groups are read and written through a WorldRoot, not PhysicsService.
 
 	Roblox moved collision group management onto WorldRoot in September 2026 and
 	deprecated the PhysicsService methods in the same announcement. Both still
-	work today -- checked against Studio 0.737 -- so this is a migration ahead of
-	a removal rather than a fix. The move also means a WorldModel gets its own
-	groups instead of sharing the Workspace's, which is the point of it.
+	work today -- checked against Studio 0.738 -- so this is a migration ahead of
+	a removal rather than a fix.
+
+	The move is not only a rename. A `WorldModel` is a WorldRoot too, and it now
+	keeps its OWN registry: a group named "Doors" inside a viewport's WorldModel
+	is a different group from the Workspace's "Doors", with its own collidability
+	matrix. Going through `PhysicsService` -- or hard-coding `workspace` here --
+	can only ever reach one of them, which would quietly make this tool lie about
+	a place that uses both. So the root is chosen per call; see `root`.
 ]]
-local CollisionGroups = workspace
+local Workspace = game:GetService("Workspace")
 
 local Dispatch = require(script.Parent.Parent.Dispatch)
 local Paths = require(script.Parent.Parent.Paths)
@@ -34,6 +40,33 @@ local Undo = require(script.Parent.Parent.Undo)
 
 local World = {}
 
+--[[
+	Which world the call is about.
+
+	Defaults to the Workspace, which is what nearly every caller means. Naming a
+	`worldModel` path targets that model's private registry instead -- the
+	viewport-preview case -- and anything that is not a WorldRoot is refused by
+	name rather than left to fail later inside `RegisterCollisionGroup` with a
+	message about a method that does not exist.
+]]
+local function root(params: { [string]: any }): Instance
+	local path = params.worldModel
+	if typeof(path) ~= "string" or path == "" then
+		return Workspace
+	end
+
+	local instance = Paths.resolve(path)
+	if not instance:IsA("WorldRoot") then
+		Dispatch.fail(
+			"BAD_PARAMS",
+			string.format("%s is a %s, not a WorldModel.", path, instance.ClassName),
+			"Collision groups live on a WorldRoot: the Workspace, or a WorldModel "
+				.. "inside a ViewportFrame. Omit `worldModel` for the Workspace."
+		)
+	end
+	return instance
+end
+
 --[[
 	Steps the undo stack.
 
@@ -101,18 +134,59 @@ end
 ]]
 function World.collision(params: { [string]: any }): { [string]: any }
 	local action = tostring(params.action or "list")
+	local world = root(params) :: any
 
 	if action == "list" then
 		local groups: { { [string]: any } } = {}
 		local ok, registered = pcall(function()
-			return CollisionGroups:GetRegisteredCollisionGroups()
+			return world:GetRegisteredCollisionGroups()
 		end)
 		if ok and typeof(registered) == "table" then
+			--[[
+				Named pairs, not the raw mask.
+
+				`mask` is the engine's bitfield, and it is not readable: a group
+				that passes through only itself reports -3, which says nothing to
+				anyone without a calculator and the group ordering to hand. The
+				whole reason a collision group exists is "these two do not
+				collide", so that is what is listed -- by name, both ways round,
+				which is the answer the caller came for.
+
+				The mask is kept beside it, because a caller comparing against
+				something they stored earlier still needs the number.
+			]]
 			for _, group in registered :: { any } do
-				table.insert(groups, { name = group.name, mask = group.mask })
+				local passesThrough: { string } = {}
+				for _, other in registered :: { any } do
+					local okPair, collides = pcall(function()
+						return world:CollisionGroupsAreCollidable(group.name, other.name)
+					end)
+					if okPair and collides == false then
+						table.insert(passesThrough, other.name)
+					end
+				end
+				table.sort(passesThrough)
+				table.insert(groups, {
+					name = group.name,
+					mask = group.mask,
+					passesThrough = if #passesThrough > 0 then table.concat(passesThrough, ", ") else "nothing",
+				})
 			end
 		end
-		return { groups = groups }
+		--[[
+			The ceiling is reported alongside the groups because it is low --
+			32 in practice -- and a caller building groups programmatically has
+			no other way to learn it before the registration that fails.
+		]]
+		local limit: number? = nil
+		local okLimit, maximum = pcall(function()
+			return world:GetMaxCollisionGroups()
+		end)
+		if okLimit then
+			limit = tonumber(maximum)
+		end
+
+		return { groups = groups, world = Paths.of(world), count = #groups, max = limit }
 	end
 
 	local name = params.group
@@ -122,7 +196,7 @@ function World.collision(params: { [string]: any }): { [string]: any }
 
 	if action == "create" then
 		local ok, err = pcall(function()
-			CollisionGroups:RegisterCollisionGroup(name)
+			world:RegisterCollisionGroup(name)
 		end)
 		if not ok then
 			-- Already existing is the common case and is not a failure worth
@@ -131,7 +205,7 @@ function World.collision(params: { [string]: any }): { [string]: any }
 				Dispatch.fail("COLLISION_FAILED", string.format("Could not create %q: %s", name, tostring(err)))
 			end
 		end
-		return { group = name, created = ok, existed = not ok }
+		return { group = name, created = ok, existed = not ok, world = Paths.of(world) }
 	end
 
 	if action == "assign" then
@@ -154,7 +228,7 @@ function World.collision(params: { [string]: any }): { [string]: any }
 				end
 			end
 		end)
-		return { group = name, assigned = #assigned, parts = assigned, undoable = undoable }
+		return { group = name, assigned = #assigned, parts = assigned, undoable = undoable, world = Paths.of(world) }
 	end
 
 	if action == "remove" then
@@ -168,12 +242,12 @@ function World.collision(params: { [string]: any }): { [string]: any }
 			has existed the whole time; it was just never wired up.
 		]]
 		local ok, err = pcall(function()
-			CollisionGroups:UnregisterCollisionGroup(name)
+			world:UnregisterCollisionGroup(name)
 		end)
 		if not ok then
 			Dispatch.fail("COLLISION_FAILED", string.format("Could not remove %q: %s", name, tostring(err)))
 		end
-		return { group = name, removed = true }
+		return { group = name, removed = true, world = Paths.of(world) }
 	end
 
 	if action == "collidable" then
@@ -183,12 +257,12 @@ function World.collision(params: { [string]: any }): { [string]: any }
 		end
 		local collidable = params.collidable ~= false
 		local ok, err = pcall(function()
-			CollisionGroups:CollisionGroupSetCollidable(name, other, collidable)
+			world:CollisionGroupSetCollidable(name, other, collidable)
 		end)
 		if not ok then
 			Dispatch.fail("COLLISION_FAILED", string.format("Could not set collidability: %s", tostring(err)))
 		end
-		return { group = name, with = other, collidable = collidable }
+		return { group = name, with = other, collidable = collidable, world = Paths.of(world) }
 	end
 
 	Dispatch.fail("BAD_PARAMS", string.format("unknown collision action %q", action))

package/plugin/src/init.server.luau

@@ -30,6 +30,8 @@ local Geometry = require(script.handlers.Geometry)
 local Generate = require(script.handlers.Generate)
 local Terrain = require(script.handlers.Terrain)
 local World = require(script.handlers.World)
+local Spatial = require(script.handlers.Spatial)
+local Audio = require(script.handlers.Audio)
 local Discover = require(script.handlers.Discover)
 local Exec = require(script.handlers.Exec)
 local Instances = require(script.handlers.Instances)
@@ -38,6 +40,8 @@ local Playtest = require(script.handlers.Playtest)
 local Viewport = require(script.handlers.Viewport)
 local Input = require(script.handlers.Input)
 local Device = require(script.handlers.Device)
+local Data = require(script.handlers.Data)
+local Anim = require(script.handlers.Anim)
 local Api = require(script.handlers.Api)
 local Scripts = require(script.handlers.Scripts)
 local Session = require(script.handlers.Session)
@@ -176,11 +180,15 @@ Geometry.register()
 Generate.register()
 Terrain.register()
 World.register()
+Spatial.register()
+Audio.register()
 Exec.register()
 Viewport.register()
 Scripts.register()
 Input.register()
 Device.register()
+Data.register()
+Anim.register()
 Api.register()
 
 --[[
@@ -698,7 +706,7 @@ local function onCommand(id: string, op: string, params: { [string]: any }?)
 		]]
 		Transport.sendResult(result)
 
-		local elapsed = string.format("%.0fms", milliseconds)
+		local elapsed = Console.durationText(milliseconds)
 		Console.recordCall(result.ok, milliseconds)
 
 		if result.ok then

package/scripts/build-plugin.mjs

@@ -17,6 +17,19 @@ const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const sourceDir = join(root, "plugin", "src");
 const outputPath = resolve(process.argv[2] ?? join(root, "build", "StudioMCP.rbxmx"));
 
+/**
+ * The package's version, stamped into the plugin the same way the build id is.
+ *
+ * `Config.PLUGIN_VERSION` used to be a literal that someone had to remember to
+ * edit alongside package.json, and nothing checked. A release that bumped the
+ * package and not the literal shipped a plugin reporting the previous version
+ * in its own `version` and `status` output, in `list_studios`, and in the
+ * mismatch warnings the server prints when a plugin looks out of date -- which
+ * is the one place a wrong version number does real damage, because it is read
+ * as evidence about which build is running.
+ */
+const packageVersion = JSON.parse(readFileSync(join(root, "package.json"), "utf8")).version;
+
 const NEWLINE = "\n";
 
 /**
@@ -121,6 +134,13 @@ function buildTree(dir, name) {
       // Stamped with the fingerprint of the pre-injection sources, which is
       // exactly what the server recomputes at runtime.
       source = source.replace('Config.BUILD_ID = "dev"', `Config.BUILD_ID = "${stamp}"`);
+      // The literal in the source is the fallback for anyone loading
+      // plugin/src directly through Rojo; a built plugin always carries the
+      // package's own version.
+      source = source.replace(
+        /Config\.PLUGIN_VERSION = "[^"]*"/,
+        `Config.PLUGIN_VERSION = "${packageVersion}"`,
+      );
     }
 
     if (entry.name === "init.server.luau") {

package/scripts/check-plugin.mjs

@@ -1,125 +1,172 @@
-/**
- * Compiles every plugin source file, so a broken one is caught here rather than
- * in Studio.
- *
- * This exists because the feedback loop without it is terrible. Nothing in the
- * Node build reads the Luau at all -- `build:plugin` packs the files into an
- * .rbxmx as text -- so a syntax error ships, installs, and is only discovered
- * when the user focuses Studio and the plugin fails to load. It cost two
- * sessions in one afternoon: a literal newline written into a string where an
- * escape was meant, and a closure that captured a nil global because it sat
- * above the forward declaration of the local it meant to call. The first is a
- * compile error and would have been caught instantly by this. The second is not,
- * which is why `--!strict` analysis runs too when the analyser is available:
- * an unknown global is exactly what it flags.
- *
- * Needs `luau-compile` (and ideally `luau-analyze`) on PATH, in ./tools, or
- * named by the LUAU_COMPILE / LUAU_ANALYZE environment variables. Get them from
- * https://github.com/luau-lang/luau/releases.
- *
- * Silent and exit 0 when everything compiles; prints what failed otherwise.
- *
- * Usage: node scripts/check-plugin.mjs
- */
-import { spawnSync } from "node:child_process";
-import { readdirSync, statSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { locateLuau, missingLuau } from "./locate-luau.mjs";
-
-const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-
-function luauFiles(directory) {
-  const found = [];
-  for (const entry of readdirSync(directory)) {
-    const path = join(directory, entry);
-    if (statSync(path).isDirectory()) found.push(...luauFiles(path));
-    else if (entry.endsWith(".luau")) found.push(path);
-  }
-  return found;
-}
-
-const compiler = locateLuau("LUAU_COMPILE", ["luau-compile.exe", "luau-compile"]);
-if (compiler === null) {
-  process.stderr.write(
-    "No luau-compile found. Put it on PATH or in ./tools, or set LUAU_COMPILE.\n" +
-      "Download: https://github.com/luau-lang/luau/releases\n",
-  );
-  process.exit(1);
-}
-
-const files = luauFiles(join(root, "plugin", "src"));
-const failures = [];
-
-for (const file of files) {
-  // --binary throws the bytecode away; only the exit status and diagnostics
-  // matter, and writing it anywhere would just be litter to clean up.
-  const result = spawnSync(compiler, ["--binary", file], { encoding: "utf8" });
-  const diagnostics = `${result.stderr ?? ""}${result.status === 0 ? "" : (result.stdout ?? "")}`.trim();
-  if (result.status !== 0 || diagnostics.length > 0) {
-    failures.push(`${file.slice(root.length + 1)}\n${diagnostics}`);
-  }
-}
-
-/*
- * One diagnostic from the analyser, deliberately.
- *
- * `LocalShadow` is reported when a name is used as a global and a local of that
- * same name is declared later in the file -- which is the shape of the bug this
- * check was written for, and is unambiguous. Running the analyser without
- * Roblox's type definitions also reports every engine global as unknown, so
- * `script`, `task`, `Color3` and friends produce hundreds of lines of noise;
- * filtering to this one diagnostic gets the signal without needing a
- * definitions file that would then have to be kept current with the engine.
- */
-/*
- * Diagnostics about a table this file declares its own type for.
- *
- * The LocalShadow filter was the only thing let through, and that let a whole
- * class of error ship: a field read or written on a `--!strict` table type that
- * does not declare it. The plugin failed to load on the first line it logged --
- * "attempt to perform arithmetic on nil" -- because a batch of edits added five
- * uses of `state.entries` and the edit declaring it never landed. The analyser
- * had said so, four times, and this script threw it away.
- *
- * These two patterns are safe to surface where the rest is not. Without Roblox
- * type definitions the analyser cannot know what `Instance` or `Color3` are, so
- * it reports engine globals in their hundreds -- but those come out as unknown
- * *globals* and unknown *types*. A key missing from a named table type can only
- * be a table this file declared itself.
- */
-const TYPE_PATTERNS = [/Key '[^']+' not found in table/, /Cannot add property '[^']+' to table/];
-
-const analyser = locateLuau("LUAU_ANALYZE", ["luau-analyze.exe", "luau-analyze"]);
-const shadowed = [];
-const mistyped = [];
-if (analyser !== null) {
-  for (const file of files) {
-    const result = spawnSync(analyser, [file], { encoding: "utf8" });
-    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
-    for (const line of output.split("\n")) {
-      if (line.includes("LocalShadow:")) shadowed.push(line.trim());
-      else if (TYPE_PATTERNS.some((pattern) => pattern.test(line))) mistyped.push(line.trim());
-    }
-  }
-}
-
-if (failures.length > 0) {
-  process.stderr.write(`${failures.join("\n\n")}\n`);
-}
-if (shadowed.length > 0) {
-  process.stderr.write(
-    "\nA local is used before it is declared, so the call reaches a nil global " +
-      "instead:\n" +
-      `${shadowed.join("\n")}\n`,
-  );
-}
-if (mistyped.length > 0) {
-  process.stderr.write(
-    "\nA field is used on a table whose type does not declare it. It is nil at " +
-      "runtime, and the plugin fails the first time that line runs:\n" +
+/**
+ * Compiles every plugin source file, so a broken one is caught here rather than
+ * in Studio.
+ *
+ * This exists because the feedback loop without it is terrible. Nothing in the
+ * Node build reads the Luau at all -- `build:plugin` packs the files into an
+ * .rbxmx as text -- so a syntax error ships, installs, and is only discovered
+ * when the user focuses Studio and the plugin fails to load. It cost two
+ * sessions in one afternoon: a literal newline written into a string where an
+ * escape was meant, and a closure that captured a nil global because it sat
+ * above the forward declaration of the local it meant to call. The first is a
+ * compile error and would have been caught instantly by this. The second is not,
+ * which is why `--!strict` analysis runs too when the analyser is available:
+ * an unknown global is exactly what it flags.
+ *
+ * Needs `luau-compile` (and ideally `luau-analyze`) on PATH, in ./tools, or
+ * named by the LUAU_COMPILE / LUAU_ANALYZE environment variables. Get them from
+ * https://github.com/luau-lang/luau/releases.
+ *
+ * Silent and exit 0 when everything compiles; prints what failed otherwise.
+ *
+ * Usage: node scripts/check-plugin.mjs
+ */
+import { spawnSync } from "node:child_process";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { locateLuau, missingLuau } from "./locate-luau.mjs";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+function luauFiles(directory) {
+  const found = [];
+  for (const entry of readdirSync(directory)) {
+    const path = join(directory, entry);
+    if (statSync(path).isDirectory()) found.push(...luauFiles(path));
+    else if (entry.endsWith(".luau")) found.push(path);
+  }
+  return found;
+}
+
+const compiler = locateLuau("LUAU_COMPILE", ["luau-compile.exe", "luau-compile"]);
+if (compiler === null) {
+  process.stderr.write(
+    "No luau-compile found. Put it on PATH or in ./tools, or set LUAU_COMPILE.\n" +
+      "Download: https://github.com/luau-lang/luau/releases\n",
+  );
+  process.exit(1);
+}
+
+const files = luauFiles(join(root, "plugin", "src"));
+const failures = [];
+
+for (const file of files) {
+  // --binary throws the bytecode away; only the exit status and diagnostics
+  // matter, and writing it anywhere would just be litter to clean up.
+  const result = spawnSync(compiler, ["--binary", file], { encoding: "utf8" });
+  const diagnostics = `${result.stderr ?? ""}${result.status === 0 ? "" : (result.stdout ?? "")}`.trim();
+  if (result.status !== 0 || diagnostics.length > 0) {
+    failures.push(`${file.slice(root.length + 1)}\n${diagnostics}`);
+  }
+}
+
+/*
+ * One diagnostic from the analyser, deliberately.
+ *
+ * `LocalShadow` is reported when a name is used as a global and a local of that
+ * same name is declared later in the file -- which is the shape of the bug this
+ * check was written for, and is unambiguous. Running the analyser without
+ * Roblox's type definitions also reports every engine global as unknown, so
+ * `script`, `task`, `Color3` and friends produce hundreds of lines of noise;
+ * filtering to this one diagnostic gets the signal without needing a
+ * definitions file that would then have to be kept current with the engine.
+ */
+/*
+ * Diagnostics about a table this file declares its own type for.
+ *
+ * The LocalShadow filter was the only thing let through, and that let a whole
+ * class of error ship: a field read or written on a `--!strict` table type that
+ * does not declare it. The plugin failed to load on the first line it logged --
+ * "attempt to perform arithmetic on nil" -- because a batch of edits added five
+ * uses of `state.entries` and the edit declaring it never landed. The analyser
+ * had said so, four times, and this script threw it away.
+ *
+ * These two patterns are safe to surface where the rest is not. Without Roblox
+ * type definitions the analyser cannot know what `Instance` or `Color3` are, so
+ * it reports engine globals in their hundreds -- but those come out as unknown
+ * *globals* and unknown *types*. A key missing from a named table type can only
+ * be a table this file declared itself.
+ */
+const TYPE_PATTERNS = [/Key '[^']+' not found in table/, /Cannot add property '[^']+' to table/];
+
+const analyser = locateLuau("LUAU_ANALYZE", ["luau-analyze.exe", "luau-analyze"]);
+const shadowed = [];
+const mistyped = [];
+if (analyser !== null) {
+  for (const file of files) {
+    const result = spawnSync(analyser, [file], { encoding: "utf8" });
+    const output = `${result.stdout ?? ""}${result.stderr ?? ""}`;
+    for (const line of output.split("\n")) {
+      if (line.includes("LocalShadow:")) shadowed.push(line.trim());
+      else if (TYPE_PATTERNS.some((pattern) => pattern.test(line))) mistyped.push(line.trim());
+    }
+  }
+}
+
+/*
+ * Every operation the plugin answers has to have a readable name in the panel.
+ *
+ * `Phrase` falls back to tidying the wire name, so a missing entry is invisible
+ * in testing and only shows up as "Data set" where "SAVE over 4212 in PlayerData"
+ * belonged. Left unchecked it rots by default: 26 of 72 operations had drifted
+ * out of the table, which is every tool added after the table was written. A
+ * missing KIND is worse than cosmetic -- the fallback is "read", so an
+ * unregistered terrain wipe was announced with the weight of an inspect.
+ */
+const unnamed = [];
+const kindless = new Set();
+{
+  const phrase = readFileSync(join(root, "plugin", "src", "Phrase.luau"), "utf8");
+  const described = new Set([...phrase.matchAll(/\["([^"]+)"\]\s*=\s*function/g)].map((m) => m[1]));
+  const kinds = new Set([...phrase.matchAll(/^\t([a-z]+) = "/gm)].map((m) => m[1]));
+  // `script` is split by action inside Phrase.kindOf rather than by a table row.
+  kinds.add("script");
+
+  for (const file of files) {
+    const source = readFileSync(file, "utf8");
+    for (const block of source.matchAll(/Dispatch\.registerAll\("([^"]+)",\s*\{([\s\S]*?)\n\t\}\)/g)) {
+      const group = block[1];
+      if (!kinds.has(group)) kindless.add(group);
+      for (const entry of block[2].matchAll(/^\s*([A-Za-z0-9_]+)\s*=/gm)) {
+        const op = `${group}.${entry[1]}`;
+        if (!described.has(op)) unnamed.push(op);
+      }
+    }
+  }
+}
+
+if (unnamed.length > 0) {
+  failures.push(
+    "These operations have no entry in Phrase.luau, so the Studio panel shows " +
+      "the wire name instead of saying what they touch:\n  " +
+      unnamed.sort().join("\n  "),
+  );
+}
+if (kindless.size > 0) {
+  failures.push(
+    "These operation groups have no entry in Phrase KINDS, so they are announced " +
+      'as "read" whatever they do:\n  ' +
+      [...kindless].sort().join("\n  "),
+  );
+}
+
+if (failures.length > 0) {
+  process.stderr.write(`${failures.join("\n\n")}\n`);
+}
+if (shadowed.length > 0) {
+  process.stderr.write(
+    "\nA local is used before it is declared, so the call reaches a nil global " +
+      "instead:\n" +
+      `${shadowed.join("\n")}\n`,
+  );
+}
+if (mistyped.length > 0) {
+  process.stderr.write(
+    "\nA field is used on a table whose type does not declare it. It is nil at " +
+      "runtime, and the plugin fails the first time that line runs:\n" +
       `${mistyped.join("\n")}
-`,
-  );
-}
-process.exit(failures.length > 0 || shadowed.length > 0 || mistyped.length > 0 ? 1 : 0);
+`,
+  );
+}
+process.exit(failures.length > 0 || shadowed.length > 0 || mistyped.length > 0 ? 1 : 0);