@el4cteo/rbx-studio-mcp 0.3.1 → 0.3.6

package/plugin/src/Themes/Orbit.luau

@@ -0,0 +1,268 @@
+--!strict
+--[[
+	Orbit -- the only preset that reports something the others cannot.
+
+	A body at the centre with satellites running elliptical paths around it. The
+	number of satellites is the session's activity, so where Lattice climbs a
+	ladder of shapes to say "busy", this says it in a way you can count: one
+	moon is a quiet session, five is a burst.
+
+	The ellipses are a projected circle rather than a drawn oval, so the whole
+	system tilts as the angle turns and a satellite genuinely passes behind the
+	body -- it dims and shrinks on the far side because it is further away. That
+	is what stops it reading as a loading spinner with extra dots.
+
+	Colour is warm here on purpose. Every other dark preset in the set leans
+	blue or violet; a gold system against navy is the one that looks like an
+	instrument rather than a screensaver.
+]]
+
+local Draw = require(script.Parent.Draw)
+local Theme = require(script.Parent.Theme)
+
+-- Satellites are pooled at the maximum and hidden when the session is calm, so
+-- activity changes what is visible rather than what exists.
+local MOONS = 6
+local PATH_DOTS = 28
+local FOCAL = 3.2
+
+--[[
+	How far the orbits reach, as a multiple of the body's radius.
+
+	Chosen so the outermost satellite sits about 18px from a centre with 20px of
+	room: filling the cell, with just enough margin that it never touches the
+	clip. Two earlier values were both wrong for the same underlying reason --
+	2.4 threw the sixth moon 26px out when busy, and 1.5 fixed the clipping by
+	making the whole system too small to read.
+]]
+local ORBIT_SCALE = 1.95
+
+--[[
+	How much of the scale spring the ORBITS take. Almost none.
+
+	The spring swings 0.82 to 1.20, and letting the satellites carry that meant
+	the system had to rest small enough that its overshoot still fit -- so it
+	was sized by its worst moment rather than by the one you spend all your time
+	looking at. The body and the halo carry the spring instead: they sit at the
+	centre with room to grow, and a struck object whose middle flexes reads the
+	same as one that flexes all over.
+]]
+local ORBIT_BREATH = 0.08
+
+local Orbit = {}
+
+Orbit.id = "orbit"
+Orbit.label = "Orbit"
+Orbit.blurb = "Body and satellites"
+
+Orbit.palette = {
+	background = Color3.fromRGB(10, 13, 22),
+	surface = Color3.fromRGB(17, 22, 36),
+	rule = Color3.fromRGB(240, 186, 108),
+	text = Color3.fromRGB(226, 222, 210),
+	dim = Color3.fromRGB(96, 100, 116),
+	green = Color3.fromRGB(134, 214, 158),
+	red = Color3.fromRGB(240, 130, 116),
+	amber = Color3.fromRGB(246, 190, 106),
+	cyan = Color3.fromRGB(132, 196, 226),
+	violet = Color3.fromRGB(196, 164, 226),
+}
+
+local body: Frame? = nil
+local halo: Frame? = nil
+local moons: { Frame } = {}
+local path: { Frame } = {}
+
+--[[
+	Orbital parameters for satellite `index`.
+
+	Fixed per index so a moon keeps its own path for the life of the session --
+	re-rolling them would make the system reshuffle every frame. Radius rises
+	with the index so the moons never share an orbit, and the inclination is
+	what makes the paths cross rather than sit in one flat ring.
+]]
+local function orbitOf(index: number): (number, number, number)
+	-- Tightened from `0.42 + index * 0.1`, which put the sixth moon at 1.02 and
+	-- 26px from a centre with 20px of room -- so the satellite that only appears
+	-- when the session is busiest was the one that flew off the edge.
+	local radius = 0.34 + index * 0.055
+	local speed = 1.5 / (radius * 2.4)
+	local inclination = (Draw.hash(index, 5) - 0.5) * 1.6
+	return radius, speed, inclination
+end
+
+function Orbit.mount(cell: Frame)
+	path = Draw.pool(cell, PATH_DOTS, "Path", true)
+
+	local disc = Instance.new("Frame")
+	disc.Name = "Halo"
+	disc.AnchorPoint = Vector2.new(0.5, 0.5)
+	disc.BorderSizePixel = 0
+	disc.Parent = cell
+	local haloCorner = Instance.new("UICorner")
+	haloCorner.CornerRadius = UDim.new(1, 0)
+	haloCorner.Parent = disc
+	halo = disc
+
+	local core = Instance.new("Frame")
+	core.Name = "Body"
+	core.AnchorPoint = Vector2.new(0.5, 0.5)
+	core.BorderSizePixel = 0
+	core.Parent = cell
+	local coreCorner = Instance.new("UICorner")
+	coreCorner.CornerRadius = UDim.new(1, 0)
+	coreCorner.Parent = core
+	body = core
+
+	-- Last, so a near satellite passes in front of the body it orbits.
+	moons = Draw.pool(cell, MOONS, "Moon", true)
+end
+
+function Orbit.unmount()
+	body = nil
+	halo = nil
+	moons = {}
+	path = {}
+end
+
+function Orbit.paint(ctx: Theme.Context, _delta: number)
+	local breath = (1 - ORBIT_BREATH) + ctx.scale * ORBIT_BREATH
+	local radius = ctx.size * 0.34 * breath
+	local core = body
+	local glow = halo
+
+	if core ~= nil then
+		--[[
+			Amber, not the status tint.
+
+			Every other preset paints its cell in `ctx.tint` so the panel reads as
+			disconnected at a glance. Orbit cannot: the tint is green while
+			connected, so the body came out green while the drawer previewed it in
+			gold, and the preview is a promise. The HALO carries the status colour
+			instead -- same information, on the part of the scene that is supposed
+			to change.
+		]]
+		local size = math.max(5, math.floor(7.5 * ctx.scale + ctx.flare * 3))
+		Draw.dot(
+			core,
+			ctx.centre,
+			size,
+			ctx.palette.amber:Lerp(Color3.new(1, 1, 1), 0.3 + ctx.flare * 0.5),
+			0
+		)
+	end
+	if glow ~= nil then
+		-- A halo that grows with energy rather than a body that does: the body
+		-- staying put is what gives the satellites something fixed to orbit.
+		local size = math.max(10, math.floor(13 * ctx.scale + ctx.energy * 8 + ctx.flare * 6))
+		Draw.dot(glow, ctx.centre, size, ctx.tint, math.clamp(0.9 - ctx.flare * 0.35, 0, 1))
+	end
+
+	--[[
+		The innermost path, drawn as points so it fades with depth.
+
+		Only one path is drawn even though there are six orbits. Six rings turns
+		the cell into a scribble at forty pixels across; one ring establishes
+		that these things are orbiting and the rest is left to the motion.
+	]]
+	local pathRadius, _, pathTilt = orbitOf(1)
+	for index = 1, PATH_DOTS do
+		local frame = path[index]
+		local turn = (index / PATH_DOTS) * math.pi * 2
+		local local3 = Vector3.new(
+			math.cos(turn) * pathRadius,
+			math.sin(turn) * pathRadius * math.sin(pathTilt),
+			math.sin(turn) * pathRadius * math.cos(pathTilt)
+		)
+		local point, depth = Draw.project(
+			Draw.rotate(local3, ctx.angle * 0.5),
+			FOCAL,
+			radius * ORBIT_SCALE,
+			ctx.centre
+		)
+		local near = math.clamp((depth + 1) / 2, 0, 1)
+		Draw.dot(frame, point, 1, ctx.palette.dim, math.clamp(0.78 - near * 0.3, 0, 1))
+	end
+
+	--[[
+		How many satellites are up. Activity runs 0..1 over about ten seconds,
+		so this climbs through the pool as a burst lands and drops back as it
+		unwinds -- which is the readout the theme exists for.
+	]]
+	local visible = 1 + math.floor(math.clamp(ctx.activity, 0, 1) * (MOONS - 1) + 0.5)
+
+	for index = 1, MOONS do
+		local frame = moons[index]
+		if frame == nil then
+			continue
+		end
+		if index > visible then
+			frame.Visible = false
+			continue
+		end
+
+		local orbitRadius, speed, tilt = orbitOf(index)
+		-- Phase offset per moon so they do not launch from the same point and
+		-- travel as a clump.
+		local turn = ctx.clock * speed + Draw.hash(index, 6) * math.pi * 2
+		local local3 = Vector3.new(
+			math.cos(turn) * orbitRadius,
+			math.sin(turn) * orbitRadius * math.sin(tilt),
+			math.sin(turn) * orbitRadius * math.cos(tilt)
+		)
+		local point, depth = Draw.project(
+			Draw.rotate(local3, ctx.angle * 0.5),
+			FOCAL,
+			radius * ORBIT_SCALE,
+			ctx.centre
+		)
+		local near = math.clamp((depth + 1) / 2, 0, 1)
+		Draw.dot(
+			frame,
+			point,
+			math.max(2, math.floor(2.5 + near * 2.5 + ctx.flare * 1.5)),
+			ctx.palette.amber:Lerp(Color3.new(1, 1, 1), near * 0.4 + ctx.flare * 0.3),
+			math.clamp(0.35 - near * 0.32 - ctx.flare * 0.3, 0, 1)
+		)
+	end
+end
+
+--[[
+	History as a run of moons at their apoapsis: a dot per call, high when slow.
+
+	Bars would be the obvious choice and are wrong here -- a rectangle sitting
+	on a baseline has nothing to do with the rest of the scene, and the trace
+	and the cell would read as two unrelated instruments sharing a strip.
+]]
+function Orbit.paintSlot(slot: Theme.Slot, ctx: Theme.Context)
+	local frame = slot.frame
+	local recency = 1 - slot.age
+
+	frame.AnchorPoint = Vector2.new(0.5, 0.5)
+	local size = math.max(2, math.floor(2 + slot.weight * 3 + recency))
+	frame.Size = UDim2.fromOffset(size, size)
+	frame.Position = UDim2.new(frame.Position.X.Scale, frame.Position.X.Offset, 0.88 - slot.weight * 0.74, 0)
+	frame.BackgroundColor3 = if slot.ok then ctx.palette.amber else ctx.palette.red
+	frame.BackgroundTransparency = math.clamp((if slot.ok then 0.7 else 0.35) - recency * 0.55, 0, 1)
+	frame.Rotation = 0
+end
+
+function Orbit.swatch(frame: Frame, palette: Theme.Palette)
+	local centre = Vector2.new(20, 12)
+	local ring = Draw.pool(frame, 20, "Path", true)
+	for index = 1, 20 do
+		local turn = (index / 20) * math.pi * 2
+		Draw.dot(
+			ring[index],
+			centre + Vector2.new(math.cos(turn) * 13, math.sin(turn) * 5.5),
+			1,
+			palette.dim,
+			0.6
+		)
+	end
+	local pool = Draw.pool(frame, 2, "Body", true)
+	Draw.dot(pool[1], centre, 7, palette.amber:Lerp(Color3.new(1, 1, 1), 0.3), 0)
+	Draw.dot(pool[2], centre + Vector2.new(13, -1), 3, palette.amber, 0.1)
+end
+
+return Orbit

