Skip to content

Node Reference Plugins

Jump to bottom
Bobby Comet edited this page Aug 1, 2026 · 5 revisions

Node Reference — Conky Studio Plugins

Official-style plugin pack (api_version 1.1). Install via Tools → Plugins… or drop the manifest under ~/.config/conky-studio/plugins/. Plugins are data only (JSON + Lua templates). Lua runs inside Conky — only load packs you trust. Type ids below are exact registry keys. Slot properties: use a unique integer per instance when two nodes of the same type must not share state.

Logic plugins

Threshold — logic.threshold

Richer than built-in Threshold Gate.

Prop Kind Default Bindable Notes
value float 50 yes accepts number, percent, celsius
threshold float 80 yes same accepts
mode enum above above ≥ · below ≤ · equal ±ε
output_mode enum binary binary 0/1 · gate pass value or 0 · invert_binary
epsilon float 0.01 only for equal mode

Output: number

Deadzone — logic.deadzone

Abs-magnitude deadzone (not centre+radius built-in).

Prop Kind Default Bindable Notes
value float 0 yes accepts number, percent, celsius
zone float 1 yes |value| ≤ zone → 0
soft bool false if on, subtract zone and keep sign

Output: number

Smooth (EMA) — logic.smooth

Exponential moving average.

Prop Kind Default Bindable Notes
value float 0 yes accepts number, percent, celsius
alpha float 0.2 yes 0.01–1; lower = heavier lag
slot int 1 unique per node

Output: number · Uses helper table _cs_plugin_smooth

Temp Convert — logic.temp_convert

Prop Kind Default Notes
value float 72 bindable
direction enum f_to_c f_to_c / c_to_f
decimals enum 1 none / 0 / 1 / 2

Output: celsius (kind tag; value is converted number)

Threshold Chain (10-Stage) — logic.threshold_chain_10

Maps one number to a stage index 1…N (or none_value).

Prop Kind Default Notes
value float 0 bindable
steps_count int 4 1–10 active steps
mode enum progressive progressive / highest / exact_band
none_value float 0 when below all thresholds
t1…t10 float 10…140 bindable thresholds

Output: number (stage index)

Use: image chains, picker indices, multi-LED logic

Round — logic.round

Richer than built-in nearest-only Round.

Prop Kind Default Bindable Notes
value float 0 yes accepts number, percent, celsius
mode enum nearest nearest / floor / ceil
decimals int 0 0–6

Output: number

AND (0/1) — logic.boolean_and

| a, b | bindable floats | truthy if ≥ threshold (default 0.5) → output 1 else 0 |

Output: number (0/1)

OR (0/1) — logic.boolean_or

Same shape as AND with OR semantics.

Output: number (0/1)

NOT (0/1) — logic.boolean_not

| value | bindable | inverted vs threshold |

Output: number (0/1)

Pick (A/B) — logic.pick

| selector ≥ threshold → a, else b (all bindable as listed in pack) |

Output: number

Percent of — logic.percent_of

value / total * 100; 0 if total is 0.

Output: percent

Unit Format — logic.unit_format

Formats number as text with prefix, suffix, decimals (e.g. 42.5 °C).

Output: text

Rate Limit — logic.rate_limit

Max change per refresh (max_step); state in slot.

Output: number · helper _cs_plugin_ratelimit

Hold Peak — logic.hold_peak

Remembers peak with optional decay per tick; slot for state.

Output: number · helper _cs_plugin_peak

Modulo — logic.modulo

value % divisor (0 if divisor is 0).

Output: number

Data Rate Format — logic.data_rate_format

Auto-scales a raw KB/s number into a human string (e.g. 1400 -> '1.4 MB/s'). Companion to Network Download/Upload, which output a raw number in KB/s.

Prop Kind Default Bindable Notes
value float 0 yes raw KB/s
binary_prefixes bool true On: KiB/MiB/GiB (×1024). Off: KB/MB/GB (×1000)
decimals int 1
suffix string /s

Output: text

Text Case — logic.text_case

Force text to UPPER, lower, or Title Case -- e.g. normalizing Now Playing status or a weather condition string before a Text Label.

Prop Kind Default Bindable Notes
value string yes accepts text, category
mode enum upper upper / lower / title

Output: text

Hold Min — logic.hold_min

Remembers the lowest value seen, with optional slow relax back upward. The trough-tracking counterpart to Hold Peak -- e.g. lowest battery drain rate, coldest temp today.

Prop Kind Default Bindable Notes
value float 0 yes accepts number, percent, celsius
decay float 0.5 relax upward per tick; slot for state
slot int 1 unique per node

Output: number · Uses helper table _cs_plugin_holdmin

Visual plugins

Dot — visual.plugin.dot

Always-on filled circle (status LED without threshold).

Prop Kind Default Notes
x float 40
y float 40
radius float 6 1–200
color color #4fd1c5 → r,g,b in Lua
opacity float 1 0–1

No data output. Unlike LED Dot, colour is fixed (no on/off threshold).

Badge — visual.plugin.badge

A rounded-rect status chip with centred text -- wire a category source (Playback Status, Weather Category) or a String Format output straight in for an 'ONLINE' / 'PAUSED' / 'RAIN' style pill.

Prop Kind Default Bindable Notes
x float 20
y float 20
width float 90
height float 24
corner_radius float 12 Half of Height → full pill
text string STATUS yes bindable text/category
font_size float 11
bg_color color #2c8f6a
text_color color #ffffff

No data output. Draw-only visual.

Tick Ring — visual.plugin.tick_ring

Decorative radial tick marks -- chrome to stack under/around an Arc Gauge, Segmented Gauge, or in place of Analog Clock's built-in ticks.

Prop Kind Default Notes
cx float 100
cy float 100
radius float 90
tick_count int 12
tick_length float 8
tick_width float 2
start_angle_deg float -90 degrees
sweep_deg float 360 degrees
color color #4fd1c5
opacity float 0.8

No data output. Draw-only visual.

Pulse Dot — visual.plugin.pulse_dot

A dot that pulses (grows/fades) continuously while Active is truthy, and sits dim/static otherwise -- wire a Threshold Gate, Playback Status via a comparison, or any 0/1-ish signal into Active for a 'something is happening' indicator.

Prop Kind Default Bindable Notes
x float 40
y float 40
radius float 6
active float 1 yes ≥ 0.5 pulses; else dim/static
speed float 1.5 pulse frequency multiplier
color color #4fd1c5

No data output. Draw-only visual.

Install reminder

Tools → Plugins… → fetch / load manifest
# or
~/.config/conky-studio/plugins/your-pack.json

Validate:

from conkystudio.plugins.loader import load_manifest_file, validate_only
print(validate_only(load_manifest_file("pack.json")))

Authoring rules: see wiki Plugins and repo PLUGIN_AUTHORING.md.

Clone this wiki locally