@el4cteo/rbx-studio-mcp 0.3.1 → 0.3.5

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 {}

package/plugin/src/Themes/Void.luau

@@ -0,0 +1,230 @@
+--!strict
+--[[
+	Void -- an accretion disc, and the most literal of the eight.
+
+	A dark core with matter spiralling into it. Orbital speed rises as radius
+	falls, the way it actually does, so the inner ring visibly outruns the outer
+	one and the disc shears instead of turning as a plate. That single detail is
+	what separates it from a spinning ring of dots.
+
+	The trace is where the metaphor pays for itself. A slow call is drawn
+	stretched and shifted red, so latency is not a height you have to compare
+	against its neighbours -- it is a thing visibly being pulled apart. A
+	forty-bar chart makes you measure; this makes you look.
+
+	It is also the least legible preset in the set, and that is a real trade
+	rather than an oversight: the disc is dark, the motion is continuous, and
+	there is no baseline to read heights against. It is here because someone
+	will want it, not because it is the best instrument.
+]]
+
+local Draw = require(script.Parent.Draw)
+local Theme = require(script.Parent.Theme)
+
+local MOTES = 34
+local RINGS = 4
+
+--[[
+	How far the disc reaches, and how flat it is seen.
+
+	The reach was already near the cell's limit; the disc read as small because
+	it was a HAIRLINE -- flattened to 0.3, four rings of it occupied about 10px
+	of vertical space in a 40px cell, so a wide thin smear was doing the work of
+	a picture. Opening the viewing angle to 0.48 nearly doubles the height for
+	no extra width, which is the axis that actually had room spare.
+]]
+local DISC_SPREAD = 0.54
+local FLATTEN = 0.48
+
+-- The disc barely breathes: same reasoning as Orbit. A ring sized to fill the
+-- cell at rest would be cut off by the clip at every overshoot, so the CORE
+-- carries the spring and the matter around it holds its radius.
+local DISC_BREATH = 0.1
+
+local Void = {}
+
+Void.id = "void"
+Void.label = "Void"
+Void.blurb = "Accretion disc"
+
+Void.palette = {
+	background = Color3.fromRGB(6, 5, 10),
+	surface = Color3.fromRGB(13, 11, 20),
+	rule = Color3.fromRGB(168, 108, 236),
+	text = Color3.fromRGB(206, 200, 222),
+	dim = Color3.fromRGB(84, 78, 102),
+	green = Color3.fromRGB(120, 220, 176),
+	red = Color3.fromRGB(252, 96, 118),
+	amber = Color3.fromRGB(250, 174, 108),
+	cyan = Color3.fromRGB(126, 202, 244),
+	violet = Color3.fromRGB(178, 122, 246),
+}
+
+local motes: { Frame } = {}
+local core: Frame? = nil
+local shadow: Frame? = nil
+
+--[[
+	Which ring a mote belongs to, and where it sits on that ring.
+
+	Distributed by index rather than randomly so every ring gets a similar share
+	-- a random assignment leaves visible gaps at forty motes, and a gap in a
+	disc reads as a rendering fault rather than as structure.
+]]
+local function ringOf(index: number): (number, number)
+	local ring = 1 + (index - 1) % RINGS
+	local along = Draw.hash(index, 41)
+	return ring, along
+end
+
+function Void.mount(cell: Frame)
+	local dark = Instance.new("Frame")
+	dark.Name = "Shadow"
+	dark.AnchorPoint = Vector2.new(0.5, 0.5)
+	dark.BorderSizePixel = 0
+	dark.Parent = cell
+	local darkCorner = Instance.new("UICorner")
+	darkCorner.CornerRadius = UDim.new(1, 0)
+	darkCorner.Parent = dark
+	shadow = dark
+
+	motes = Draw.pool(cell, MOTES, "Mote", true)
+
+	--[[
+		The core is built LAST so it draws over the motes.
+
+		That is the entire illusion: matter passing behind the core has to
+		disappear behind something, and with the core underneath, motes crossed
+		it and the disc read as a flat ring with a dot in the middle.
+	]]
+	local sphere = Instance.new("Frame")
+	sphere.Name = "Core"
+	sphere.AnchorPoint = Vector2.new(0.5, 0.5)
+	sphere.BorderSizePixel = 0
+	sphere.Parent = cell
+	local corner = Instance.new("UICorner")
+	corner.CornerRadius = UDim.new(1, 0)
+	corner.Parent = sphere
+	core = sphere
+end
+
+function Void.unmount()
+	motes = {}
+	core = nil
+	shadow = nil
+end
+
+function Void.paint(ctx: Theme.Context, _delta: number)
+	local breath = (1 - DISC_BREATH) + ctx.scale * DISC_BREATH
+	local scale = ctx.size * DISC_SPREAD * breath
+	-- Lensing: a failure warps the disc rather than shaking the panel, which on
+	-- a strip this small would read as a glitch.
+	local warp = 1 + ctx.shake * 0.28
+
+	for index = 1, MOTES do
+		local frame = motes[index]
+		if frame == nil then
+			continue
+		end
+		local ring, along = ringOf(index)
+		local radius = (0.3 + ring * 0.14) * scale * warp
+
+		--[[
+			Keplerian, near enough: inner orbits are faster. Anything uniform
+			turns the disc as a rigid plate, and the shear is what says the
+			thing at the centre is pulling rather than spinning.
+		]]
+		local speed = 2.4 / (0.3 + ring * 0.14)
+		local turn = along * math.pi * 2 + ctx.clock * speed * 0.1 * (1 + ctx.energy)
+
+		-- Flattened on Y: a disc seen nearly edge-on, not a set of circles.
+		local x = math.cos(turn) * radius
+		local y = math.sin(turn) * radius * FLATTEN
+		-- Depth from the same angle, so a mote on the far side dims.
+		local near = (math.sin(turn) + 1) / 2
+
+		local heat = 1 - ring / RINGS
+		Draw.dot(
+			frame,
+			ctx.centre + Vector2.new(x, y),
+			math.max(2, math.floor(1.5 + heat * 2.5 + ctx.flare * 1.5)),
+			ctx.palette.violet
+				:Lerp(ctx.palette.amber, heat)
+				:Lerp(Color3.new(1, 1, 1), ctx.flare * 0.4),
+			math.clamp(0.82 - near * 0.45 - heat * 0.2 - ctx.flare * 0.25, 0, 1)
+		)
+	end
+
+	local halo = shadow
+	if halo ~= nil then
+		Draw.dot(
+			halo,
+			ctx.centre,
+			math.max(12, math.floor(16 * ctx.scale + ctx.energy * 5)),
+			ctx.palette.violet,
+			0.88
+		)
+	end
+
+	local sphere = core
+	if sphere ~= nil then
+		-- The core does not brighten on a reply. Everything around it does, and
+		-- the hole staying black through a flare is what sells it as a hole.
+		Draw.dot(
+			sphere,
+			ctx.centre,
+			math.max(6, math.floor(9 * ctx.scale)),
+			ctx.palette.background,
+			0
+		)
+	end
+end
+
+--[[
+	History falling inward.
+
+	A slow call is drawn taller AND redder AND further from the baseline, so
+	three channels carry the same fact. That is redundant on purpose: the disc
+	behind it is busy, and one channel would be lost in it.
+]]
+function Void.paintSlot(slot: Theme.Slot, ctx: Theme.Context)
+	local frame = slot.frame
+	local recency = 1 - slot.age
+	local height = math.max(2, math.floor(2 + slot.weight * 18))
+
+	frame.AnchorPoint = Vector2.new(0.5, 1)
+	frame.Size = UDim2.fromOffset(2, height)
+	-- Lifted off the baseline in proportion to how slow it was: the bar has
+	-- started to fall in.
+	frame.Position = UDim2.new(
+		frame.Position.X.Scale,
+		frame.Position.X.Offset,
+		1,
+		-math.floor(slot.weight * 4)
+	)
+	frame.BackgroundColor3 = if slot.ok
+		then ctx.palette.amber:Lerp(ctx.palette.red, slot.weight)
+		else ctx.palette.red
+	frame.BackgroundTransparency = math.clamp(0.7 - recency * 0.6, 0, 1)
+	frame.Rotation = 0
+end
+
+function Void.swatch(frame: Frame, palette: Theme.Palette)
+	local centre = Vector2.new(20, 12)
+	local pool = Draw.pool(frame, 26, "Mote", true)
+	for index = 1, 24 do
+		local ring = 1 + (index - 1) % 3
+		local turn = Draw.hash(index, 43) * math.pi * 2
+		local radius = 5 + ring * 3.4
+		Draw.dot(
+			pool[index],
+			centre + Vector2.new(math.cos(turn) * radius, math.sin(turn) * radius * FLATTEN),
+			1 + math.floor((3 - ring) * 0.7),
+			palette.violet:Lerp(palette.amber, 1 - ring / 3),
+			0.45
+		)
+	end
+	Draw.dot(pool[25], centre, 9, palette.background, 0)
+end
+
+return Void

