@princeofscale/bloxforge-inspector 2.20.2

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

@@ -0,0 +1,111 @@
+// Async execute_luau handlers. execute_luau_async registers a job, spawns the
+// real LuauExec.execute in a coroutine, and returns the jobId immediately;
+// get_job_status / get_job_result poll the registry. This keeps every MCP call
+// fast (no long-poll timeout) while heavy Luau runs between polls. Cancellation
+// is best-effort — Luau coroutines can't be force-killed, so we flag the job and
+// discard its result on completion.
+
+import LuauExec from "../LuauExec";
+import JobRegistry from "../JobRegistry";
+
+// Install a sanctioned progress/cancel API once. Server-generated long-running
+// Luau (terrain/template/batch builders) can call _G.__mcp.progress(done,total,msg)
+// and _G.__mcp.checkCancelled() to report progress and bail early. We do NOT
+// auto-inject this into arbitrary user code — it's an opt-in cooperative API.
+declare const _G: { __mcp?: unknown };
+function installMcpGlobal(): void {
+	if (_G.__mcp !== undefined) return;
+	_G.__mcp = {
+		progress: (done: number, total?: number, message?: string, stage?: string) => {
+			JobRegistry.reportProgress(coroutine.running(), done, total, message, stage);
+		},
+		checkCancelled: () => JobRegistry.isCancelledForThread(coroutine.running()),
+	};
+}
+installMcpGlobal();
+
+function executeLuauAsync(requestData: Record<string, unknown>) {
+	const code = requestData.code as string;
+	if (!code || code === "") return { error: "Code is required" };
+
+	const job = JobRegistry.create();
+	task.spawn(() => {
+		const co = coroutine.running();
+		JobRegistry.bindThread(co, job.id);
+		const result = LuauExec.execute(code);
+		JobRegistry.unbindThread(co);
+		const j = JobRegistry.get(job.id);
+		if (!j) return;
+		if (j.cancelled === true) {
+			j.status = "cancelled";
+			j.finishedAt = tick();
+			return;
+		}
+		j.success = result.success;
+		j.returnValue = result.returnValue;
+		j.output = result.output;
+		j.error = result.error;
+		j.message = result.message;
+		j.status = result.success ? "done" : "error";
+		j.finishedAt = tick();
+	});
+
+	return { jobId: job.id, status: "running", estimatedKind: "long" };
+}
+
+function getJobStatus(requestData: Record<string, unknown>) {
+	const jobId = requestData.jobId as string;
+	if (!jobId || jobId === "") return { error: "jobId is required" };
+	const j = JobRegistry.get(jobId);
+	if (!j) return { error: "Unknown jobId", jobId };
+	const elapsed = (j.finishedAt ?? tick()) - j.startedAt;
+	return {
+		jobId: j.id,
+		status: j.status,
+		elapsed,
+		message: j.message,
+		progress: j.progress,
+		total: j.total,
+		stage: j.stage,
+		done: j.status !== "running",
+	};
+}
+
+function getJobResult(requestData: Record<string, unknown>) {
+	const jobId = requestData.jobId as string;
+	if (!jobId || jobId === "") return { error: "jobId is required" };
+	const j = JobRegistry.get(jobId);
+	if (!j) return { error: "Unknown jobId", jobId };
+	if (j.status === "running") {
+		return { jobId: j.id, status: "running", done: false };
+	}
+	return {
+		jobId: j.id,
+		status: j.status,
+		done: true,
+		success: j.success,
+		returnValue: j.returnValue,
+		output: j.output,
+		error: j.error,
+		message: j.message,
+		elapsed: (j.finishedAt ?? tick()) - j.startedAt,
+	};
+}
+
+function cancelJob(requestData: Record<string, unknown>) {
+	const jobId = requestData.jobId as string;
+	if (!jobId || jobId === "") return { error: "jobId is required" };
+	const j = JobRegistry.get(jobId);
+	if (!j) return { error: "Unknown jobId", jobId };
+	if (j.status === "running") {
+		j.cancelled = true;
+		return {
+			jobId: j.id,
+			status: "cancelling",
+			note: "Luau coroutines cannot be force-killed; the result will be discarded on completion.",
+		};
+	}
+	return { jobId: j.id, status: j.status, note: "Job already finished." };
+}
+
+export = { executeLuauAsync, getJobStatus, getJobResult, cancelJob };

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

@@ -0,0 +1,14 @@
+import RuntimeLogBuffer from "../RuntimeLogBuffer";
+
+function getRuntimeLogs(requestData: Record<string, unknown>): unknown {
+	const since = requestData.since as number | undefined;
+	const tail = requestData.tail as number | undefined;
+	const filter = requestData.filter as string | undefined;
+	// This is the buffer that captured the LogService event, not necessarily
+	// the script-origin peer. Ordinary playtests share/reflect logs across
+	// edit/server/client LogService buffers.
+	const capturedBy = RuntimeLogBuffer.detectPeer();
+	return RuntimeLogBuffer.query({ since, tail, filter }, capturedBy);
+}
+
+export = { getRuntimeLogs };

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

