@princeofscale/bloxforge 2.20.2

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

@@ -0,0 +1,386 @@
+const HttpService = game.GetService("HttpService");
+const Players = game.GetService("Players");
+const RunService = game.GetService("RunService");
+
+interface ScriptProfilerServiceLike extends Instance {
+	ServerStart(this: ScriptProfilerServiceLike, frequency?: number): void;
+	ServerStop(this: ScriptProfilerServiceLike): void;
+	ServerRequestData(this: ScriptProfilerServiceLike): void;
+	ClientStart(this: ScriptProfilerServiceLike, player: Player, frequency?: number): void;
+	ClientStop(this: ScriptProfilerServiceLike, player: Player): void;
+	ClientRequestData(this: ScriptProfilerServiceLike, player: Player): void;
+	OnNewData: RBXScriptSignal<(player: Player | undefined, jsonString: string) => void>;
+}
+
+interface CategoryInfo {
+	Name?: string;
+	NodeId?: number;
+}
+
+interface FunctionInfo {
+	Source?: string;
+	Name?: string;
+	Line?: number;
+	TotalDuration?: number;
+	Flags?: number;
+}
+
+interface ProfilingInfo {
+	Version?: number;
+	SessionStartTime?: number;
+	SessionEndTime?: number;
+	Categories?: CategoryInfo[];
+	Nodes?: unknown[];
+	Functions?: FunctionInfo[];
+}
+
+interface FunctionRow {
+	function_index: number;
+	name: string;
+	source?: string;
+	line?: number;
+	total_us: number;
+	is_native?: boolean;
+	is_plugin?: boolean;
+	is_debug_label?: boolean;
+}
+
+const DEFAULT_DURATION_MS = 1000;
+const MIN_DURATION_MS = 100;
+const MAX_DURATION_MS = 15000;
+const DEFAULT_FREQUENCY = 1000;
+const DEFAULT_MAX_FUNCTIONS = 20;
+
+function getProfilerService(): ScriptProfilerServiceLike | Record<string, unknown> {
+	const provider = game as unknown as { GetService(serviceName: string): Instance };
+	const [ok, service] = pcall(() => provider.GetService("ScriptProfilerService") as ScriptProfilerServiceLike);
+	if (!ok || !service) {
+		return {
+			error: "script_profiler_unavailable",
+			message: `ScriptProfilerService is unavailable: ${tostring(service)}`,
+		};
+	}
+	return service;
+}
+
+function normalizeDurationMs(value: unknown): number {
+	if (!typeIs(value, "number")) return DEFAULT_DURATION_MS;
+	return math.clamp(math.floor(value), MIN_DURATION_MS, MAX_DURATION_MS);
+}
+
+function normalizeFrequency(value: unknown): number {
+	if (!typeIs(value, "number")) return DEFAULT_FREQUENCY;
+	return math.clamp(math.floor(value), 1, 10000);
+}
+
+function normalizeMaxFunctions(value: unknown): number {
+	if (!typeIs(value, "number")) return DEFAULT_MAX_FUNCTIONS;
+	return math.clamp(math.floor(value), 1, 100);
+}
+
+function normalizeMinTotalUs(requestData: Record<string, unknown>): number {
+	const value = requestData.min_total_us;
+	if (typeIs(value, "number")) return math.max(0, value);
+	return 0;
+}
+
+function stringContains(haystack: string, needle: string): boolean {
+	return string.find(string.lower(haystack), string.lower(needle), 1, true)[0] !== undefined;
+}
+
+function localPlayer(): Player | undefined {
+	let player = Players.LocalPlayer;
+	const started = tick();
+	while (!player && tick() - started < 5) {
+		task.wait(0.05);
+		player = Players.LocalPlayer;
+	}
+	return player;
+}
+
+function functionDisplayName(func: FunctionInfo): string {
+	if (typeIs(func.Name, "string") && func.Name !== "") return func.Name;
+	if (typeIs(func.Source, "string") && func.Source !== "") {
+		if (typeIs(func.Line, "number") && func.Line > 0) return `${func.Source}:${func.Line}`;
+		return func.Source;
+	}
+	return "<anonymous>";
+}
+
+function flagsOf(func: FunctionInfo): number {
+	return typeIs(func.Flags, "number") ? func.Flags : 0;
+}
+
+function isNativeFunction(func: FunctionInfo): boolean {
+	return bit32.band(flagsOf(func), 1) !== 0;
+}
+
+function isPluginFunction(func: FunctionInfo): boolean {
+	if (bit32.band(flagsOf(func), 2) !== 0) return true;
+	return typeIs(func.Source, "string") && string.find(func.Source, "MCPPlugin", 1, true)[0] !== undefined;
+}
+
+function isDebugLabel(func: FunctionInfo, filter: string | undefined): boolean {
+	if (filter === undefined) return false;
+	if (!typeIs(func.Name, "string") || func.Name === "") return false;
+	if (!typeIs(func.Source, "string") || func.Source === "" || func.Source === "[C]" || func.Source === "GC") return false;
+	if (func.Line !== undefined && func.Line !== 0) return false;
+	if (isNativeFunction(func) || isPluginFunction(func)) return false;
+	return stringContains(func.Name, filter) || stringContains(func.Source, filter);
+}
+
+function pctOfCapture(row: FunctionRow, durationMs: number): number | undefined {
+	const captureUs = durationMs * 1000;
+	if (captureUs <= 0) return undefined;
+	return math.floor((row.total_us / captureUs) * 10000 + 0.5) / 100;
+}
+
+function compactFunction(row: FunctionRow, rank: number, durationMs: number): Record<string, unknown> {
+	const out: Record<string, unknown> = {
+		rank,
+		function_index: row.function_index,
+		name: row.name,
+		total_us: math.floor(row.total_us + 0.5),
+	};
+	const pct = pctOfCapture(row, durationMs);
+	if (pct !== undefined) out.pct_of_capture = pct;
+	if (row.source !== undefined) out.source = row.source;
+	if (row.line !== undefined) out.line = row.line;
+	if (row.is_native === true) out.is_native = true;
+	if (row.is_plugin === true) out.is_plugin = true;
+	if (row.is_debug_label === true) out.is_debug_label = true;
+	return out;
+}
+
+function summarizeProfile(
+	rawJson: string,
+	profile: ProfilingInfo,
+	requestData: Record<string, unknown>,
+	durationMs: number,
+	frequency: number,
+	eventPlayerName: string | undefined,
+): Record<string, unknown> {
+	const funcs = typeIs(profile.Functions, "table") ? profile.Functions : [];
+	const nodes = typeIs(profile.Nodes, "table") ? profile.Nodes : [];
+	const categories = typeIs(profile.Categories, "table") ? profile.Categories : [];
+	const maxFunctions = normalizeMaxFunctions(requestData.max_functions);
+	const minTotalUs = normalizeMinTotalUs(requestData);
+	const includeNative = requestData.include_native === true;
+	const includePlugin = requestData.include_plugin === true;
+	const filter = typeIs(requestData.filter, "string") && requestData.filter !== "" ? requestData.filter as string : undefined;
+
+	const rows: FunctionRow[] = [];
+	const debugRows: FunctionRow[] = [];
+	let omittedNative = 0;
+	let omittedPlugin = 0;
+	let omittedBelowThreshold = 0;
+	let omittedByFilter = 0;
+
+	for (let i = 0; i < funcs.size(); i++) {
+		const func = funcs[i];
+		if (!typeIs(func, "table")) continue;
+		const info = func as FunctionInfo;
+		const totalUs = typeIs(info.TotalDuration, "number") ? info.TotalDuration : 0;
+		const name = functionDisplayName(info);
+		const row: FunctionRow = {
+			function_index: i + 1,
+			name,
+			source: typeIs(info.Source, "string") ? info.Source : undefined,
+			line: typeIs(info.Line, "number") ? info.Line : undefined,
+			total_us: totalUs,
+			is_native: isNativeFunction(info) ? true : undefined,
+			is_plugin: isPluginFunction(info) ? true : undefined,
+			is_debug_label: isDebugLabel(info, filter) ? true : undefined,
+		};
+
+		if (!includeNative && row.is_native === true) {
+			omittedNative += 1;
+			continue;
+		}
+		if (!includePlugin && row.is_plugin === true) {
+			omittedPlugin += 1;
+			continue;
+		}
+		if (totalUs < minTotalUs) {
+			omittedBelowThreshold += 1;
+			continue;
+		}
+		if (filter !== undefined) {
+			const text = `${row.name} ${row.source ?? ""}`;
+			if (!stringContains(text, filter)) {
+				omittedByFilter += 1;
+				continue;
+			}
+		}
+		rows.push(row);
+		if (row.is_debug_label === true) debugRows.push(row);
+	}
+
+	rows.sort((a, b) => a.total_us > b.total_us);
+	debugRows.sort((a, b) => a.total_us > b.total_us);
+
+	const topFunctions: Record<string, unknown>[] = [];
+	for (let i = 0; i < math.min(maxFunctions, rows.size()); i++) {
+		topFunctions.push(compactFunction(rows[i], i + 1, durationMs));
+	}
+
+	const debugLabels: Record<string, unknown>[] = [];
+	for (let i = 0; i < math.min(maxFunctions, debugRows.size()); i++) {
+		debugLabels.push(compactFunction(debugRows[i], i + 1, durationMs));
+	}
+
+	const categoryNames: string[] = [];
+	for (let i = 0; i < categories.size(); i++) {
+		const category = categories[i];
+		if (typeIs(category, "table")) {
+			const name = (category as CategoryInfo).Name;
+			if (typeIs(name, "string")) categoryNames.push(name);
+		}
+	}
+
+	const omitted: Record<string, number> = {};
+	let hasOmitted = false;
+	if (omittedNative > 0) {
+		omitted.native = omittedNative;
+		hasOmitted = true;
+	}
+	if (omittedPlugin > 0) {
+		omitted.plugin = omittedPlugin;
+		hasOmitted = true;
+	}
+	if (omittedBelowThreshold > 0) {
+		omitted.below_min_total_us = omittedBelowThreshold;
+		hasOmitted = true;
+	}
+	if (omittedByFilter > 0) {
+		omitted.filtered_out = omittedByFilter;
+		hasOmitted = true;
+	}
+
+	const result: Record<string, unknown> = {
+		ok: true,
+		duration_ms: durationMs,
+		frequency,
+		applied: {
+			filter: filter ?? undefined,
+			min_total_us: minTotalUs,
+			include_native: includeNative,
+			include_plugin: includePlugin,
+			max_functions: maxFunctions,
+			sort: "total_us_desc",
+		},
+		json_bytes: rawJson.size(),
+		counts: {
+			categories: categories.size(),
+			nodes: nodes.size(),
+			functions: funcs.size(),
+		},
+		top_functions: topFunctions,
+		debug_labels: debugLabels,
+	};
+	if (categoryNames.size() > 0) result.categories = categoryNames;
+	if (hasOmitted) result.omitted = omitted;
+	if (profile.Version !== undefined) result.version = profile.Version;
+	if (profile.SessionStartTime !== undefined || profile.SessionEndTime !== undefined) {
+		result.session = {
+			start_time: profile.SessionStartTime,
+			end_time: profile.SessionEndTime,
+		};
+	}
+	if (eventPlayerName !== undefined) result.player = eventPlayerName;
+	if (requestData.__mcp_include_raw_json === true) result.raw_json = rawJson;
+	return result;
+}
+
+function captureScriptProfiler(requestData: Record<string, unknown>): unknown {
+	if (!RunService.IsRunning()) {
+		return {
+			error: "runtime_target_required",
+			message: "Script profiler capture requires a running playtest target such as target=\"server\" or target=\"client-1\".",
+		};
+	}
+
+	const serviceOrError = getProfilerService();
+	if (!serviceOrError.IsA) return serviceOrError;
+	const service = serviceOrError as ScriptProfilerServiceLike;
+
+	const durationMs = normalizeDurationMs(requestData.duration_ms);
+	const frequency = normalizeFrequency(requestData.frequency);
+	const isServer = RunService.IsServer();
+	const isClient = RunService.IsClient() && !isServer;
+	const player = isClient ? localPlayer() : undefined;
+	if (!isServer && !player) {
+		return {
+			error: "client_player_unavailable",
+			message: "Could not resolve Players.LocalPlayer for client profiling.",
+		};
+	}
+
+	let rawJson: string | undefined;
+	let eventPlayerName: string | undefined;
+	const connection = service.OnNewData.Connect((playerArg: Player | undefined, jsonString: string) => {
+		if (rawJson !== undefined) return;
+		rawJson = jsonString;
+		if (playerArg) eventPlayerName = playerArg.Name;
+	});
+
+	const [startOk, startErr] = pcall(() => {
+		if (isServer) {
+			service.ServerStart(frequency);
+		} else {
+			service.ClientStart(player!, frequency);
+		}
+	});
+	if (!startOk) {
+		connection.Disconnect();
+		return {
+			error: "script_profiler_start_failed",
+			message: tostring(startErr),
+		};
+	}
+
+	task.wait(durationMs / 1000);
+
+	const [stopOk, stopErr] = pcall(() => {
+		if (isServer) {
+			service.ServerStop();
+			service.ServerRequestData();
+		} else {
+			service.ClientStop(player!);
+			service.ClientRequestData(player!);
+		}
+	});
+	if (!stopOk) {
+		connection.Disconnect();
+		return {
+			error: "script_profiler_stop_failed",
+			message: tostring(stopErr),
+		};
+	}
+
+	const requestedAt = tick();
+	while (rawJson === undefined && tick() - requestedAt < 5) {
+		task.wait(0.05);
+	}
+	connection.Disconnect();
+
+	if (rawJson === undefined) {
+		return {
+			error: "script_profiler_data_timeout",
+			message: "ScriptProfilerService did not emit OnNewData after requesting profiler data.",
+		};
+	}
+
+	const [decodeOk, decoded] = pcall(() => HttpService.JSONDecode(rawJson!));
+	if (!decodeOk) {
+		return {
+			error: "script_profiler_decode_failed",
+			message: tostring(decoded),
+			json_bytes: rawJson.size(),
+		};
+	}
+
+	return summarizeProfile(rawJson, decoded as ProfilingInfo, requestData, durationMs, frequency, eventPlayerName);
+}
+
+export = { captureScriptProfiler };

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