package/plugin/src/Themes/init.luau

@@ -0,0 +1,116 @@
+--!strict
+--[[
+	The preset registry: which themes exist, which is active, and who to tell
+	when that changes.
+
+	Deliberately dumb. It holds no drawing code and no Instances -- it maps ids
+	to modules, remembers one id, and fires listeners. Everything visual lives
+	in the preset modules and everything stateful lives in Visuals, so this file
+	is the one place you can look to answer "what themes are there" without
+	reading eight renderers.
+
+	Persistence is not done here either. `plugin` is a script-level global that
+	ModuleScripts do not get, so init.server.luau reads the stored id at startup
+	and writes it back from `onChanged`. That keeps the only Studio-specific
+	dependency in the one file that already has it.
+]]
+
+local Theme = require(script.Theme)
+
+local Themes = {}
+
+export type Theme = Theme.Theme
+export type Palette = Theme.Palette
+export type Context = Theme.Context
+export type Slot = Theme.Slot
+
+--[[
+	Presentation order in the picker, which is not alphabetical.
+
+	Lattice first because it is the default and the one people return to. Then
+	the two dark presets closest to it, then the colourful ones, then the two
+	that abandon the aesthetic entirely. A user scanning the drawer should be
+	able to stop as soon as the list stops looking like what they came for.
+]]
+local ORDER: { Theme.Theme } = {
+	require(script.Lattice),
+	require(script.Observatory),
+	require(script.Orbit),
+	require(script.Void),
+	require(script.Nebula),
+	require(script.Aurora),
+	require(script.Phosphor),
+	require(script.Blueprint),
+}
+
+local byId: { [string]: Theme.Theme } = {}
+for _, theme in ORDER do
+	byId[theme.id] = theme
+end
+
+local DEFAULT = "lattice"
+local activeId = DEFAULT
+local listeners: { (Theme.Theme) -> () } = {}
+
+function Themes.list(): { Theme.Theme }
+	return ORDER
+end
+
+--[[
+	Looks up a preset, falling back to the default rather than erroring.
+
+	The id can come from a saved setting written by an older or newer build, so
+	an unknown one is expected rather than exceptional -- and a console that
+	refuses to start because a theme was renamed would be a bad trade for a
+	cosmetic feature.
+]]
+function Themes.get(id: string?): Theme.Theme
+	if id ~= nil then
+		local found = byId[id]
+		if found ~= nil then
+			return found
+		end
+	end
+	return byId[DEFAULT]
+end
+
+function Themes.active(): Theme.Theme
+	return Themes.get(activeId)
+end
+
+function Themes.palette(): Theme.Palette
+	return Themes.active().palette
+end
+
+function Themes.activeId(): string
+	return activeId
+end
+
+--[[
+	Switches presets and tells everyone who cares.
+
+	Returns whether anything changed, so a caller re-selecting the current theme
+	does not pay for a full remount and a repaint of the log.
+]]
+function Themes.use(id: string): boolean
+	local theme = Themes.get(id)
+	if theme.id == activeId then
+		return false
+	end
+	activeId = theme.id
+	for _, listener in listeners do
+		listener(theme)
+	end
+	return true
+end
+
+--[[
+	Registers a listener. There is no unsubscribe: every listener here lives as
+	long as the plugin does, and an unsubscribe nobody calls is a function that
+	rots rather than one that helps.
+]]
+function Themes.onChanged(listener: (Theme.Theme) -> ())
+	table.insert(listeners, listener)
+end
+
+return Themes