@chrrxs/robloxstudio-mcp 2.14.0 → 2.15.1

package/studio-plugin/src/modules/Communication.ts

@@ -16,6 +16,7 @@ import InputHandlers from "./handlers/InputHandlers";
 import LogHandlers from "./handlers/LogHandlers";
 import SerializationHandlers from "./handlers/SerializationHandlers";
 import MemoryHandlers from "./handlers/MemoryHandlers";
+import SceneAnalysisHandlers from "./handlers/SceneAnalysisHandlers";
 import { Connection, RequestPayload, PollResponse, ReadyResponse } from "../types";
 
 // Per-plugin-load random GUID. Used as the /poll URL param so the server
@@ -46,6 +47,8 @@ function computeInstanceId(): string {
 const instanceId = computeInstanceId();
 let assignedRole: string | undefined;
 let duplicateInstanceRole = false;
+let hasVersionMismatch = false;
+let lastVersionMismatchWarningKey: string | undefined;
 
 // Cache the published place name from MarketplaceService:GetProductInfo so
 // /ready can carry a friendly identifier (e.g. "Natural Disasters") distinct
@@ -162,6 +165,7 @@ const routeMap: Record<string, Handler> = {
 	"/api/import-rbxm": SerializationHandlers.importRbxm,
 
 	"/api/get-memory-breakdown": MemoryHandlers.getMemoryBreakdown,
+	"/api/get-scene-analysis": SceneAnalysisHandlers.getSceneAnalysis,
 };
 
 function processRequest(request: RequestPayload): unknown {
@@ -236,6 +240,8 @@ function sendReady(conn: Connection): void {
 					placeName: resolvePlaceName(),
 					dataModelName: game.Name,
 					isRunning: RunService.IsRunning(),
+					pluginVersion: State.CURRENT_VERSION,
+					pluginVariant: State.PLUGIN_VARIANT,
 					pluginReady: true,
 					timestamp: tick(),
 				}),
@@ -299,6 +305,19 @@ function pollForRequests(connIndex: number) {
 		const mcpConnected = data.mcpConnected === true;
 		conn.lastHttpOk = true;
 		conn.lastMcpOk = mcpConnected;
+		const serverVersion = data.serverVersion ?? "unknown";
+		if (data.versionMismatch === true) {
+			hasVersionMismatch = true;
+			const warningKey = `${State.CURRENT_VERSION}:${serverVersion}`;
+			if (lastVersionMismatchWarningKey !== warningKey) {
+				lastVersionMismatchWarningKey = warningKey;
+				warn(`[MCPPlugin] Version mismatch: Studio plugin v${State.CURRENT_VERSION} / MCP v${serverVersion}. Run npx -y @chrrxs/robloxstudio-mcp@latest --auto-install-plugin and restart Studio.`);
+			}
+			UI.showBanner("version-mismatch", `Plugin v${State.CURRENT_VERSION} / MCP v${serverVersion} mismatch`);
+		} else if (hasVersionMismatch) {
+			hasVersionMismatch = false;
+			UI.hideBanner("version-mismatch");
+		}
 
 		// Server tells us when its in-memory instances map doesn't have us
 		// (e.g. after an MCP process restart). Re-issue /ready immediately so
@@ -537,11 +556,9 @@ function checkForUpdates() {
 			if (ok && data?.version) {
 				const latestVersion = data.version;
 				if (Utils.compareVersions(State.CURRENT_VERSION, latestVersion) < 0) {
-					const ui = UI.getElements();
-					ui.updateBannerText.Text = `v${latestVersion} available - github.com/chrrxs/robloxstudio-mcp`;
-					ui.updateBanner.Visible = true;
-					ui.contentFrame.Position = new UDim2(0, 8, 0, 92);
-					ui.contentFrame.Size = new UDim2(1, -16, 1, -100);
+					if (!hasVersionMismatch) {
+						UI.showBanner("update", `v${latestVersion} available - github.com/chrrxs/robloxstudio-mcp`);
+					}
 				}
 			}
 		}

package/studio-plugin/src/modules/State.ts

@@ -1,6 +1,7 @@
 import { Connection } from "../types";
 
 const CURRENT_VERSION = "__VERSION__";
+const PLUGIN_VARIANT = "__PLUGIN_VARIANT__";
 const MAX_CONNECTIONS = 5;
 const BASE_PORT = 58741;
 let activeTabIndex = 0;
@@ -81,6 +82,7 @@ function getConnections(): Connection[] {
 
 export = {
 	CURRENT_VERSION,
+	PLUGIN_VARIANT,
 	MAX_CONNECTIONS,
 	BASE_PORT,
 	connections,

package/studio-plugin/src/modules/UI.ts

@@ -38,6 +38,7 @@ interface ToolbarIcons {
 let toolbarButton: PluginToolbarButton | undefined;
 let toolbarIcons: ToolbarIcons | undefined;
 let lastToolbarIcon: string | undefined;
+let activeBannerKind: string | undefined;
 
 function setToolbarButton(btn: PluginToolbarButton, icons: ToolbarIcons) {
 	toolbarButton = btn;
@@ -77,6 +78,23 @@ function tweenProp(instance: Instance, props: Record<string, unknown>) {
 	TweenService.Create(instance, TWEEN_QUICK, props as unknown as { [key: string]: unknown }).Play();
 }
 
+function showBanner(kind: string, text: string) {
+	activeBannerKind = kind;
+	elements.updateBannerText.Text = text;
+	elements.updateBanner.Visible = true;
+	elements.contentFrame.Position = new UDim2(0, 8, 0, 92);
+	elements.contentFrame.Size = new UDim2(1, -16, 1, -100);
+}
+
+function hideBanner(kind?: string) {
+	if (kind !== undefined && activeBannerKind !== kind) return;
+	activeBannerKind = undefined;
+	elements.updateBanner.Visible = false;
+	elements.updateBannerText.Text = "";
+	elements.contentFrame.Position = new UDim2(0, 8, 0, 66);
+	elements.contentFrame.Size = new UDim2(1, -16, 1, -74);
+}
+
 const C = {
 	bg: Color3.fromRGB(14, 14, 14),
 	card: Color3.fromRGB(22, 22, 22),
@@ -759,5 +777,7 @@ export = {
 	startPulseAnimation,
 	setToolbarButton,
 	updateToolbarIcon,
+	showBanner,
+	hideBanner,
 	getElements: () => elements,
 };

package/studio-plugin/src/modules/handlers/SceneAnalysisHandlers.ts

@@ -0,0 +1,216 @@
+interface SceneAnalysisServiceLike extends Instance {
+	GetInstanceCompositionAsync(this: SceneAnalysisServiceLike): unknown;
+	GetScriptMemoryAsync(this: SceneAnalysisServiceLike): unknown;
+	GetUnparentedInstancesAsync(this: SceneAnalysisServiceLike): unknown;
+	GetTriangleCompositionAsync(this: SceneAnalysisServiceLike): unknown;
+	GetAnimationMemoryAsync(this: SceneAnalysisServiceLike): unknown;
+	GetAudioMemoryAsync(this: SceneAnalysisServiceLike): unknown;
+}
+
+interface SceneAnalysisNode {
+	Name?: string;
+	Size?: number;
+	Sizes?: Record<string, number>;
+	Children?: SceneAnalysisNode[];
+	AssetId?: string;
+}
+
+interface ModeConfig {
+	method: string;
+	query: (service: SceneAnalysisServiceLike) => unknown;
+	sortByTriangles?: boolean;
+}
+
+const MODE_CONFIGS: Record<string, ModeConfig> = {
+	instance_composition: {
+		method: "GetInstanceCompositionAsync",
+		query: (service) => service.GetInstanceCompositionAsync(),
+	},
+	script_memory: {
+		method: "GetScriptMemoryAsync",
+		query: (service) => service.GetScriptMemoryAsync(),
+	},
+	unparented_instances: {
+		method: "GetUnparentedInstancesAsync",
+		query: (service) => service.GetUnparentedInstancesAsync(),
+	},
+	triangle_composition: {
+		method: "GetTriangleCompositionAsync",
+		query: (service) => service.GetTriangleCompositionAsync(),
+		sortByTriangles: true,
+	},
+	animation_memory: {
+		method: "GetAnimationMemoryAsync",
+		query: (service) => service.GetAnimationMemoryAsync(),
+	},
+	audio_memory: {
+		method: "GetAudioMemoryAsync",
+		query: (service) => service.GetAudioMemoryAsync(),
+	},
+};
+
+const ALL_MODES = [
+	"instance_composition",
+	"script_memory",
+	"unparented_instances",
+	"triangle_composition",
+	"animation_memory",
+	"audio_memory",
+];
+
+function betaDisabledError(): Record<string, unknown> {
+	return {
+		error: "scene_analysis_not_enabled",
+		message: "SceneAnalysisService is not enabled. Enable Scene Analysis in Studio Beta Features and restart Studio.",
+		betaFeatureRequired: true,
+	};
+}
+
+function isBetaDisabledError(value: unknown): boolean {
+	return typeIs(value, "string") && string.find(value, "SceneAnalysisService is not enabled", 1, true)[0] !== undefined;
+}
+
+function getSceneAnalysisService(): SceneAnalysisServiceLike | Record<string, unknown> {
+	const provider = game as unknown as { GetService(serviceName: string): Instance };
+	const [ok, service] = pcall(() => provider.GetService("SceneAnalysisService") as SceneAnalysisServiceLike);
+	if (!ok || !service) {
+		return {
+			error: "scene_analysis_unavailable",
+			message: `SceneAnalysisService is unavailable: ${tostring(service)}`,
+		};
+	}
+	return service;
+}
+
+function normalizeMode(mode: unknown): string | Record<string, unknown> {
+	if (mode === undefined || mode === "all") return "all";
+	if (!typeIs(mode, "string") || MODE_CONFIGS[mode] === undefined) {
+		return {
+			error: "invalid_mode",
+			message: `mode must be one of: all, ${ALL_MODES.join(", ")}`,
+		};
+	}
+	return mode;
+}
+
+function normalizeTopN(topN: unknown): number {
+	if (!typeIs(topN, "number")) return 10;
+	return math.clamp(math.floor(topN), 1, 100);
+}
+
+function countLeaves(node: SceneAnalysisNode): number {
+	const children = node.Children;
+	if (children && children.size() > 0) {
+		let total = 0;
+		for (const child of children) total += countLeaves(child);
+		return total;
+	}
+	return 1;
+}
+
+function flattenLeaves(node: SceneAnalysisNode, out: SceneAnalysisNode[]): void {
+	const children = node.Children;
+	if (children && children.size() > 0) {
+		for (const child of children) flattenLeaves(child, out);
+		return;
+	}
+	out.push(node);
+}
+
+function compactEntry(node: SceneAnalysisNode): Record<string, unknown> {
+	const entry: Record<string, unknown> = {
+		name: node.Name,
+	};
+	if (node.Size !== undefined) entry.size = node.Size;
+	if (node.Sizes !== undefined) entry.sizes = node.Sizes;
+	if (node.AssetId !== undefined) entry.asset_id = node.AssetId;
+	return entry;
+}
+
+function compactRoot(node: SceneAnalysisNode, leafCount: number): Record<string, unknown> {
+	const children = node.Children;
+	const root: Record<string, unknown> = {
+		name: node.Name,
+		child_count: children ? children.size() : 0,
+		leaf_count: leafCount,
+	};
+	if (node.Size !== undefined) root.size = node.Size;
+	if (node.Sizes !== undefined) root.sizes = node.Sizes;
+	return root;
+}
+
+function metric(node: SceneAnalysisNode, sortByTriangles: boolean): number {
+	if (sortByTriangles) {
+		const sizes = node.Sizes;
+		const triangles = sizes ? sizes.Triangles : undefined;
+		return triangles ?? 0;
+	}
+	return node.Size ?? 0;
+}
+
+function summarizeMode(
+	mode: string,
+	config: ModeConfig,
+	service: SceneAnalysisServiceLike,
+	topN: number,
+	raw: boolean,
+): Record<string, unknown> {
+	const started = os.clock();
+	const [ok, result] = pcall(() => config.query(service) as SceneAnalysisNode);
+	const elapsedMs = math.floor((os.clock() - started) * 1000);
+
+	if (!ok) {
+		if (isBetaDisabledError(result)) return betaDisabledError();
+		return {
+			error: "scene_analysis_query_failed",
+			mode,
+			method: config.method,
+			message: tostring(result),
+		};
+	}
+
+	const tree = result as SceneAnalysisNode;
+	const leaves: SceneAnalysisNode[] = [];
+	flattenLeaves(tree, leaves);
+	leaves.sort((a, b) => metric(a, config.sortByTriangles === true) > metric(b, config.sortByTriangles === true));
+
+	const top: Record<string, unknown>[] = [];
+	for (let i = 0; i < math.min(topN, leaves.size()); i++) {
+		top.push(compactEntry(leaves[i]));
+	}
+
+	const body: Record<string, unknown> = {
+		mode,
+		method: config.method,
+		elapsed_ms: elapsedMs,
+		root: compactRoot(tree, leaves.size()),
+		top,
+	};
+	if (raw) body.tree = tree;
+	return body;
+}
+
+function getSceneAnalysis(requestData: Record<string, unknown>): unknown {
+	const mode = normalizeMode(requestData.mode);
+	if (!typeIs(mode, "string")) return mode;
+
+	const serviceOrError = getSceneAnalysisService();
+	if (!serviceOrError.IsA) return serviceOrError;
+	const service = serviceOrError as SceneAnalysisServiceLike;
+	const topN = normalizeTopN(requestData.topN);
+	const raw = requestData.raw === true;
+
+	if (mode !== "all") {
+		return summarizeMode(mode, MODE_CONFIGS[mode], service, topN, raw);
+	}
+
+	const body: Record<string, unknown> = {};
+	for (const m of ALL_MODES) {
+		const result = summarizeMode(m, MODE_CONFIGS[m], service, topN, raw);
+		if (result.error === "scene_analysis_not_enabled") return result;
+		body[m] = result;
+	}
+	return body;
+}
+
+export = { getSceneAnalysis };

package/studio-plugin/src/types/index.d.ts

@@ -30,6 +30,10 @@ export interface RequestPayload {
 
 export interface PollResponse {
 	mcpConnected: boolean;
+	serverVersion?: string;
+	pluginVersion?: string;
+	pluginVariant?: string;
+	versionMismatch?: boolean;
 	request?: RequestPayload;
 	requestId?: string;
 	// Server signals knownInstance=false when its in-memory instances map
@@ -42,6 +46,8 @@ export interface ReadyResponse {
 	success: boolean;
 	assignedRole?: string;
 	instanceId?: string;
+	serverVersion?: string;
+	versionMismatch?: boolean;
 	error?: string;
 	message?: string;
 }