@@ -0,0 +1,44 @@
+const Stats = game.GetService("Stats");
+
+// GetMemoryUsageMbAllCategories is gated by capability "InternalTest" and not
+// callable from plugin context. GetMemoryUsageMbForTag is not - so we iterate
+// Enum.DeveloperMemoryTag and ask per-tag.
+function getMemoryBreakdown(requestData: Record<string, unknown>): unknown {
+	if (!Stats.MemoryTrackingEnabled) {
+		return { error: "MemoryTrackingEnabled is false on this peer" };
+	}
+
+	const requested = requestData.tags as string[] | undefined;
+	const requestedSet = requested && requested.size() > 0 ? new Set(requested) : undefined;
+
+	const categories: Record<string, number> = {};
+	for (const item of Enum.DeveloperMemoryTag.GetEnumItems()) {
+		const name = item.Name;
+		if (requestedSet && !requestedSet.has(name)) continue;
+		const [ok, mb] = pcall(() => Stats.GetMemoryUsageMbForTag(item));
+		categories[name] = ok ? (mb as number) : 0;
+	}
+
+	const unknownTags: string[] = [];
+	if (requestedSet) {
+		const known = new Set<string>();
+		for (const i of Enum.DeveloperMemoryTag.GetEnumItems()) known.add(i.Name);
+		for (const t of requestedSet) {
+			if (!known.has(t)) {
+				unknownTags.push(t);
+				categories[t] = 0;
+			}
+		}
+	}
+
+	const result: Record<string, unknown> = {
+		total_mb: Stats.GetTotalMemoryUsageMb(),
+		categories,
+		memory_tracking_enabled: true,
+		timestamp: DateTime.now().UnixTimestampMillis,
+	};
+	if (unknownTags.size() > 0) result.unknown_tags = unknownTags;
+	return result;
+}
+
+export = { getMemoryBreakdown };

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