package/plugin/src/Themes/Phosphor.luau

@@ -0,0 +1,200 @@
+--!strict
+--[[
+	Phosphor -- a CRT oscilloscope.
+
+	A Lissajous figure traced by a moving beam, with the phosphor decaying
+	behind it. The head is white-hot, the tail fades to green over about forty
+	samples, and the whole cell sits under scanlines.
+
+	It deliberately does NOT reuse the wireframe. Drawing Lattice's solid in
+	green with a trail would be the obvious CRT gag and would leave two of the
+	eight presets doing the same thing in different colours. A beam tracing a
+	curve is what a scope actually does, and it gives the theme its own answer
+	to "is this alive": the figure's shape changes with the session, because the
+	frequency ratio is driven by activity. Idle it draws a lazy ellipse; busy it
+	knots into a rose.
+
+	The sample buffer is a ring rather than a growing list. The head advances,
+	the sample under it is overwritten, and age is computed from the distance
+	back to the head -- so nothing is allocated or shifted per frame.
+]]
+
+local Draw = require(script.Parent.Draw)
+local Theme = require(script.Parent.Theme)
+
+local SAMPLES = 46
+-- Samples per second the beam advances. Fast enough that the figure is a curve
+-- rather than a dotted line, slow enough that the decay is visible.
+local RATE = 60
+
+local Phosphor = {}
+
+Phosphor.id = "phosphor"
+Phosphor.label = "Phosphor"
+Phosphor.blurb = "CRT scope beam"
+
+Phosphor.palette = {
+	background = Color3.fromRGB(4, 8, 5),
+	surface = Color3.fromRGB(9, 16, 11),
+	rule = Color3.fromRGB(86, 232, 122),
+	text = Color3.fromRGB(178, 236, 190),
+	dim = Color3.fromRGB(70, 112, 82),
+	green = Color3.fromRGB(86, 240, 128),
+	red = Color3.fromRGB(248, 118, 96),
+	amber = Color3.fromRGB(240, 208, 106),
+	cyan = Color3.fromRGB(122, 234, 208),
+	violet = Color3.fromRGB(150, 226, 150),
+}
+
+local dots: { Frame } = {}
+local scanlines: { Frame } = {}
+local samples: { Vector2 } = {}
+local head = 0
+local accumulator = 0
+
+function Phosphor.mount(cell: Frame)
+	dots = Draw.pool(cell, SAMPLES, "Sample", true)
+
+	scanlines = {}
+	samples = {}
+	head = 0
+	accumulator = 0
+
+	--[[
+		Scanlines last, so they lie OVER the beam.
+
+		Underneath they were invisible -- the beam is the brightest thing in the
+		cell and simply covered them. A CRT's lines cross what it is drawing;
+		that is what makes it read as a screen rather than as a dark background
+		with stripes on it.
+	]]
+	for index = 1, 10 do
+		local line = Instance.new("Frame")
+		line.Name = string.format("Scan%02d", index)
+		line.BorderSizePixel = 0
+		line.BackgroundColor3 = Color3.new(0, 0, 0)
+		line.BackgroundTransparency = 0.78
+		line.Size = UDim2.new(1, 0, 0, 1)
+		line.Position = UDim2.fromOffset(0, index * 4)
+		line.ZIndex = 4
+		line.Parent = cell
+		scanlines[index] = line
+	end
+end
+
+function Phosphor.unmount()
+	dots = {}
+	scanlines = {}
+	samples = {}
+end
+
+function Phosphor.paint(ctx: Theme.Context, delta: number)
+	local radius = ctx.size * 0.33 * ctx.scale
+
+	--[[
+		The figure's ratio, from activity.
+
+		A Lissajous curve closes when its two frequencies are a simple ratio, so
+		holding X at 2 and sliding Y between 3 and roughly 5 walks it from an
+		open ellipse through a figure-eight into a knot. The session's load
+		therefore changes the SHAPE, not just the speed -- which is the same
+		trick Lattice plays with its solids, done continuously.
+	]]
+	local ratio = 3 + math.clamp(ctx.activity, 0, 1) * 2.1
+
+	-- Fixed-step sampling. Advancing one sample per frame would make the trail's
+	-- length depend on Studio's frame rate, so the beam would visibly speed up
+	-- whenever the editor was idle.
+	accumulator += math.min(delta, 1 / 15)
+	local advance = math.floor(accumulator * RATE)
+	if advance > 0 then
+		accumulator -= advance / RATE
+		for _ = 1, math.min(advance, SAMPLES) do
+			head += 1
+			local t = head / RATE
+			samples[(head % SAMPLES) + 1] = Vector2.new(
+				math.sin(t * 2) * radius,
+				math.sin(t * ratio + ctx.clock * 0.15) * radius
+			)
+		end
+	end
+
+	for index = 1, SAMPLES do
+		local frame = dots[index]
+		local point = samples[index]
+		if frame == nil then
+			continue
+		end
+		if point == nil then
+			frame.Visible = false
+			continue
+		end
+
+		--[[
+			How far back from the head this sample is, 0 (newest) to 1 (about to
+			be overwritten). The modulo is what lets the ring buffer stand in for
+			an ordered trail without moving anything.
+		]]
+		local back = (head - (index - 1)) % SAMPLES
+		local age = back / SAMPLES
+
+		-- Squared, so the head is a bright point with a long dim tail rather
+		-- than an evenly grey worm. Phosphor decays fast at first.
+		local glow = (1 - age) * (1 - age)
+
+		Draw.dot(
+			frame,
+			ctx.centre + point,
+			math.max(1, math.floor(1 + glow * 2 + ctx.flare * 1.5)),
+			ctx.palette.green:Lerp(Color3.new(1, 1, 1), glow * 0.85),
+			math.clamp(0.94 - glow * 0.9 - ctx.flare * 0.2, 0, 1)
+		)
+	end
+end
+
+--[[
+	History as scope columns: hard-edged, one pixel wide, no rounding. The trace
+	is the one part of a scope's screen that is supposed to look like a chart.
+]]
+function Phosphor.paintSlot(slot: Theme.Slot, ctx: Theme.Context)
+	local frame = slot.frame
+	local recency = 1 - slot.age
+	local height = math.max(1, math.floor(1 + slot.weight * 22))
+
+	frame.AnchorPoint = Vector2.new(0.5, 1)
+	frame.Size = UDim2.fromOffset(2, height)
+	frame.Position = UDim2.new(frame.Position.X.Scale, frame.Position.X.Offset, 1, 0)
+	frame.BackgroundColor3 = if slot.ok
+		then ctx.palette.green:Lerp(Color3.new(1, 1, 1), recency * 0.4)
+		else ctx.palette.red
+	frame.BackgroundTransparency = math.clamp(0.7 - recency * 0.65, 0, 1)
+	frame.Rotation = 0
+end
+
+function Phosphor.swatch(frame: Frame, palette: Theme.Palette)
+	local centre = Vector2.new(20, 12)
+	local pool = Draw.pool(frame, 30, "Sample", true)
+	for index = 1, 30 do
+		local t = index / 6
+		local glow = index / 30
+		Draw.dot(
+			pool[index],
+			centre + Vector2.new(math.sin(t * 2) * 15, math.sin(t * 3) * 9),
+			1 + math.floor(glow * 2),
+			palette.green:Lerp(Color3.new(1, 1, 1), glow * 0.8),
+			0.85 - glow * 0.8
+		)
+	end
+	for index = 1, 6 do
+		local line = Instance.new("Frame")
+		line.BorderSizePixel = 0
+		line.BackgroundColor3 = Color3.new(0, 0, 0)
+		line.BackgroundTransparency = 0.75
+		line.Size = UDim2.new(1, 0, 0, 1)
+		line.Position = UDim2.fromOffset(0, index * 4)
+		line.ZIndex = 4
+		line.Parent = frame
+	end
+end
+
+return Phosphor

