-
-
Notifications
You must be signed in to change notification settings - Fork 1
Plugins
Plugins extend the Studio node palette with extra logic and visual types. A plugin pack is data only: JSON metadata plus Lua templates. Conky Studio does not run Python from a pack. At Live Preview and Build, the generated Lua runs inside Conky.
Plugin Lua has the same privileges as theme scripts inside Conky (io.popen, os.execute, file I/O, etc. may be available). Only install packs you trust. Treat a remote manifest the same way you treat downloading a theme.
| Method | How |
|---|---|
| In-app | Tools → Plugins — set a manifest URL, Fetch, check entries, Install Checked |
| Local drop-in | Put *.json under ~/.config/conky-studio/plugins/ (loaded on startup; same shape as plugins.json) |
| Persistence | Installed plugins are stored in installed-plugins.json under that directory and survive restarts and Fetch |
| Uninstall | Tools → Plugins → select installed → Uninstall (also writes uninstalled-ids.json so Fetch won’t re-apply them until you install again) |
| Remote default | Project/GitHub raw plugins.json (URL shown in the Plugins dialog) |
After install, the palette refreshes when the dialog closes (or reopen Studio). Projects that reference a missing plugin type still open; those nodes show as Missing plugin placeholders until the pack is installed.
Startup behaviour: only local installed packs are auto-loaded. The remote catalogue is for Fetch/Install, not silent auto-install on every launch. remote-cache.json is an offline catalogue, not an install list.
| Category | Required fields | Role |
|---|---|---|
| logic |
output_kind, lua_expr
|
One Lua expression evaluated in refresh_sources(); sits between sources and visuals |
| visual | lua_draw_body |
Cairo draw body inside draw_node_<id>(cr, W, H)
|
There are no plugin categories for source or canvas (those need real polling scripts or fixed window semantics).
Optional (api 1.1): tags, lua_helpers (shared Lua emitted once per plugin type per build), simple_mode, homepage, license.
Same as built-ins:
- Drag from the palette (or double-click) onto the canvas
- Set properties in the Properties dock
- Wire bindable inputs from sources / other logic
Logic plugins appear under Logic (often subcategory Plugins). Visual plugins appear under Visuals. Simple-mode plugins also show when the palette is set to Simple.
The official pack reimplements or extends some ideas that also exist as built-ins. Registry ids must stay unique. Built-in examples: logic.math, logic.conditional, logic.smooth, logic.threshold, visual.bar, … Plugin examples use the same names in the UI but may be richer (e.g., plugin logic.threshold modes, plugin logic.smooth with a Slot). Prefer one or the other in a graph; do not assume two “Threshold” nodes are interchangeable across machines unless the same pack is installed.
api_version: 1.1 · updated_at: 2026-08-02 · 58 entries
Authors in this pack: conky-studio and community-pack.
| Id | Label | Simple | Notes (short) |
|---|---|---|---|
logic.threshold |
Threshold | ✓ | Above/below/equal; binary, gate, or invert |
logic.deadzone |
Deadzone | Zero small magnitudes; optional soft edge | |
logic.smooth |
Smooth (EMA) | ✓ | EMA with per-instance Slot state |
logic.temp_convert |
Temp Convert | ✓ | °F ↔ °C |
logic.threshold_chain_10 |
Threshold Chain (10-Stage) | ✓ | Stage index 1–10 for image chains / pickers |
logic.round |
Round | ✓ | Nearest / floor / ceil + decimals |
logic.boolean_and |
AND (0/1) | Configurable truth threshold | |
logic.boolean_or |
OR (0/1) | ||
logic.boolean_not |
NOT (0/1) | ||
logic.pick |
Pick (A/B) | ✓ | Selector vs threshold → A or B |
logic.percent_of |
Percent of | ✓ | value/total × 100 (safe total=0) |
logic.unit_format |
Unit Format | ✓ | Number → text with prefix/suffix/decimals |
logic.rate_limit |
Rate Limit | Max step per refresh (Slot) | |
logic.hold_peak |
Hold Peak | Peak hold + optional decay | |
logic.modulo |
Modulo | Wrap / cycle | |
logic.data_rate_format |
Data Rate Format | ✓ | Auto KiB/s, MiB/s style text |
logic.text_case |
Text Case | ✓ | Upper / lower / title |
logic.hold_min |
Hold Min | Trough hold | |
logic.coerce_number |
Coerce Number | ✓ | Text → number bridge |
logic.coerce_text |
Coerce Text | ✓ | Number → text bridge |
logic.truthy |
Truthy Gate | ✓ | Non-zero / non-empty → 0/1 |
logic.string_length |
String Length | ||
logic.substring |
Substring | ||
logic.remap_curve |
Remap Curve | Ease-style remap | |
logic.counter |
Frame Counter | Stateful counter |
| Id | Label | Simple | Notes (short) |
|---|---|---|---|
visual.plugin.dot |
Dot | ✓ | Simple filled circle/LED |
visual.plugin.badge |
Badge | ✓ | Rounded chip + label |
visual.plugin.tick_ring |
Tick Ring | ✓ | Decorative tick ring |
visual.plugin.pulse_dot |
Pulse Dot | ✓ | Animated pulse |
visual.plugin.signal_bars |
Signal Bars | ✓ | Wi‑Fi style bars |
visual.plugin.thermometer |
Thermometer | Vertical temp fill | |
visual.plugin.spinner |
Spinner | ✓ | Loading ring |
visual.plugin.heartbeat |
Heartbeat Line | ECG-style line | |
visual.plugin.liquid_fill |
Liquid Fill | Wave fill gauge | |
visual.plugin.traffic_light |
Traffic Light | ✓ | 3-state threshold LEDs |
visual.plugin.hex_tile |
Hex Tile | ✓ | Hex shape |
visual.plugin.hex_gauge |
Hex Gauge | Hex ring gauge | |
visual.plugin.dot_matrix |
Dot Matrix Field | Animated grid | |
visual.plugin.chevron_row |
Chevron Row | ✓ | Progress chevrons |
visual.plugin.bubble_meter |
Bubble Meter | Tank/bubbles | |
visual.plugin.concentric_pulse |
Concentric Pulse | Sonar rings | |
visual.plugin.spark_burst |
Spark Burst | Radial sparks from trigger | |
visual.plugin.soft_shadow_panel |
Soft Shadow Panel | ✓ | Card with soft shadow |
visual.plugin.led_bar_horizontal |
LED Bar (Horizontal) | ✓ | Segmented LED meter |
visual.plugin.compass |
Compass Rose | Heading needle | |
visual.plugin.minimap_grid |
Minimap Grid | Blueprint grid | |
visual.plugin.value_arc_ticks |
Value Arc Ticks | ✓ | Discrete lit ticks on an arc |
visual.plugin.digital_clock |
Digital Alarm Clock | ✓ | 7-segment style clock |
visual.plugin.attitude_indicator |
Attitude Indicator | Artificial horizon | |
visual.plugin.altimeter |
Altimeter | Dual-needle altimeter face | |
visual.plugin.soft_shadow_circle |
Soft Shadow Circle | ✓ | Soft shadowed disc |
visual.plugin.aurora_veil |
Aurora Veil | ✓ | Drift ribbons/backdrop |
visual.plugin.capsule_bar |
Capsule Bar | ✓ | Stadium progress bar |
visual.plugin.ember_field |
Ember Field | ✓ | Rising particles |
visual.plugin.scrolling_text |
Scrolling Text | ✓ | Marquee/now-playing |
visual.plugin.battery_icon |
Battery Icon | ✓ | Body + fill + charge mark |
(Exact property lists live in the manifest; open Tools → Plugins or the JSON for full schemas.)
Document required plugin ids and where to get the pack. Recipients need the same packs installed, or those nodes stay missing. If they only need to run the HUD, ship a built theme folder (start.sh + render.lua + scripts) instead of the .json project.
Authoring rules, placeholder syntax, validation, and layout conventions: How to make plugins (separate page below).