@@ -0,0 +1,172 @@
+import { RunService } from "@rbxts/services";
+import Utils from "../Utils";
+import Recording from "../Recording";
+
+// SerializationService:SerializeInstancesAsync / DeserializeInstancesAsync were
+// added in engine v668 and are PluginSecurity. They are not in @rbxts/types yet,
+// so we resolve the service through an untyped GetService cast and treat the
+// methods as opaque (buffer in / buffer out).
+type SerializationServiceShape = {
+	SerializeInstancesAsync(this: SerializationServiceShape, instances: Instance[]): buffer;
+	DeserializeInstancesAsync(this: SerializationServiceShape, b: buffer): Instance[];
+};
+
+const SerializationService = (game as unknown as {
+	GetService(name: string): SerializationServiceShape;
+}).GetService("SerializationService");
+
+// EncodingService:Base64Encode / Base64Decode take and return `buffer` (not
+// `string`). The signature is in @rbxts/types under None.d.ts so a normal
+// GetService("EncodingService") would already give correct types, but @rbxts
+// generates a per-service nominal interface and roblox.d.ts doesn't re-export
+// EncodingService from the services barrel module - so the typed cast below
+// matches what GetService would give us if it did.
+type EncodingServiceShape = {
+	Base64Encode(this: EncodingServiceShape, input: buffer): buffer;
+	Base64Decode(this: EncodingServiceShape, input: buffer): buffer;
+};
+
+const EncodingService = (game as unknown as {
+	GetService(name: string): EncodingServiceShape;
+}).GetService("EncodingService");
+
+const { getInstanceByPath, getInstancePath } = Utils;
+const { beginRecording, finishRecording } = Recording;
+
+function exportRbxm(requestData: Record<string, unknown>): unknown {
+	const instancePaths = requestData.instance_paths as string[] | undefined;
+	if (!instancePaths || !typeIs(instancePaths, "table") || instancePaths.size() === 0) {
+		return { error: "instance_paths must be a non-empty array" };
+	}
+
+	const instances: Instance[] = [];
+	for (const p of instancePaths) {
+		const inst = getInstanceByPath(p);
+		if (!inst) {
+			return { error: `instance not found: ${p}` };
+		}
+		instances.push(inst);
+	}
+
+	const [serializeOk, serializeResult] = pcall(() => {
+		return SerializationService.SerializeInstancesAsync(instances);
+	});
+	if (!serializeOk) {
+		return { error: `SerializeInstancesAsync failed: ${tostring(serializeResult)}` };
+	}
+
+	const buf = serializeResult as buffer;
+	const [encodeOk, encodeResult] = pcall(() => EncodingService.Base64Encode(buf));
+	if (!encodeOk) {
+		return { error: `EncodingService:Base64Encode failed: ${tostring(encodeResult)}` };
+	}
+	// Base64Encode returns a buffer of ASCII bytes; convert to a Lua string so
+	// HttpService:JSONEncode (called by the harness in Communication.ts) accepts
+	// it. Base64 is by definition pure ASCII so this round-trips cleanly.
+	const base64Str = buffer.tostring(encodeResult as buffer);
+
+	return {
+		base64: base64Str,
+		instance_count: instances.size(),
+	};
+}
+
+function importRbxm(requestData: Record<string, unknown>): unknown {
+	const b64 = requestData.base64 as string | undefined;
+	const parentPath = requestData.parent_path as string | undefined;
+	const sourceLabel = (requestData.source_label as string | undefined) ?? "unknown";
+
+	if (!b64 || !typeIs(b64, "string")) {
+		return { error: "base64 payload is required" };
+	}
+	if (!parentPath || !typeIs(parentPath, "string")) {
+		return { error: "parent_path is required" };
+	}
+
+	const parentInstance = getInstanceByPath(parentPath);
+	if (!parentInstance) {
+		return { error: `parent instance not found: ${parentPath}` };
+	}
+
+	// b64 is an ASCII-only Lua string from the wire; lift it into a buffer for
+	// EncodingService:Base64Decode, which returns a buffer of raw rbxm bytes
+	// ready for DeserializeInstancesAsync.
+	const [b64BufOk, b64BufResult] = pcall(() => buffer.fromstring(b64));
+	if (!b64BufOk) {
+		return { error: `buffer.fromstring(base64) failed: ${tostring(b64BufResult)}` };
+	}
+	const [decodeOk, decodeResult] = pcall(() => EncodingService.Base64Decode(b64BufResult as buffer));
+	if (!decodeOk) {
+		return { error: `EncodingService:Base64Decode failed: ${tostring(decodeResult)}` };
+	}
+	const buf = decodeResult as buffer;
+
+	const [deserOk, deserResult] = pcall(() => {
+		return SerializationService.DeserializeInstancesAsync(buf);
+	});
+	if (!deserOk) {
+		return { error: `DeserializeInstancesAsync failed: ${tostring(deserResult)}` };
+	}
+	const deserialized = deserResult as Instance[];
+
+	// All-or-nothing parenting. Track every instance we've attached and roll back
+	// (unparent + Destroy) if any later one fails - partial imports leave the DM
+	// in a worse state than failing cleanly.
+	const isEdit = !RunService.IsRunning();
+	const recordingId = isEdit ? beginRecording(`Import rbxm`) : undefined;
+
+	const attached: Instance[] = [];
+	let failureMessage: string | undefined;
+	for (const inst of deserialized) {
+		const [parentOk, parentErr] = pcall(() => {
+			inst.Parent = parentInstance;
+		});
+		if (!parentOk) {
+			failureMessage = `failed to parent ${inst.Name} (${inst.ClassName}) under ${parentPath}: ${tostring(parentErr)}`;
+			break;
+		}
+		attached.push(inst);
+	}
+
+	if (failureMessage !== undefined) {
+		for (const inst of attached) {
+			pcall(() => {
+				inst.Parent = undefined;
+				inst.Destroy();
+			});
+		}
+		// Also destroy any unparented deserialized instances so they don't leak.
+		for (const inst of deserialized) {
+			if (inst.Parent === undefined) {
+				pcall(() => inst.Destroy());
+			}
+		}
+		finishRecording(recordingId, false);
+		return { error: failureMessage };
+	}
+
+	const names: string[] = [];
+	const paths: string[] = [];
+	for (const inst of attached) {
+		names.push(inst.Name);
+		paths.push(getInstancePath(inst));
+	}
+
+	// The recording shows "MCP: Import rbxm" in Studio's undo stack -
+	// ChangeHistoryService doesn't expose a way to set a richer displayName
+	// after TryBeginRecording, so the count/source only land in the JSON response.
+	finishRecording(recordingId, true);
+
+	return {
+		instance_count: attached.size(),
+		instance_names: names,
+		instance_paths: paths,
+		parent_path: parentPath,
+		source: sourceLabel,
+	};
+}
+
+export = {
+	exportRbxm,
+	importRbxm,
+};