package/plugin/src/Themes/Theme.luau

@@ -0,0 +1,121 @@
+--!strict
+--[[
+	The contract every preset satisfies.
+
+	A theme owns two surfaces and nothing else. `cell` is the square at the left
+	of the activity band -- the slot the wireframe prism occupies under the
+	default theme, and which any other theme is free to fill with something that
+	is not a prism at all. `slots` are the forty most recent calls, drawn as bars
+	under the default theme and as anything else under the rest.
+
+	What a theme deliberately does NOT own is the simulation. Energy, activity,
+	flare, shake, the scale spring and the quiet timer are computed once in
+	Visuals and handed to whichever preset is active. That is the whole reason
+	eight presets do not mean eight animation systems: they are eight painters
+	over one set of physics, so a preset is a few hundred lines of drawing and
+	holds no state that could drift out of step with the session.
+]]
+
+export type Palette = {
+	background: Color3,
+	surface: Color3,
+	rule: Color3,
+	text: Color3,
+	dim: Color3,
+	green: Color3,
+	red: Color3,
+	amber: Color3,
+	cyan: Color3,
+	violet: Color3,
+}
+
+--[[
+	The session, as numbers a painter can use.
+
+	Everything here decays on its own, so a painter never has to schedule
+	anything: read the value, draw that frame, and the motion follows.
+
+	`energy` rises with each command and falls over about a second -- use it for
+	anything that should react. `activity` is the slower average, over roughly
+	ten seconds, and is what should drive how BUSY a scene looks rather than how
+	startled. `flare` spikes to 1 the instant a reply lands and is gone in a
+	third of a second, which is what makes a completed call read as an event.
+	`shake` is the same but only for failures. `quiet` is seconds since anything
+	ran; past `QUIET_AFTER` the session has stopped rather than paused, and a
+	scene that keeps working at full pace after that is claiming an activity
+	which is not happening.
+]]
+export type Context = {
+	palette: Palette,
+	-- Connection state blended toward the kind of work last done.
+	tint: Color3,
+	energy: number,
+	activity: number,
+	flare: number,
+	shake: number,
+	-- The scale spring: 1 at rest, overshoots past 1 on a reply, 0.82 when idle.
+	scale: number,
+	quiet: number,
+	-- Accumulated rotation on three axes. Meaningful to anything that turns;
+	-- ignorable by anything that does not.
+	angle: Vector3,
+	-- `os.clock()`, sampled once per frame so every painter agrees on the time.
+	clock: number,
+	-- The cell is square; this is its side in pixels.
+	size: number,
+	centre: Vector2,
+}
+
+--[[
+	One finished call, as history rather than as an event.
+
+	`age` is 0 for the newest and rises toward 1 for the oldest still on screen,
+	which is what lets a preset fade its history out without tracking when
+	anything happened. `frame` is pooled and reused as bars shift left, so a
+	painter must set every property it cares about rather than assuming the
+	frame arrives clean.
+]]
+export type Slot = {
+	frame: Frame,
+	milliseconds: number,
+	ok: boolean,
+	title: string,
+	age: number,
+	-- Duration against the "slow" reference, clamped to 1. Height, for a bar.
+	weight: number,
+}
+
+export type Theme = {
+	id: string,
+	label: string,
+	-- One line, shown under the label in the picker.
+	blurb: string,
+	palette: Palette,
+	--[[
+		Builds whatever the cell needs, once. Pooled Instances belong here:
+		allocating inside `paint` is how a decorative strip becomes a performance
+		complaint.
+	]]
+	mount: (cell: Frame) -> (),
+	paint: (ctx: Context, delta: number) -> (),
+	--[[
+		Destroys what `mount` built. Called on every theme switch, so it must
+		leave the cell empty enough for the next preset to start clean.
+	]]
+	unmount: () -> (),
+	--[[
+		Draws one call of history. Optional: a preset that wants ordinary bars
+		omits it and Visuals draws them.
+	]]
+	paintSlot: ((slot: Slot, ctx: Context) -> ())?,
+	--[[
+		A still miniature for the picker, drawn into a 40x24 frame.
+
+		Static on purpose. Eight live renderers running behind a hover menu is
+		the one place the "only one preset runs at a time" argument breaks, and
+		it breaks in a drawer the user looks at for two seconds.
+	]]
+	swatch: (frame: Frame, palette: Palette) -> (),
+}
+
+return {}