-
-
Notifications
You must be signed in to change notification settings - Fork 1
Node Reference Visuals
Node Reference — Visuals
Visuals draw via Cairo in render.lua. They have no data output. Bindable rows accept wires (source/logic kinds must be in accepts).
Placement: cx, cy = centre; x, y = top-left. Layers dock: draw order, hide (skipped in codegen), lock.
Common bind targets: value, trigger, category, title_label, rotation, opacity-related fields where listed.
| value | bindable — all kinds (numbers auto-format) |
| prefix/suffix/decimals | formatting |
| x, y, align, font, colour, halo | style |
What it does: Single-line readout or caption.
Examples: Fixed title "SYSTEM"; wire CPU % for a live number; wire String Format/String Join for Artist — Title. Halo helps on busy wallpapers.
Multi-line block; value bindable (all kinds; newlines separate lines).
Example: Custom Script printing three lines of service status.
Month grid with today highlight, optional outside days, fonts/colours per role.
Example: Side panel on a desktop HUD; pair with Date/Time text above.
Split-flap / departure-board style digit. On value change, it runs a fold-and-shrink animation (cairo_scale + STATE that tracks the previous value).
Example: Large clock digits or a counter that “flips” when the number updates; pair several for multi-digit readouts.
Small bouncing-ellipsis loader.
Example: Idle “thinking” indicator next to a status line or while a long-running script is active.
| value | bindable numeric |
| min/max, cx, cy, radius, thickness, start/sweep | geometry |
| value_suffix, track/fill, caps, gradients | style |
Example: CPU % or RAM % direct. Partial sweep (270°) for “dashboard” look. Stack Ring Track underneath for chrome.
Discrete lit segments (LED-ring style).
Example: Battery or GPU util in sci-fi HUDs; fewer segments = chunkier look.
Analog dial: zones (ok/warn/danger), ticks, needle, optional value text.
Example: CPU temp after Map Range; warn zone from 60%, danger from 85%. Requires current Studio build with framework text helpers (needle labels).
Horizontal/vertical; solid, segmented, or trapezoid skin; optional critical pulse.
Example: RAM % segmented; disk % with pulse ≥ 90%.
Stylized core gauge with accent/warn/critical behaviour (theme chrome).
Static arc only; no value.
Example: Decorative rings behind Arc Gauge or Radar.
| value | bindable; on when ≥ threshold |
| color_on / color_off, glow, cx, cy, radius |
Example: Wire Hysteresis/Threshold output (0/1); threshold 0.5. Status “disk hot”, “VPN down”, etc.
Per-core bars from ${cpu cpuN} inside the visual; no source nodes required.
Example: 8-core strip with heat-map colours at the bottom of a gaming HUD.
Drawn fan (curved Bézier blades + hub) that rotates; speed driven by a bound value. Pairs with the fan_sensors script family. Optional motion-blur ghost-blade pass so motion remains readable even at slow Conky refresh rates.
Example: Wire a fan RPM (or normalised 0–1) so the blades spin proportionally; place next to a temperature gauge.
| value | bindable — rolling samples |
| title_label | bindable caption above the frame (text or numbers) |
| width/height, fill, colours | style |
Example: CPU % history; title wired from String Format CPU {value}%.
Compact, borderless; auto_scale fits recent samples.
Example: Dense row of net down/up sparklines without heavy frames.
Up to three series (value_a/b/c), shared min/max, optional title_label.
Example: CPU temp (A) + GPU temp (B); or download + upload. Leave unused series unwired.
Conky ${top} table (rank, name, CPU, MEM) drawn as rows — no source wiring.
Example: Classic sysmon corner; 5 rows, header on.
Polar / spider chart with up to 6 bound axes. Plots multiple series on one shape (e.g. CPU / RAM / GPU / Disk / Net / Temp as a single polygon).
Example: System-health overview in the centre of a HUD; each axis wired to a normalised 0–1 metric.
Equalizer-style bars arranged in a ring.
Example: Decorative audio-reactive (or CPU-reactive) ring around a central gauge or album art.
| mode | circle/image silhouette/star/triangle |
| trigger + threshold | optional gate |
| pulse Hz, alpha min/max, layers | motion |
Example: Always-on soft ring behind a logo; or trigger from CPU ≥ 85 so the glow only appears under load.
Rotating spiral or tick radar.
Example: Idle chrome; rotation_speed_dps negative to reverse.
Concentric rings, sweep beam, optional blips.
Example: Sci-fi/JARVIS centrepiece under a Reactor Gauge.
Dots on rings; trigger scales speed (and slightly radius).
Example: Wire CPU % so orbits speed up under load.
Decorative EQ (not real FFT). trigger raises energy; unbound uses idle energy.
Example: Trigger from Playback Progress or CPU for “alive” chrome near Now Playing.
Phase disc, illumination, next full/new; approximates lunar eclipses (e.g. deep partial 2026-08-27/28, total 2028-12-31/2029-01-01) and solar-eclipse seasons. Southern hemisphere flips the limb. Labels fit inside the bracket box.
Example: Side widget with brackets on; southern_hemisphere for AU/NZ users.
Face, hands, optional digital readout — wall-clock time, not a source wire.
HUD corner frame; arm length/thickness/which corners.
Spinning record with grooves, label, spindle, and specular sheen. Freezes on a bound spin gate via STATE + delta-time (not naive wall_clock() * rpm), so pause does not jump the angle.
Example: Beside Now Playing / Album Art; gate from playback state so the disc stops cleanly when the track is paused.
Matrix-style falling code, fully procedural (time + index hashing; no per-frame random seed to manage).
Example: Full-panel or side-strip background chrome for a cyberpunk theme.
| Node | Role |
|---|---|
| Rectangle | Panels, cards, backdrop chips (fill/stroke, radius, gradient) |
| HLine/VLine | Section dividers, gutters |
| Crosshair | Reticle/radar centre |
| Circle | Full disc, arc, or pie |
| Star/Triangle | Decorative geometry |
Example: Semi-transparent Rectangle behind a cluster of gauges; HLine under a title.
| path | PNG/SVG (copied to images/ on build) |
| size, rotation (bindable) | |
| swap paths by threshold | optional |
Example: Logo; rotation from a Math node for a slow spin. Threshold swaps for temp-based artwork.
| category | bindable category (or constant for preview) |
Example: Wire Weather Category; no image files needed (vector).
Fetches art via playerctl ecosystem; size/position; daemon helper script.
Example: Square art beside Now Playing text.
Font codepoint glyph (Nerd Font/icon font).
Raw Cairo drawing code, dropped straight into the node's own draw function. Use it for anything the built-in visuals don't cover, or to paste in hand-written Cairo from a legacy theme.
| Offset X/Y | Shifts the whole block via cairo_translate; move your drawing without touching the Lua |
| Input 1–12 | 12 separate bindable sockets (in1…in12). Each accepts percent, Celsius, number, text, or category from one source or logic node |
| code | Runs inside local function(cr, W, H) ... end, with cr, W, H already in scope |
What's already in scope inside code:
-
cr,W,H— the Cairo context and canvas width/height (already translated by Offset X/Y) -
in1…in12— whichever Data inputs you wired, injected as locals before your code runs - Framework helpers —
clamp,lerp,rounded_rect,load_image_cached,wall_clock,studio_draw_text,studio_heat_rgb, and friends. No need to reimplement these. - Anything Conky's Lua/Cairo API normally exposes (
cairo_*,safe_parse,safe_number, etc.)
How the 12 inputs work; read this before wiring:
- Each slot is independent: you can wire up to 12 different source/logic nodes at once (or repeat the same one in more than one slot if that's ever useful).
-
Unwired slots are
nil, not0. This is deliberate; it lets your code tell "nothing wired" apart from "a real reading of zero." Always write:rather than assuminglocal cpu = tonumber(in1) or safe_number('${cpu}', 0)
in1is already a number. That pattern falls back to reading the sensor directly if the slot is left unbound, and still uses the wired value if something is plugged in. - If you need more than 12 live values, don't try to jam more wires in; feed several sources into a Math/combine-style logic node first See the Node reference logic, Custon Plugins, and wire its single output into one of the 12 slots. That trades slot count for one extra hop.
One-directional: Custom Lua has no output socket. Other nodes can feed data into it, but nothing downstream can bind off of it; it's a drawing sink, not a passthrough.
Legacy import: the theme importer wraps hand-written Cairo it can't decompose into a Custom Lua node automatically, and auto-wires common vitals (CPU, RAM, temps, etc.) into the early input slots, patching the pasted Lua so a bound value wins over an internal conky_parse/cache read where one exists.
Example: Paste a legacy theme's raw draw body in as-is first to confirm it still renders, then progressively wire live sources into in1, in2, … replacing hardcoded conky_parse calls with tonumber(inN) or ... fallbacks one at a time.
Where exposed: on_click_command + click region (x,y,w,h) in canvas pixels. Conky mouse hook runs the shell command (e.g., playerctl play-pause).
Many fill-capable nodes support solid/linear/radial via fill mode + end colour. Sparklines, multi-series lines, and segmented gauges use solid colours only.
| HUD idea | Nodes |
|---|---|
| CPU ring + label | CPU % → Arc Gauge; String Format → Text |
| Smooth needle temp | CPU temp → Smooth → Map Range → Needle Gauge |
| Hot LED without flicker | Temp → Hysteresis → LED Dot |
| Net history | Down + Up → Multi-Series; title_label caption |
| Weather row | Category → Weather Icon; Condition + Temp → Text |
| Now Playing | Album Art + String Join(Artist,Title) + Progress Bar |
| Sci-fi chrome | Ring Track, Radar Sweep, Orbit Field (trigger=CPU), Corner Brackets |
| Fan + temp | Fan RPM → Spinning Fan; Temp → Needle or Arc Gauge |
| System spider | Six normalised metrics → Radar Chart |
| Vinyl + art | Playback state → Vinyl Spinner gate; Album Art beside it |
| Cyberpunk panel | Matrix Rain background + Flip Digit clocks + LED Dot status |
| Radial EQ chrome | Trigger (CPU or progress) → Radial Spectrum around a central gauge |
| Legacy paste, live-wired | Legacy import → Custom Lua (auto-wired) → replace conky_parse calls with tonumber(inN) or ...
|