@chrrxs/robloxstudio-mcp 3.0.0 → 3.0.2

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

@@ -1,460 +0,0 @@
-import Utils from "../Utils";
-
-const { getInstanceByPath } = Utils;
-
-const HttpService = game.GetService("HttpService");
-const RunService = game.GetService("RunService");
-const ServerStorage = game.GetService("ServerStorage");
-
-const LOG_PREFIX = "Breakpoint";
-const REGISTRY_KEY_PREFIX = "MCP_BREAKPOINTS_V1_";
-const MCP_PLACE_ID_ATTRIBUTE = "__MCPPlaceId";
-
-let pluginRef: Plugin | undefined;
-let loadedRegistryKey: string | undefined;
-let loadedRegistryFromSettings = false;
-
-interface ScriptBreakpointSpec {
-	Line: number;
-	Enabled?: boolean;
-	Condition?: string;
-	LogMessage?: string;
-	ContinueExecution?: boolean;
-}
-
-interface ScriptBreakpointResult {
-	Verified?: boolean;
-	Line?: number;
-	Message?: string;
-}
-
-interface ScriptDebuggerServiceLike extends Instance {
-	AddBreakpoint(this: ScriptDebuggerServiceLike, script: Instance, breakpoint: ScriptBreakpointSpec): ScriptBreakpointResult;
-	RemoveBreakpoint(this: ScriptDebuggerServiceLike, script: Instance, line: number): boolean;
-	ClearBreakpoints(this: ScriptDebuggerServiceLike): void;
-}
-
-interface BreakpointEntry {
-	script_path: string;
-	line: number;
-	requested_line?: number;
-	enabled?: boolean;
-	condition?: string;
-	log_message?: string;
-	continue_execution?: boolean;
-	verified?: false;
-	message?: string;
-	created_at?: number;
-}
-
-interface PersistedBreakpointEntry {
-	script_path: string;
-	line: number;
-}
-
-interface RegistryScope {
-	key: string;
-}
-
-const breakpoints = new Map<string, BreakpointEntry>();
-
-function init(p: Plugin): void {
-	pluginRef = p;
-}
-
-function breakpointKey(scriptPath: string, line: number): string {
-	return `${scriptPath}:${line}`;
-}
-
-function computeInstanceId(): string {
-	if (game.PlaceId !== 0) {
-		return `place:${tostring(game.PlaceId)}`;
-	}
-	const existing = ServerStorage.GetAttribute(MCP_PLACE_ID_ATTRIBUTE);
-	if (typeIs(existing, "string") && existing !== "") {
-		return `anon:${existing as string}`;
-	}
-	const fresh = HttpService.GenerateGUID(false);
-	pcall(() => ServerStorage.SetAttribute(MCP_PLACE_ID_ATTRIBUTE, fresh));
-	return `anon:${fresh}`;
-}
-
-function detectRole(): string {
-	if (!RunService.IsRunning()) return "edit";
-	if (RunService.IsServer()) return "server";
-	return "client";
-}
-
-function requestedRole(requestData: Record<string, unknown>): string {
-	return typeIs(requestData.__mcp_target_role, "string") && requestData.__mcp_target_role !== ""
-		? requestData.__mcp_target_role as string
-		: detectRole();
-}
-
-function registryScope(requestData: Record<string, unknown>): RegistryScope {
-	const instanceId = typeIs(requestData.__mcp_instance_id, "string") && requestData.__mcp_instance_id !== ""
-		? requestData.__mcp_instance_id as string
-		: computeInstanceId();
-	const role = requestedRole(requestData);
-	return {
-		key: `${REGISTRY_KEY_PREFIX}${instanceId}:${role}`,
-	};
-}
-
-function readSetting(key: string): unknown {
-	if (!pluginRef) return undefined;
-	const [ok, value] = pcall(() => pluginRef!.GetSetting(key));
-	return ok ? value : undefined;
-}
-
-function writeSetting(key: string, value: unknown): boolean {
-	if (!pluginRef) return false;
-	const [ok] = pcall(() => pluginRef!.SetSetting(key, value));
-	return ok;
-}
-
-function decodePersistedBreakpointEntry(value: unknown): BreakpointEntry | undefined {
-	if (!typeIs(value, "table")) return undefined;
-	const data = value as Record<string, unknown>;
-	if (!typeIs(data.script_path, "string") || data.script_path === "") return undefined;
-	if (!typeIs(data.line, "number") || data.line < 1) return undefined;
-
-	return {
-		script_path: data.script_path as string,
-		line: math.floor(data.line as number),
-	};
-}
-
-function loadRegistry(requestData: Record<string, unknown>): RegistryScope {
-	const scope = registryScope(requestData);
-	if (loadedRegistryKey !== scope.key) {
-		breakpoints.clear();
-		loadedRegistryKey = scope.key;
-		loadedRegistryFromSettings = false;
-	}
-
-	if (loadedRegistryFromSettings) return scope;
-	loadedRegistryFromSettings = true;
-
-	const stored = readSetting(scope.key);
-	if (stored === undefined) return scope;
-
-	let decoded: unknown = stored;
-	if (typeIs(stored, "string")) {
-		const [ok, result] = pcall(() => HttpService.JSONDecode(stored as string));
-		if (!ok) return scope;
-		decoded = result;
-	}
-	if (!typeIs(decoded, "table")) return scope;
-
-	breakpoints.clear();
-	for (const item of decoded as unknown[]) {
-		const entry = decodePersistedBreakpointEntry(item);
-		if (entry) {
-			breakpoints.set(breakpointKey(entry.script_path, entry.line), entry);
-		}
-	}
-	return scope;
-}
-
-interface PersistResult {
-	ok: boolean;
-	error?: string;
-}
-
-function persistRegistry(scope: RegistryScope): PersistResult {
-	if (!pluginRef) return { ok: false, error: "Plugin settings are unavailable; managed breakpoint registry is memory-only." };
-
-	const out: PersistedBreakpointEntry[] = [];
-	for (const [, entry] of breakpoints) {
-		out.push({
-			script_path: entry.script_path,
-			line: entry.line,
-		});
-	}
-
-	const [encodedOk, encoded] = pcall(() => HttpService.JSONEncode(out));
-	if (!encodedOk || !typeIs(encoded, "string")) {
-		return { ok: false, error: `Failed to encode managed breakpoint registry: ${tostring(encoded)}` };
-	}
-	if (!writeSetting(scope.key, encoded)) {
-		return { ok: false, error: "Failed to persist managed breakpoint registry with plugin:SetSetting." };
-	}
-	const stored = readSetting(scope.key);
-	if (stored !== encoded) {
-		return { ok: false, error: "Failed to verify managed breakpoint registry persistence after plugin:SetSetting." };
-	}
-	return { ok: true };
-}
-
-function attachPersistenceWarning(response: Record<string, unknown>, persist: PersistResult): Record<string, unknown> {
-	if (!persist.ok) {
-		response.managed_registry_persisted = false;
-		response.registry_error = persist.error;
-	}
-	return response;
-}
-
-function serviceError(message?: string): Record<string, unknown> {
-	return {
-		error: "script_debugger_unavailable",
-		message: message ?? "ScriptDebuggerService is unavailable. Enable the Studio Debugger Luau API beta feature and restart Studio.",
-		betaFeatureRequired: true,
-	};
-}
-
-function operationError(errorCode: string, operation: string, raw: unknown): Record<string, unknown> {
-	return {
-		error: errorCode,
-		message:
-			`${operation} failed. The breakpoints tool requires the Studio Debugger Luau API beta feature. ` +
-			"Enable it in Studio Beta Features and restart/reload Studio, then retry.",
-		rawMessage: tostring(raw),
-		betaFeatureRequired: true,
-	};
-}
-
-function getService(): ScriptDebuggerServiceLike | Record<string, unknown> {
-	const provider = game as unknown as { GetService(serviceName: string): Instance };
-	const [ok, service] = pcall(() => provider.GetService("ScriptDebuggerService") as ScriptDebuggerServiceLike);
-	if (!ok || !service) {
-		return serviceError(`ScriptDebuggerService unavailable: ${tostring(service)}`);
-	}
-	return service;
-}
-
-function luauStringLiteral(value: string): string {
-	let escaped = value.gsub("\\", "\\\\")[0];
-	escaped = escaped.gsub("\n", "\\n")[0];
-	escaped = escaped.gsub("\r", "\\r")[0];
-	escaped = escaped.gsub("\t", "\\t")[0];
-	escaped = escaped.gsub('"', '\\"')[0];
-	return `"${escaped}"`;
-}
-
-function buildLogMessage(scriptPath: string, line: number, logMessage: string | undefined): string {
-	const prefix = [
-		luauStringLiteral(LOG_PREFIX),
-		luauStringLiteral(`${scriptPath}:${line}`),
-	];
-	if (typeIs(logMessage, "string") && logMessage !== "") {
-		prefix.push(logMessage);
-	}
-	return prefix.join(", ");
-}
-
-function listBreakpoints(requestData: Record<string, unknown>): Record<string, unknown> {
-	loadRegistry(requestData);
-	const out: BreakpointEntry[] = [];
-	for (const [, entry] of breakpoints) {
-		out.push(entry);
-	}
-	return {
-		breakpoints: out,
-		count: out.size(),
-	};
-}
-
-function setBreakpoint(requestData: Record<string, unknown>): unknown {
-	const scope = loadRegistry(requestData);
-	const serviceOrError = getService();
-	if (!serviceOrError.IsA) return serviceOrError;
-	const service = serviceOrError as ScriptDebuggerServiceLike;
-
-	const scriptPath = requestData.script_path as string | undefined;
-	const lineRaw = requestData.line as number | undefined;
-	if (!typeIs(scriptPath, "string") || scriptPath === "" || !typeIs(lineRaw, "number")) {
-		return { error: "invalid_args", message: "breakpoints action=set requires script_path and line" };
-	}
-
-	const requestedLine = math.floor(lineRaw);
-	if (requestedLine < 1) {
-		return { error: "invalid_line", message: "line must be a 1-based positive number" };
-	}
-
-	const instance = getInstanceByPath(scriptPath);
-	if (!instance) return { error: "script_not_found", script_path: scriptPath };
-	if (!instance.IsA("LuaSourceContainer")) {
-		return {
-			error: "not_a_script",
-			message: `${scriptPath} is ${instance.ClassName}, not a LuaSourceContainer`,
-			script_path: scriptPath,
-		};
-	}
-
-	const rawLogMessage = typeIs(requestData.log_message, "string") ? requestData.log_message as string : undefined;
-	const hasLogMessage = rawLogMessage !== undefined && rawLogMessage !== "";
-	const continueExecution = typeIs(requestData.continue_execution, "boolean")
-		? requestData.continue_execution as boolean
-		: hasLogMessage;
-	const enabled = typeIs(requestData.enabled, "boolean") ? requestData.enabled as boolean : true;
-	const effectiveLogMessage = hasLogMessage || continueExecution ? buildLogMessage(scriptPath, requestedLine, rawLogMessage) : undefined;
-
-	const spec: ScriptBreakpointSpec = {
-		Line: requestedLine,
-		Enabled: enabled,
-		ContinueExecution: continueExecution,
-	};
-	if (typeIs(requestData.condition, "string") && requestData.condition !== "") {
-		spec.Condition = requestData.condition as string;
-	}
-	if (effectiveLogMessage !== undefined) {
-		spec.LogMessage = effectiveLogMessage;
-	}
-
-	const [ok, result] = pcall(() => service.AddBreakpoint(instance, spec));
-	if (!ok) return operationError("add_breakpoint_failed", "ScriptDebuggerService:AddBreakpoint", result);
-
-	const breakpointResult = result as ScriptBreakpointResult;
-	const actualLine = typeIs(breakpointResult.Line, "number") ? breakpointResult.Line : requestedLine;
-	const verified = typeIs(breakpointResult.Verified, "boolean") ? breakpointResult.Verified : undefined;
-	const message = typeIs(breakpointResult.Message, "string") ? breakpointResult.Message : undefined;
-	const entry: BreakpointEntry = {
-		script_path: scriptPath,
-		line: actualLine,
-		requested_line: actualLine !== requestedLine ? requestedLine : undefined,
-		enabled,
-		condition: spec.Condition,
-		log_message: rawLogMessage,
-		continue_execution: continueExecution,
-		verified: verified === false ? false : undefined,
-		message,
-		created_at: DateTime.now().UnixTimestampMillis,
-	};
-
-	breakpoints.set(breakpointKey(scriptPath, actualLine), entry);
-	return attachPersistenceWarning({
-		ok: true,
-		breakpoint: entry,
-	}, persistRegistry(scope));
-}
-
-function removeBreakpoint(requestData: Record<string, unknown>): unknown {
-	const scope = loadRegistry(requestData);
-	const serviceOrError = getService();
-	if (!serviceOrError.IsA) return serviceOrError;
-	const service = serviceOrError as ScriptDebuggerServiceLike;
-
-	const scriptPath = requestData.script_path as string | undefined;
-	const lineRaw = requestData.line as number | undefined;
-	if (!typeIs(scriptPath, "string") || scriptPath === "" || !typeIs(lineRaw, "number")) {
-		return { error: "invalid_args", message: "breakpoints action=remove requires script_path and line" };
-	}
-	const line = math.floor(lineRaw);
-	if (line < 1) {
-		return { error: "invalid_line", message: "line must be a 1-based positive number" };
-	}
-
-	const instance = getInstanceByPath(scriptPath);
-	if (!instance) return { error: "script_not_found", script_path: scriptPath };
-	if (!instance.IsA("LuaSourceContainer")) {
-		return {
-			error: "not_a_script",
-			message: `${scriptPath} is ${instance.ClassName}, not a LuaSourceContainer`,
-			script_path: scriptPath,
-		};
-	}
-
-	const [ok, removed] = pcall(() => service.RemoveBreakpoint(instance, line));
-	if (!ok) return operationError("remove_breakpoint_failed", "ScriptDebuggerService:RemoveBreakpoint", removed);
-
-	breakpoints.delete(breakpointKey(scriptPath, line));
-	return attachPersistenceWarning({
-		ok: true,
-		removed,
-		script_path: scriptPath,
-		line,
-	}, persistRegistry(scope));
-}
-
-function clearManagedBreakpoints(requestData: Record<string, unknown>): unknown {
-	const scope = loadRegistry(requestData);
-	const serviceOrError = getService();
-	if (!serviceOrError.IsA) return serviceOrError;
-	const service = serviceOrError as ScriptDebuggerServiceLike;
-
-	let cleared = 0;
-	const errors: Record<string, unknown>[] = [];
-
-	for (const [key, entry] of breakpoints) {
-		const instance = getInstanceByPath(entry.script_path);
-		if (!instance || !instance.IsA("LuaSourceContainer")) {
-			breakpoints.delete(key);
-			cleared += 1;
-			continue;
-		}
-
-		const [ok, removedOrError] = pcall(() => service.RemoveBreakpoint(instance, entry.line));
-		if (ok) {
-			breakpoints.delete(key);
-			cleared += 1;
-		} else {
-			errors.push({
-				script_path: entry.script_path,
-				line: entry.line,
-				error: tostring(removedOrError),
-			});
-		}
-	}
-
-	if (errors.size() > 0) {
-		return {
-			ok: false,
-			cleared,
-			errors,
-		};
-	}
-
-	return attachPersistenceWarning({
-		ok: true,
-		cleared,
-	}, persistRegistry(scope));
-}
-
-function clearAllBreakpoints(requestData: Record<string, unknown>): unknown {
-	const scope = loadRegistry(requestData);
-	const serviceOrError = getService();
-	if (!serviceOrError.IsA) return serviceOrError;
-	const service = serviceOrError as ScriptDebuggerServiceLike;
-
-	const managedCount = breakpoints.size();
-	const [ok, err] = pcall(() => service.ClearBreakpoints());
-	if (!ok) return operationError("clear_breakpoints_failed", "ScriptDebuggerService:ClearBreakpoints", err);
-	breakpoints.clear();
-	return attachPersistenceWarning({
-		ok: true,
-		cleared_managed: managedCount,
-	}, persistRegistry(scope));
-}
-
-function clearBreakpoints(requestData: Record<string, unknown>): unknown {
-	if (requestData.clear_all === true) {
-		return clearAllBreakpoints(requestData);
-	}
-	return clearManagedBreakpoints(requestData);
-}
-
-function breakpointsTool(requestData: Record<string, unknown>): unknown {
-	const action = requestData.action as string | undefined;
-	if (!typeIs(action, "string") || action === "") {
-		return { error: "invalid_args", message: "breakpoints requires action=set|remove|clear|list" };
-	}
-
-	switch (action) {
-		case "set":
-			return setBreakpoint(requestData);
-		case "remove":
-			return removeBreakpoint(requestData);
-		case "clear":
-			return clearBreakpoints(requestData);
-		case "list":
-			return listBreakpoints(requestData);
-		default:
-			return {
-				error: "unknown_action",
-				message: `breakpoints action must be one of: set, remove, clear, list (got ${action})`,
-			};
-	}
-}
-
-export = { breakpoints: breakpointsTool, init };

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