@@ -0,0 +1,354 @@
+import { CollectionService } from "@rbxts/services";
+import Utils from "../Utils";
+import Recording from "../Recording";
+import LuauExec from "../LuauExec";
+
+const ChangeHistoryService = game.GetService("ChangeHistoryService");
+const Selection = game.GetService("Selection");
+
+const { getInstancePath, getInstanceByPath } = Utils;
+const { beginRecording, finishRecording } = Recording;
+
+function serializeValue(value: unknown): unknown {
+	const vType = typeOf(value);
+	if (vType === "Vector3") {
+		const v = value as Vector3;
+		return { X: v.X, Y: v.Y, Z: v.Z, _type: "Vector3" };
+	} else if (vType === "Color3") {
+		const v = value as Color3;
+		return { R: v.R, G: v.G, B: v.B, _type: "Color3" };
+	} else if (vType === "CFrame") {
+		const v = value as CFrame;
+		return { Position: { X: v.Position.X, Y: v.Position.Y, Z: v.Position.Z }, _type: "CFrame" };
+	} else if (vType === "UDim2") {
+		const v = value as UDim2;
+		return {
+			X: { Scale: v.X.Scale, Offset: v.X.Offset },
+			Y: { Scale: v.Y.Scale, Offset: v.Y.Offset },
+			_type: "UDim2",
+		};
+	} else if (vType === "BrickColor") {
+		const v = value as BrickColor;
+		return { Name: v.Name, _type: "BrickColor" };
+	}
+	return value;
+}
+
+function deserializeValue(attributeValue: unknown, valueType?: string): unknown {
+	if (!typeIs(attributeValue, "table")) return attributeValue;
+
+	const tbl = attributeValue as Record<string, unknown>;
+	const t = (tbl._type as string) ?? valueType;
+
+	if (t === "Vector3") {
+		return new Vector3((tbl.X as number) ?? 0, (tbl.Y as number) ?? 0, (tbl.Z as number) ?? 0);
+	} else if (t === "Color3") {
+		return new Color3((tbl.R as number) ?? 0, (tbl.G as number) ?? 0, (tbl.B as number) ?? 0);
+	} else if (t === "UDim2") {
+		const x = tbl.X as Record<string, number> | undefined;
+		const y = tbl.Y as Record<string, number> | undefined;
+		return new UDim2(x?.Scale ?? 0, x?.Offset ?? 0, y?.Scale ?? 0, y?.Offset ?? 0);
+	} else if (t === "BrickColor") {
+		return new BrickColor(((tbl.Name as string) ?? "Medium stone grey") as unknown as number);
+	}
+	return attributeValue;
+}
+
+function setAttribute(requestData: Record<string, unknown>) {
+	const instancePath = requestData.instancePath as string;
+	const attributeName = requestData.attributeName as string;
+	const attributeValue = requestData.attributeValue;
+	const valueType = requestData.valueType as string | undefined;
+
+	if (!instancePath || !attributeName) {
+		return { error: "Instance path and attribute name are required" };
+	}
+
+	const instance = getInstanceByPath(instancePath);
+	if (!instance) return { error: `Instance not found: ${instancePath}` };
+	const recordingId = beginRecording(`Set attribute ${attributeName} on ${instance.Name}`);
+
+	const [success, result] = pcall(() => {
+		const value = deserializeValue(attributeValue, valueType);
+		instance.SetAttribute(attributeName, value as AttributeValue);
+
+		return {
+			success: true, instancePath, attributeName,
+			value: attributeValue, message: "Attribute set successfully",
+		};
+	});
+
+	if (success) {
+		finishRecording(recordingId, true);
+		return result;
+	}
+	finishRecording(recordingId, false);
+	return { error: `Failed to set attribute: ${result}` };
+}
+
+function getAttributes(requestData: Record<string, unknown>) {
+	const instancePath = requestData.instancePath as string;
+	if (!instancePath) return { error: "Instance path is required" };
+
+	const instance = getInstanceByPath(instancePath);
+	if (!instance) return { error: `Instance not found: ${instancePath}` };
+
+	const [success, result] = pcall(() => {
+		const attributes = instance.GetAttributes();
+		const serializedAttributes: Record<string, { value: unknown; type: string }> = {};
+		let count = 0;
+
+		for (const [name, value] of pairs(attributes)) {
+			serializedAttributes[name as string] = {
+				value: serializeValue(value),
+				type: typeOf(value),
+			};
+			count++;
+		}
+
+		return { instancePath, attributes: serializedAttributes, count };
+	});
+
+	if (success) return result;
+	return { error: `Failed to get attributes: ${result}` };
+}
+
+function deleteAttribute(requestData: Record<string, unknown>) {
+	const instancePath = requestData.instancePath as string;
+	const attributeName = requestData.attributeName as string;
+
+	if (!instancePath || !attributeName) {
+		return { error: "Instance path and attribute name are required" };
+	}
+
+	const instance = getInstanceByPath(instancePath);
+	if (!instance) return { error: `Instance not found: ${instancePath}` };
+	const recordingId = beginRecording(`Delete attribute ${attributeName} from ${instance.Name}`);
+
+	const [success, result] = pcall(() => {
+		const existed = instance.GetAttribute(attributeName) !== undefined;
+		instance.SetAttribute(attributeName, undefined);
+
+		return {
+			success: true, instancePath, attributeName, existed,
+			message: existed ? "Attribute deleted successfully" : "Attribute did not exist",
+		};
+	});
+
+	if (success) {
+		finishRecording(recordingId, true);
+		return result;
+	}
+	finishRecording(recordingId, false);
+	return { error: `Failed to delete attribute: ${result}` };
+}
+
+function getTags(requestData: Record<string, unknown>) {
+	const instancePath = requestData.instancePath as string;
+	if (!instancePath) return { error: "Instance path is required" };
+
+	const instance = getInstanceByPath(instancePath);
+	if (!instance) return { error: `Instance not found: ${instancePath}` };
+
+	const [success, result] = pcall(() => {
+		const tags = CollectionService.GetTags(instance);
+		return { instancePath, tags, count: tags.size() };
+	});
+
+	if (success) return result;
+	return { error: `Failed to get tags: ${result}` };
+}
+
+function addTag(requestData: Record<string, unknown>) {
+	const instancePath = requestData.instancePath as string;
+	const tagName = requestData.tagName as string;
+
+	if (!instancePath || !tagName) {
+		return { error: "Instance path and tag name are required" };
+	}
+
+	const instance = getInstanceByPath(instancePath);
+	if (!instance) return { error: `Instance not found: ${instancePath}` };
+	const recordingId = beginRecording(`Add tag ${tagName} to ${instance.Name}`);
+
+	const [success, result] = pcall(() => {
+		const alreadyHad = CollectionService.HasTag(instance, tagName);
+		CollectionService.AddTag(instance, tagName);
+
+		return {
+			success: true, instancePath, tagName, alreadyHad,
+			message: alreadyHad ? "Instance already had this tag" : "Tag added successfully",
+		};
+	});
+
+	if (success) {
+		finishRecording(recordingId, true);
+		return result;
+	}
+	finishRecording(recordingId, false);
+	return { error: `Failed to add tag: ${result}` };
+}
+
+function removeTag(requestData: Record<string, unknown>) {
+	const instancePath = requestData.instancePath as string;
+	const tagName = requestData.tagName as string;
+
+	if (!instancePath || !tagName) {
+		return { error: "Instance path and tag name are required" };
+	}
+
+	const instance = getInstanceByPath(instancePath);
+	if (!instance) return { error: `Instance not found: ${instancePath}` };
+	const recordingId = beginRecording(`Remove tag ${tagName} from ${instance.Name}`);
+
+	const [success, result] = pcall(() => {
+		const hadTag = CollectionService.HasTag(instance, tagName);
+		CollectionService.RemoveTag(instance, tagName);
+
+		return {
+			success: true, instancePath, tagName, hadTag,
+			message: hadTag ? "Tag removed successfully" : "Instance did not have this tag",
+		};
+	});
+
+	if (success) {
+		finishRecording(recordingId, true);
+		return result;
+	}
+	finishRecording(recordingId, false);
+	return { error: `Failed to remove tag: ${result}` };
+}
+
+function getTagged(requestData: Record<string, unknown>) {
+	const tagName = requestData.tagName as string;
+	if (!tagName) return { error: "Tag name is required" };
+
+	const [success, result] = pcall(() => {
+		const taggedInstances = CollectionService.GetTagged(tagName);
+		const instances = taggedInstances.map((instance) => ({
+			name: instance.Name,
+			className: instance.ClassName,
+			path: getInstancePath(instance),
+		}));
+
+		return { tagName, instances, count: instances.size() };
+	});
+
+	if (success) return result;
+	return { error: `Failed to get tagged instances: ${result}` };
+}
+
+function getSelection(_requestData: Record<string, unknown>) {
+	const selection = Selection.Get();
+
+	if (selection.size() === 0) {
+		return { success: true, selection: [], count: 0, message: "No objects selected" };
+	}
+
+	const selectedObjects = selection.map((instance: Instance) => ({
+		name: instance.Name,
+		className: instance.ClassName,
+		path: getInstancePath(instance),
+		parent: instance.Parent ? getInstancePath(instance.Parent) : undefined,
+	}));
+
+	return {
+		success: true,
+		selection: selectedObjects,
+		count: selection.size(),
+		message: `${selection.size()} object(s) selected`,
+	};
+}
+
+function executeLuau(requestData: Record<string, unknown>) {
+	const code = requestData.code as string;
+	if (!code || code === "") return { error: "Code is required" };
+	// All wrapping, print/warn capture, loadstring fallback, JSON-encoding
+	// of table returns, and parse-error recovery live in LuauExec so the
+	// edit/server (this handler) and the play-client (ClientBroker) take
+	// the same code path and produce identical output shapes.
+	return LuauExec.execute(code);
+}
+
+function undo(_requestData: Record<string, unknown>) {
+	const [success, result] = pcall(() => {
+		ChangeHistoryService.Undo();
+		return {
+			success: true,
+			message: "Undo executed successfully",
+		};
+	});
+
+	if (success) return result;
+	return { error: `Failed to undo: ${result}` };
+}
+
+function redo(_requestData: Record<string, unknown>) {
+	const [success, result] = pcall(() => {
+		ChangeHistoryService.Redo();
+		return {
+			success: true,
+			message: "Redo executed successfully",
+		};
+	});
+
+	if (success) return result;
+	return { error: `Failed to redo: ${result}` };
+}
+
+function bulkSetAttributes(requestData: Record<string, unknown>) {
+	const instancePath = requestData.instancePath as string;
+	const attributes = requestData.attributes as Record<string, unknown>;
+
+	if (!instancePath || !attributes) {
+		return { error: "Instance path and attributes are required" };
+	}
+
+	const instance = getInstanceByPath(instancePath);
+	if (!instance) return { error: `Instance not found: ${instancePath}` };
+
+	const recordingId = beginRecording(`Bulk set attributes on ${instance.Name}`);
+
+	const results: Record<string, unknown>[] = [];
+	let successCount = 0;
+	let failureCount = 0;
+
+	for (const [name, rawValue] of pairs(attributes)) {
+		const attrName = name as string;
+		const [ok, err] = pcall(() => {
+			const value = deserializeValue(rawValue);
+			instance.SetAttribute(attrName, value as AttributeValue);
+		});
+
+		if (ok) {
+			successCount++;
+			results.push({ attributeName: attrName, success: true });
+		} else {
+			failureCount++;
+			results.push({ attributeName: attrName, success: false, error: tostring(err) });
+		}
+	}
+
+	finishRecording(recordingId, successCount > 0);
+
+	return {
+		instancePath,
+		results,
+		summary: { total: successCount + failureCount, succeeded: successCount, failed: failureCount },
+	};
+}
+
+export = {
+	setAttribute,
+	getAttributes,
+	deleteAttribute,
+	getTags,
+	addTag,
+	removeTag,
+	getTagged,
+	getSelection,
+	executeLuau,
+	undo,
+	redo,
+	bulkSetAttributes,
+};