@el4cteo/rbx-studio-mcp 0.1.0 → 0.1.1

package/plugin/src/handlers/Input.luau

@@ -45,6 +45,12 @@ local MAX_HOLD = 10
 	source, so a key called `A) print("owned") --` would run. The plan travels as
 	JSON on an attribute instead, and this script only ever indexes enums by name
 	and checks the result.
+
+	It also draws the pointer. Synthetic mouse input moves nothing the eye can
+	follow -- the click lands and the only evidence is whatever it changed -- so
+	anyone watching a playtest being driven sees results with no cause. The
+	cursor is a real ImageLabel tweened to each target before the click is sent,
+	which makes the agent's aim visible and, when it misses, visibly wrong.
 ]]
 local RELAY_SOURCE = [==[
 local UserInputService = game:GetService("UserInputService")
@@ -67,6 +73,154 @@ end
 local virtual = UserInputService:CreateVirtualInput()
 local performed = {}
 
+--[[
+	The on-screen pointer.
+
+	Roblox's own arrow texture, not one of ours. Shipping the pixels was tried
+	first -- base64 in a StringValue, decoded into an EditableImage -- and it
+	cannot work: writing to an EditableImage is gated on an experience-level
+	security setting that is off by default, so every place would have to opt in
+	before the cursor appeared. `WritePixelsBuffer` says so outright ("go to the
+	Security Tab in Experience Settings to enable this API") and the failure was
+	invisible, because a cursor that fails to build just does not show up.
+
+	An image id needs neither. The primary is a public Creator Store pointer;
+	`rbxasset://` content, which ships inside the client itself and can never
+	fail to resolve, is the fallback for the day that asset is moderated or
+	pulled. Both are tinted and given a halo -- the point is to show what the
+	agent is aiming at, and a pointer indistinguishable from the player's own
+	would show nothing.
+]]
+local ARROW = "rbxassetid://15718988485"
+local ARROW_FALLBACK = "rbxasset://textures/Cursors/KeyboardMouse/ArrowCursor.png"
+local ACCENT = Color3.fromRGB(255, 162, 0)
+
+--[[
+	Where each arrow's tip sits inside its own image, as a fraction of it.
+
+	Both measured rather than guessed, and they are nothing alike -- the store
+	image is padded and the built-in one puts its tip at the exact centre of a
+	64x64 square -- so the anchor has to change with the image. Getting this
+	wrong is the quiet kind of wrong: the pointer still glides to the right
+	area and still ripples, it just lies about which pixel it hit.
+
+	The tint only works on a filled arrow. An outline-only cursor multiplies to
+	black and looks like the image failed to load.
+]]
+local HOTSPOT = Vector2.new(0.36, 0.32)
+local HOTSPOT_FALLBACK = Vector2.new(0.484, 0.5)
+
+local cursor = nil
+local cursorGui = nil
+
+local function makeCursor()
+	if relay:GetAttribute("Cursor") ~= true then
+		return
+	end
+
+	local gui = Instance.new("ScreenGui")
+	gui.Name = "MCPCursor"
+	gui.ResetOnSpawn = false
+	gui.IgnoreGuiInset = true
+	gui.DisplayOrder = 2147483647
+	gui.ZIndexBehavior = Enum.ZIndexBehavior.Sibling
+
+	local label = Instance.new("ImageLabel")
+	label.Name = "Pointer"
+	label.BackgroundTransparency = 1
+	label.Size = UDim2.fromOffset(52, 52)
+	label.AnchorPoint = HOTSPOT
+	label.Position = UDim2.fromScale(0.5, 0.5)
+	label.Image = ARROW
+	label.ImageColor3 = ACCENT
+	label.ZIndex = 100
+	label.Parent = gui
+
+	-- Centred on the tip rather than on the image, and behind the arrow, so the
+	-- pointer stays findable against a busy scene without hiding what it targets.
+	local halo = Instance.new("Frame")
+	halo.Name = "Halo"
+	halo.AnchorPoint = Vector2.new(0.5, 0.5)
+	halo.Position = UDim2.fromScale(HOTSPOT.X, HOTSPOT.Y)
+	halo.Size = UDim2.fromOffset(32, 32)
+	halo.BackgroundColor3 = ACCENT
+	halo.BackgroundTransparency = 0.45
+	halo.BorderSizePixel = 0
+	halo.ZIndex = 99
+	local round = Instance.new("UICorner")
+	round.CornerRadius = UDim.new(1, 0)
+	round.Parent = halo
+	halo.Parent = label
+
+	gui.Parent = relay.Parent
+	cursorGui = gui
+	cursor = label
+
+	-- Swapped only if the store image really did not arrive. Checked after the
+	-- GUI is live so the pointer is on screen either way, and never blocks.
+	task.spawn(function()
+		local waited = 0
+		while not label.IsLoaded and waited < 3 do
+			task.wait(0.1)
+			waited += 0.1
+		end
+		if not label.IsLoaded then
+			label.Image = ARROW_FALLBACK
+			-- The tip moves with the image, so the anchor and the halo move too.
+			label.AnchorPoint = HOTSPOT_FALLBACK
+			halo.Position = UDim2.fromScale(HOTSPOT_FALLBACK.X, HOTSPOT_FALLBACK.Y)
+		end
+	end)
+end
+
+-- Moves the pointer there and waits, so the click is seen to be aimed.
+local function moveCursor(x, y, duration)
+	if cursor == nil then
+		return
+	end
+	local TweenService = game:GetService("TweenService")
+	local goal = UDim2.fromOffset(x, y)
+	local tween = TweenService:Create(
+		cursor,
+		TweenInfo.new(duration, Enum.EasingStyle.Quad, Enum.EasingDirection.Out),
+		{ Position = goal }
+	)
+	tween:Play()
+	tween.Completed:Wait()
+end
+
+-- A ring that expands and fades where the click landed.
+local function pulse()
+	if cursor == nil then
+		return
+	end
+	local TweenService = game:GetService("TweenService")
+	local ring = Instance.new("Frame")
+	ring.AnchorPoint = Vector2.new(0.5, 0.5)
+	ring.Position = UDim2.new(cursor.Position.X.Scale, cursor.Position.X.Offset, cursor.Position.Y.Scale, cursor.Position.Y.Offset)
+	ring.Size = UDim2.fromOffset(8, 8)
+	ring.BackgroundColor3 = ACCENT
+	ring.BackgroundTransparency = 0.25
+	ring.BorderSizePixel = 0
+	ring.ZIndex = 99
+	local corner = Instance.new("UICorner")
+	corner.CornerRadius = UDim.new(1, 0)
+	corner.Parent = ring
+	ring.Parent = cursorGui
+
+	local grow = TweenService:Create(
+		ring,
+		TweenInfo.new(0.35, Enum.EasingStyle.Quad, Enum.EasingDirection.Out),
+		{ Size = UDim2.fromOffset(52, 52), BackgroundTransparency = 1 }
+	)
+	grow:Play()
+	grow.Completed:Connect(function()
+		ring:Destroy()
+	end)
+end
+
+makeCursor()
+
 for _, step in plan do
 	local kind = step.kind
 	if kind == "key" then
@@ -81,10 +235,15 @@ for _, step in plan do
 			end
 		end
 	elseif kind == "move" then
+		moveCursor(step.x, step.y, 0.3)
 		virtual:SendMousePosition(Vector2.new(step.x, step.y))
 	elseif kind == "click" then
 		local button = Enum.UserInputType[step.button or "MouseButton1"]
 		local at = Vector2.new(step.x, step.y)
+		-- Travel first, then click. Teleporting the pointer onto the target at
+		-- the same instant it fires looks like nothing happened at all.
+		moveCursor(step.x, step.y, 0.3)
+		pulse()
 		virtual:SendMousePosition(at)
 		virtual:SendMouseButton(at, button, true, 0)
 		if step.action ~= "press" then
@@ -100,6 +259,12 @@ for _, step in plan do
 	end
 end
 
+-- Left up for a moment so the last action is still visible when the tool returns.
+task.wait(0.25)
+if cursorGui ~= nil then
+	cursorGui:Destroy()
+end
+
 report:FireServer({ ok = true, performed = performed })
 ]==]
 
@@ -235,6 +400,7 @@ function Input.send(params: { [string]: any }): { [string]: any }
 	relay.Name = "MCPInputRelay"
 	relay.Source = RELAY_SOURCE
 	relay:SetAttribute("Plan", HttpService:JSONEncode(plan))
+	relay:SetAttribute("Cursor", params.cursor ~= false)
 	remote.Parent = relay
 
 	local answer: { [string]: any }? = nil

package/scripts/prism.mjs

@@ -0,0 +1,310 @@
+/**
+ * Draws the project mark: a triangular prism splitting white light.
+ *
+ * Both outputs come from this one file because they have to agree. The SVG is
+ * for anywhere that takes vector; the PNG exists because GitHub, npm and most
+ * other places reject SVG for an avatar, and hand-keeping two drawings in sync
+ * is how they end up different.
+ *
+ * There is no rasteriser installed and the shapes do not need one: the body is
+ * three flat polygons and the light is a set of bands with a Gaussian falloff
+ * across their width. The PNG is written by the same encoder behind the
+ * `screenshot` tool.
+ *
+ * Usage: node scripts/prism.mjs docs/prism.svg docs/prism.png
+ */
+import { writeFileSync } from "node:fs";
+import { encodePng } from "../dist/lib/png.js";
+
+const SIZE = 512;
+const SS = 3; // subsamples per axis
+
+// --- geometry --------------------------------------------------------------
+
+const A = [238, 142]; // apex
+const B = [146, 322]; // bottom left
+const C = [330, 322]; // bottom right
+const DEPTH = [40, -24]; // extrusion, up and to the right
+
+const add = (p, q) => [p[0] + q[0], p[1] + q[1]];
+const mix = (p, q, t) => [p[0] + (q[0] - p[0]) * t, p[1] + (q[1] - p[1]) * t];
+
+const A2 = add(A, DEPTH);
+const B2 = add(B, DEPTH);
+const C2 = add(C, DEPTH);
+
+const FRONT = [A, B, C];
+const SIDE = [A, C, C2, A2]; // the only extruded face facing the viewer
+
+// Where the beam enters the left face and leaves the right one. Both sit on an
+// edge rather than near a corner, so the light visibly passes through the body.
+const ENTRY = mix(A, B, 0.55);
+const EXIT = mix(A, C, 0.62);
+const SOURCE = [24, 196];
+
+/**
+ * The spectrum, ordered by how far each colour bends.
+ *
+ * Red deviates least and violet most, which is the whole reason a prism
+ * separates them, so red leaves closest to the original path and violet swings
+ * furthest toward the base. Reversing this is the usual tell that a prism
+ * drawing was copied rather than understood.
+ */
+const SPECTRUM = [
+  { angle: 6, color: [255, 64, 72] },
+  { angle: 11, color: [255, 138, 48] },
+  { angle: 16, color: [255, 214, 66] },
+  { angle: 21, color: [88, 230, 122] },
+  { angle: 26, color: [70, 210, 255] },
+  { angle: 31, color: [96, 132, 255] },
+  { angle: 36, color: [176, 106, 255] },
+];
+
+const FAN_LENGTH = 190;
+const BG = [10, 14, 26];
+
+const rad = (deg) => (deg * Math.PI) / 180;
+
+/** A light band: origin, direction, and how wide it is at each end. */
+function band(origin, angleDeg, length, w0, w1) {
+  const t = rad(angleDeg);
+  return {
+    origin,
+    dir: [Math.cos(t), Math.sin(t)],
+    perp: [-Math.sin(t), Math.cos(t)],
+    length,
+    w0,
+    w1,
+  };
+}
+
+const FAN = SPECTRUM.map((s) => ({
+  ...s,
+  band: band(EXIT, s.angle, FAN_LENGTH, 3, 15),
+}));
+
+const INCOMING = (() => {
+  const d = [ENTRY[0] - SOURCE[0], ENTRY[1] - SOURCE[1]];
+  const len = Math.hypot(d[0], d[1]);
+  return { band: band(SOURCE, (Math.atan2(d[1], d[0]) * 180) / Math.PI, len, 7, 4), color: [255, 255, 255] };
+})();
+
+const INTERNAL = (() => {
+  const d = [EXIT[0] - ENTRY[0], EXIT[1] - ENTRY[1]];
+  const len = Math.hypot(d[0], d[1]);
+  return { band: band(ENTRY, (Math.atan2(d[1], d[0]) * 180) / Math.PI, len, 4, 6), color: [220, 235, 255] };
+})();
+
+/** Corners of a band, for the SVG. */
+function bandPoints(b) {
+  const s = b.origin;
+  const e = [s[0] + b.dir[0] * b.length, s[1] + b.dir[1] * b.length];
+  const off = (p, w, sign) => [p[0] + b.perp[0] * w * sign, p[1] + b.perp[1] * w * sign];
+  return [off(s, b.w0, -1), off(e, b.w1, -1), off(e, b.w1, 1), off(s, b.w0, 1)];
+}
+
+// --- SVG -------------------------------------------------------------------
+
+const n = (v) => Math.round(v * 10) / 10;
+const poly = (pts) => pts.map((p) => `${n(p[0])},${n(p[1])}`).join(" ");
+const rgb = (c) => `rgb(${c[0]},${c[1]},${c[2]})`;
+
+function svg() {
+  const beams = [];
+  for (const [i, f] of FAN.entries()) {
+    const pts = bandPoints(f.band);
+    beams.push(
+      `<linearGradient id="g${i}" gradientUnits="userSpaceOnUse" ` +
+        `x1="${n(EXIT[0])}" y1="${n(EXIT[1])}" ` +
+        `x2="${n(pts[1][0])}" y2="${n(pts[1][1])}">` +
+        `<stop offset="0" stop-color="${rgb(f.color)}" stop-opacity="0.95"/>` +
+        `<stop offset="0.55" stop-color="${rgb(f.color)}" stop-opacity="0.5"/>` +
+        `<stop offset="1" stop-color="${rgb(f.color)}" stop-opacity="0"/>` +
+        `</linearGradient>`,
+    );
+  }
+
+  const fan = FAN.map((f, i) => `<polygon points="${poly(bandPoints(f.band))}" fill="url(#g${i})"/>`).join("\n      ");
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${SIZE} ${SIZE}" width="${SIZE}" height="${SIZE}" role="img" aria-label="A prism splitting a beam of white light into a spectrum">
+  <title>rbx-studio-mcp</title>
+  <defs>
+    ${beams.join("\n    ")}
+    <linearGradient id="face" gradientUnits="userSpaceOnUse" x1="${n(A[0])}" y1="${n(A[1])}" x2="${n(C[0])}" y2="${n(C[1])}">
+      <stop offset="0" stop-color="#AFC0E8" stop-opacity="0.30"/>
+      <stop offset="1" stop-color="#5C6E9E" stop-opacity="0.16"/>
+    </linearGradient>
+    <linearGradient id="side" gradientUnits="userSpaceOnUse" x1="${n(A[0])}" y1="${n(A[1])}" x2="${n(C2[0])}" y2="${n(C2[1])}">
+      <stop offset="0" stop-color="#8FA2D0" stop-opacity="0.26"/>
+      <stop offset="1" stop-color="#39456A" stop-opacity="0.34"/>
+    </linearGradient>
+    <radialGradient id="flare">
+      <stop offset="0" stop-color="#FFFFFF" stop-opacity="0.85"/>
+      <stop offset="1" stop-color="#FFFFFF" stop-opacity="0"/>
+    </radialGradient>
+    <filter id="soft" x="-40%" y="-40%" width="180%" height="180%">
+      <feGaussianBlur stdDeviation="5"/>
+    </filter>
+  </defs>
+
+  <rect width="${SIZE}" height="${SIZE}" fill="#0A0E1A"/>
+
+  <g filter="url(#soft)" opacity="0.85">
+      ${fan}
+  </g>
+  <g>
+      ${fan}
+  </g>
+
+  <polygon points="${poly(bandPoints(INCOMING.band))}" fill="#FFFFFF" opacity="0.85" filter="url(#soft)"/>
+  <polygon points="${poly(bandPoints(INCOMING.band))}" fill="#FFFFFF" opacity="0.9"/>
+
+  <polygon points="${poly(SIDE)}" fill="url(#side)"/>
+  <polygon points="${poly(FRONT)}" fill="url(#face)"/>
+
+  <polygon points="${poly(bandPoints(INTERNAL.band))}" fill="#DCEBFF" opacity="0.55"/>
+
+  <polygon points="${poly(FRONT)}" fill="none" stroke="#DCE6FF" stroke-opacity="0.85" stroke-width="2.5" stroke-linejoin="round"/>
+  <polygon points="${poly(SIDE)}" fill="none" stroke="#AEC0EA" stroke-opacity="0.5" stroke-width="2" stroke-linejoin="round"/>
+
+  <circle cx="${n(ENTRY[0])}" cy="${n(ENTRY[1])}" r="16" fill="url(#flare)"/>
+  <circle cx="${n(EXIT[0])}" cy="${n(EXIT[1])}" r="20" fill="url(#flare)"/>
+</svg>
+`;
+}
+
+// --- PNG -------------------------------------------------------------------
+
+function insidePoly(pts, x, y) {
+  let hit = false;
+  for (let i = 0, j = pts.length - 1; i < pts.length; j = i, i += 1) {
+    const [xi, yi] = pts[i];
+    const [xj, yj] = pts[j];
+    if (yi > y !== yj > y && x < ((xj - xi) * (y - yi)) / (yj - yi) + xi) hit = !hit;
+  }
+  return hit;
+}
+
+/**
+ * How brightly a band lights the point, 0..1.
+ *
+ * Gaussian across the width and falling off along the length, which is what
+ * makes a beam look like light rather than a painted stripe.
+ */
+function bandLight(b, x, y) {
+  const dx = x - b.origin[0];
+  const dy = y - b.origin[1];
+  const along = dx * b.dir[0] + dy * b.dir[1];
+  if (along < 0 || along > b.length) return 0;
+  const t = along / b.length;
+  const across = Math.abs(dx * b.perp[0] + dy * b.perp[1]);
+  const width = b.w0 + (b.w1 - b.w0) * t;
+  const profile = Math.exp(-((across / width) ** 2) * 2.2);
+  const fade = (1 - t) ** 0.7;
+  const ramp = Math.min(1, t / 0.04);
+  return profile * fade * ramp;
+}
+
+function flare(p, x, y, radius) {
+  const d = Math.hypot(x - p[0], y - p[1]) / radius;
+  return Math.exp(-d * d * 2.4);
+}
+
+function png() {
+  const out = Buffer.alloc(SIZE * SIZE * 3);
+
+  for (let py = 0; py < SIZE; py += 1) {
+    for (let px = 0; px < SIZE; px += 1) {
+      let r = 0;
+      let g = 0;
+      let b = 0;
+
+      for (let sy = 0; sy < SS; sy += 1) {
+        for (let sx = 0; sx < SS; sx += 1) {
+          const x = px + (sx + 0.5) / SS;
+          const y = py + (sy + 0.5) / SS;
+
+          let c = [...BG];
+
+          // Glass first: a faint body that the light is then added over, so the
+          // beams read as passing through rather than being drawn on.
+          if (insidePoly(SIDE, x, y)) {
+            const t = (x - A[0]) / (C2[0] - A[0]);
+            c = [c[0] + 44 * (1 - t * 0.5), c[1] + 54 * (1 - t * 0.5), c[2] + 84 * (1 - t * 0.4)];
+          }
+          if (insidePoly(FRONT, x, y)) {
+            const t = (y - A[1]) / (C[1] - A[1]);
+            c = [c[0] + 62 - 22 * t, c[1] + 74 - 24 * t, c[2] + 108 - 28 * t];
+          }
+
+          // Light is added, never blended: two beams crossing should be
+          // brighter, which is the one thing alpha compositing gets wrong.
+          const lights = [INCOMING, ...FAN];
+          for (const l of lights) {
+            const v = bandLight(l.band, x, y);
+            if (v > 0) {
+              c[0] += l.color[0] * v;
+              c[1] += l.color[1] * v;
+              c[2] += l.color[2] * v;
+            }
+          }
+          if (insidePoly(FRONT, x, y)) {
+            const v = bandLight(INTERNAL.band, x, y) * 0.85;
+            c[0] += 220 * v;
+            c[1] += 235 * v;
+            c[2] += 255 * v;
+          }
+
+          for (const [p, radius, strength] of [
+            [ENTRY, 20, 0.55],
+            [EXIT, 26, 0.75],
+          ]) {
+            const v = flare(p, x, y, radius) * strength;
+            c[0] += 255 * v;
+            c[1] += 255 * v;
+            c[2] += 255 * v;
+          }
+
+          // Edges, drawn as distance to each segment so they stay crisp.
+          const edges = [
+            [FRONT, 1.6, 210, 226, 255],
+            [SIDE, 1.2, 150, 170, 220],
+          ];
+          for (const [shape, halfWidth, er, eg, eb] of edges) {
+            for (let i = 0; i < shape.length; i += 1) {
+              const p0 = shape[i];
+              const p1 = shape[(i + 1) % shape.length];
+              const vx = p1[0] - p0[0];
+              const vy = p1[1] - p0[1];
+              const len2 = vx * vx + vy * vy;
+              let t = ((x - p0[0]) * vx + (y - p0[1]) * vy) / len2;
+              t = Math.max(0, Math.min(1, t));
+              const d = Math.hypot(x - (p0[0] + vx * t), y - (p0[1] + vy * t));
+              if (d < halfWidth + 1) {
+                const a = Math.max(0, Math.min(1, halfWidth + 1 - d));
+                c[0] += (er - c[0]) * a * 0.9;
+                c[1] += (eg - c[1]) * a * 0.9;
+                c[2] += (eb - c[2]) * a * 0.9;
+              }
+            }
+          }
+
+          r += Math.min(255, c[0]);
+          g += Math.min(255, c[1]);
+          b += Math.min(255, c[2]);
+        }
+      }
+
+      const n2 = SS * SS;
+      const at = (py * SIZE + px) * 3;
+      out[at] = Math.round(r / n2);
+      out[at + 1] = Math.round(g / n2);
+      out[at + 2] = Math.round(b / n2);
+    }
+  }
+
+  return encodePng(out, SIZE, SIZE);
+}
+
+writeFileSync(process.argv[2], svg());
+writeFileSync(process.argv[3], png());