@@ -1,170 +0,0 @@
-import * as RenderMonitor from "../RenderMonitor";
-
-const CaptureService = game.GetService("CaptureService");
-const AssetService = game.GetService("AssetService");
-
-const MAX_TILE_SIZE = 1024;
-const BASE64_CHARS = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
-const PAD_BYTE = string.byte("=")[0];
-
-const B64: number[] = [];
-for (let i = 0; i < 64; i++) {
-	B64[i] = string.byte(BASE64_CHARS, i + 1)[0];
-}
-
-function encodeBase64(buf: buffer): string {
-	const len = buffer.len(buf);
-	const fullTriples = math.floor(len / 3);
-	const remaining = len - fullTriples * 3;
-	const outLen = (fullTriples + (remaining > 0 ? 1 : 0)) * 4;
-	const out = buffer.create(outLen);
-
-	let si = 0;
-	let di = 0;
-
-	for (let t = 0; t < fullTriples; t++) {
-		const b0 = buffer.readu8(buf, si);
-		const b1 = buffer.readu8(buf, si + 1);
-		const b2 = buffer.readu8(buf, si + 2);
-
-		buffer.writeu8(out, di, B64[bit32.rshift(b0, 2)]);
-		buffer.writeu8(out, di + 1, B64[bit32.bor(bit32.lshift(bit32.band(b0, 3), 4), bit32.rshift(b1, 4))]);
-		buffer.writeu8(out, di + 2, B64[bit32.bor(bit32.lshift(bit32.band(b1, 15), 2), bit32.rshift(b2, 6))]);
-		buffer.writeu8(out, di + 3, B64[bit32.band(b2, 63)]);
-
-		si += 3;
-		di += 4;
-	}
-
-	if (remaining === 2) {
-		const b0 = buffer.readu8(buf, si);
-		const b1 = buffer.readu8(buf, si + 1);
-		buffer.writeu8(out, di, B64[bit32.rshift(b0, 2)]);
-		buffer.writeu8(out, di + 1, B64[bit32.bor(bit32.lshift(bit32.band(b0, 3), 4), bit32.rshift(b1, 4))]);
-		buffer.writeu8(out, di + 2, B64[bit32.lshift(bit32.band(b1, 15), 2)]);
-		buffer.writeu8(out, di + 3, PAD_BYTE);
-	} else if (remaining === 1) {
-		const b0 = buffer.readu8(buf, si);
-		buffer.writeu8(out, di, B64[bit32.rshift(b0, 2)]);
-		buffer.writeu8(out, di + 1, B64[bit32.lshift(bit32.band(b0, 3), 4)]);
-		buffer.writeu8(out, di + 2, PAD_BYTE);
-		buffer.writeu8(out, di + 3, PAD_BYTE);
-	}
-
-	return buffer.tostring(out);
-}
-
-function readPixelsTiled(img: EditableImage, w: number, h: number): buffer {
-	const BYTES_PER_PIXEL = 4;
-	const fullBuf = buffer.create(w * h * BYTES_PER_PIXEL);
-	const fullRowBytes = w * BYTES_PER_PIXEL;
-
-	for (let ty = 0; ty < h; ty += MAX_TILE_SIZE) {
-		const tileH = math.min(MAX_TILE_SIZE, h - ty);
-		for (let tx = 0; tx < w; tx += MAX_TILE_SIZE) {
-			const tileW = math.min(MAX_TILE_SIZE, w - tx);
-			const tileBuf = img.ReadPixelsBuffer(new Vector2(tx, ty), new Vector2(tileW, tileH));
-			const tileRowBytes = tileW * BYTES_PER_PIXEL;
-			for (let row = 0; row < tileH; row++) {
-				buffer.copy(fullBuf, (ty + row) * fullRowBytes + tx * BYTES_PER_PIXEL, tileBuf, row * tileRowBytes, tileRowBytes);
-			}
-		}
-	}
-	return fullBuf;
-}
-
-// Triggers CaptureService:CaptureScreenshot and waits for the temporary
-// content id. Works in any DM, including the play CLIENT (where reading the
-// pixels back is blocked, but capturing is not). The returned rbxtemp:// id is
-// a process-scoped handle: it can be dereferenced from a DIFFERENT, more
-// privileged DM (the edit DM) — see captureRead.
-function doCaptureScreenshot(): { contentId: string } | { error: string } {
-	// Fast-fail with a clear reason if the window isn't rendering — otherwise
-	// CaptureScreenshot's callback never fires and we'd block for the full 10s.
-	const notRendering = RenderMonitor.notRenderingReason();
-	if (notRendering !== undefined) return { error: notRendering };
-
-	let contentId: string | undefined;
-
-	CaptureService.CaptureScreenshot((id: string) => {
-		contentId = id;
-	});
-
-	const startTime = tick();
-	while (contentId === undefined) {
-		if (tick() - startTime > 10) {
-			return {
-				error: "Screenshot capture timed out (CaptureScreenshot callback never fired). The Studio window is likely minimized or occluded — restore it so the viewport renders. (Known Roblox bug: capture can also fail if the viewport renders a solid color.)",
-			};
-		}
-		task.wait(0.1);
-	}
-
-	return { contentId };
-}
-
-// Promotes a CaptureScreenshot content id into an EditableImage and reads its
-// RGBA pixels. MUST run in the edit/plugin context: the running game VM lacks
-// the privilege to create an EditableImage from a temporary texture id (errors
-// "cannot currently create editable image from temporary texture id"), while
-// the edit DM can — even for an id captured in the play client DM.
-function readContentToBase64(contentId: string): unknown {
-	const [editableOk, editableResult] = pcall(() => {
-		return AssetService.CreateEditableImageAsync(Content.fromUri(contentId));
-	});
-
-	if (!editableOk) {
-		return {
-			error: `Failed to create EditableImage from screenshot. Enable EditableImage API: Game Settings > Security > 'Allow Mesh / Image APIs'. (${tostring(editableResult)})`,
-		};
-	}
-
-	const editableImage = editableResult as EditableImage;
-	const imgSize = editableImage.Size;
-	const w = math.floor(imgSize.X);
-	const h = math.floor(imgSize.Y);
-
-	const [readOk, pixelBuffer] = pcall(() => {
-		return readPixelsTiled(editableImage, w, h);
-	});
-
-	editableImage.Destroy();
-
-	if (!readOk) {
-		return { error: `Failed to read pixel data: ${tostring(pixelBuffer)}` };
-	}
-
-	const base64Data = encodeBase64(pixelBuffer as buffer);
-
-	return { success: true, width: w, height: h, data: base64Data };
-}
-
-// Edit-mode single shot: capture and read back in the same (edit) context.
-function captureScreenshotData(): unknown {
-	const cap = doCaptureScreenshot();
-	if ("error" in cap) return cap;
-	return readContentToBase64(cap.contentId);
-}
-
-function captureScreenshot(): unknown {
-	return captureScreenshotData();
-}
-
-// Play-mode step 1 (run on the CLIENT): capture only, return the temp id.
-function captureBegin(): unknown {
-	return doCaptureScreenshot();
-}
-
-// Play-mode step 2 (run on EDIT): read pixels from a temp id captured elsewhere.
-function captureRead(requestData: Record<string, unknown>): unknown {
-	const contentId = requestData.contentId as string | undefined;
-	if (!contentId) return { error: "contentId is required" };
-	return readContentToBase64(contentId);
-}
-
-export = {
-	captureScreenshotData,
-	captureScreenshot,
-	captureBegin,
-	captureRead,
-};