Node Reference Plugins

Node Reference — Plugins

Official-style plugin pack (api_version 1.1). Plugins are data only (JSON metadata + Lua templates). At Build/Live Preview the generated theme substitutes {property} placeholders and runs the Lua inside Conky; same trust model as any theme script. Only install packs you trust.

Install

Tools → Plugins… → Fetch/Install
# or drop a manifest under:
~/.config/conky-studio/plugins/your-pack.json

Installed plugins persist in installed-plugins.json. Uninstall is explicit (survives Fetch). Remote fetch is cached offline as remote-cache.json (catalogue only; not auto-registered on launch).

Slot rule: any property named slot is process-wide state. Use a unique integer per node instance when two of the same type must not share memory (Smooth, Rate Limit, Hold Peak, Hold Min).

Overlap with built-ins: some plugin ids mirror built-in types (logic.smooth, logic.threshold, etc). The plugin version is richer (modes, slots, helpers). Prefer the plugin when you need those features; the built-in always ships without installing anything.

Type ids below are exact registry keys.

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

What it does: One comparison with three output styles; pure 0/1, inverted 0/1, or “pass the value when true else 0”.

Examples:

CPU ≥ 90 → binary → LED Dot/Glow trigger
Temp ≥ 80 → gate → only feed a bar when hot (else 0)
Battery ≤ 20 → below + invert_binary for “healthy” signal

Deadzone — `logic.deadzone`

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

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

Output: number

Example: Fan RPM or net rate: zone 5 kills idle noise; soft keeps a smooth ramp once outside the zone.

Smooth (EMA) — `logic.smooth`

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

Output: number · helper _cs_plugin_smooth

What it does: Exponential moving average across refreshes.

Example: GPU util → Smooth (α≈0.15, slot 1) → Needle Gauge. Second smoother for net → slot 2.

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; numeric value is converted)

Example: Weather Temp (F) → Temp Convert → Text Label or Map Range into a gauge.

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	below all thresholds
t1…t10	float	10…140	bindable thresholds

Output: number (stage index)

Modes:

progressive — must pass step 1, then 2, etc (breaks on first miss)
highest — highest step whose threshold is met
exact_band — step i if t[i] ≤ v < t[i+1]

Examples: Battery 0–100 → stages for 4 icons; Wi-Fi quality → signal-bar index; CPU temp → multi-LED strip index.

Round — `logic.round`

Richer than built-in nearest-only Round.

Prop	Kind	Default	Bindable	Notes
value	float	0	yes
mode	enum	`nearest`		nearest/floor/ceil
decimals	int	0		0–6

Output: number

Example: Floor temp to whole degrees before Unit Format; ceil load for conservative display.

AND (0/1) — `logic.boolean_and`/OR (0/1) — `logic.boolean_or`

Prop	Notes
a, b	bindable; truthy if ≥ threshold (default 0.5)
threshold	configurable truth cut-off

Output: number (0/1)

Example: (CPU hot) OR (GPU hot) → Glow. (Disk full) AND (swap high) → warn Badge via Pick.

NOT (0/1) — `logic.boolean_not`

| value | bindable | inverted vs threshold |

Output: number (0/1)

Example: Invert “playing” gate so a Dim Dot shows only when paused/stopped.

Pick (A/B) — `logic.pick`

| selector ≥ threshold → a, else b (all bindable) |

Output: number

Example: Selector = battery low threshold; A = warn colour index, B = normal; feed into a downstream visual or Enum Map style chain.

Percent of — `logic.percent_of`

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

Output: percent

Example: GPU VRAM used ÷ VRAM total → Arc Gauge. Disk used bytes ÷ size when you only have raw numbers.

Unit Format — `logic.unit_format`

Prop	Notes
value	bindable number
decimals, prefix, suffix	e.g., suffix `°C`

Output: text

Example: CPU temp → Unit Format ({value} + °C) → Text Label. Prefer this over String Format when you only need prefix/suffix/decimals.

Rate Limit — `logic.rate_limit`

Prop	Notes
value	bindable
max_step	max change per refresh
slot	unique per node

Output: number · helper _cs_plugin_ratelimit

Example: Cap how fast a needle can swing (max_step 2–5) so sudden sensor spikes don’t look broken.

Hold Peak — `logic.hold_peak`

Prop	Notes
value	bindable
decay	drop per tick when not making a new high
slot	unique per node

Output: number · helper _cs_plugin_peak

Example: Classic peak marker above a History Graph or Bar (decay 0.2–1.0 depending on refresh rate).

Hold Min — `logic.hold_min`

Trough counterpart to Hold Peak (relax upward by decay).

Output: number · helper _cs_plugin_holdmin

Example: Coldest CPU temp “today” readout; lowest battery % since theme start.

Modulo — `logic.modulo`

value % divisor (0 if divisor is 0).

Output: number

Example: Wrap rotation angle 0–360; cycle stage indices.

Data Rate Format — `logic.data_rate_format`

Prop	Kind	Default	Notes
value	float	0	raw KB/s (Network Download/Upload)
binary_prefixes	bool	true	KiB/MiB vs KB/MB
decimals	int	1
suffix	string	`/s`

Output: text

Example: Net down → Data Rate Format → Text Label (1.4 MiB/s). Pair with a sparkline for the same source.

Text Case — `logic.text_case`

Prop	Notes
value	bindable text/category
mode	`upper` / `lower` / `title`

Output: text

Example: Playback Status → UPPER → Badge. Weather condition → Title Case → Text Label.

Visual plugins

Dot — `visual.plugin.dot`

Always-on filled circle (no threshold).

Prop	Default	Notes
x, y, radius	40, 40, 6
color, opacity	`#4fd1c5`, 1

No data output.

Example: Static status blip, bullet beside a row, or decorative point on a radar face. For on/off by value use built-in LED Dot or Pulse Dot.

Badge — `visual.plugin.badge`

Rounded-rect chip with centred text.

Prop	Notes
x, y, width, height, corner_radius	shape (half height ≈ pill)
text	bindable text/category
font_size, bg_color, text_color	style

No data output.

Examples: Wire Playback Status → Badge (PAUSED). Weather Category → Badge. Text Case(upper) → Badge for HUD chips (ONLINE).

Tick Ring — `visual.plugin.tick_ring`

Decorative radial ticks (chrome only).

Prop	Notes
cx, cy, radius
tick_count, tick_length, tick_width
start_angle_deg, sweep_deg	partial rings supported
color, opacity

No data output.

Example: Stack under Arc Gauge or Segmented Gauge; 60 ticks for a clock-like face without Analog Clock.

Pulse Dot — `visual.plugin.pulse_dot`

Pulses (size + alpha) while active ≥ 0.5; dim/static otherwise.

Prop	Notes
x, y, radius, color
active	bindable number/percent/boolean
speed	pulse frequency multiplier

No data output.

Examples: Threshold(CPU ≥ 85) → active. Playback-derived 0/1 → “music is playing” indicator. OR(CPU hot, GPU hot) → active.

Built-in vs plugin (quick)

Need	Prefer
Simple 0/1 cut	Built-in Threshold Gate or plugin Threshold
Pass value/invert/equal±ε	Plugin Threshold
EMA smoothing	Built-in Smooth or plugin Smooth (slot)
°F ↔ °C	Plugin Temp Convert
Multi-stage index	Plugin Threshold Chain
Floor/ceil round	Plugin Round
Human net speed text	Plugin Data Rate Format
Always-on blip	Plugin Dot
Threshold LED	Built-in LED Dot
Status pill	Plugin Badge

Authoring & validation

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

Rules of thumb:

Ids must match logic.* or visual.* (lowercase)
Logic needs output_kind + lua_expr; visual needs lua_draw_body
Every {placeholder} in Lua must declare a property (except the draw context)
Optional lua_helpers emitted once per plugin id into the theme
See repo PLUGIN_AUTHORING.md and wiki Plugins

Recipe table

Goal	Chain
Quiet needle	Source → Smooth → gauge
Hot pulse only under load	Source → Threshold → Pulse Dot active
VRAM % ring	VRAM used + total → Percent of → Arc Gauge
Net readout	Net down → Data Rate Format → Text
Battery icon stages	Battery % → Threshold Chain → Image path logic
Status chip	Category / Text Case → Badge
Peak marker	Source → Hold Peak → thin Bar or Text
°F weather on °C HUD	Weather Temp F → Temp Convert → Text/Map Range

Plugins are where ideas are tested and expanded. Features that become fundamental to the node language may graduate into the core system.

Uh oh!

Node Reference Plugins

Node Reference — Plugins

Logic plugins

Threshold — logic.threshold

Deadzone — logic.deadzone

Smooth (EMA) — logic.smooth

Temp Convert — logic.temp_convert

Threshold Chain (10-Stage) — logic.threshold_chain_10

Round — logic.round

AND (0/1) — logic.boolean_and/OR (0/1) — logic.boolean_or

NOT (0/1) — logic.boolean_not

Pick (A/B) — logic.pick

Percent of — logic.percent_of

Unit Format — logic.unit_format

Rate Limit — logic.rate_limit

Hold Peak — logic.hold_peak

Hold Min — logic.hold_min

Modulo — logic.modulo

Data Rate Format — logic.data_rate_format

Text Case — logic.text_case

Visual plugins

Dot — visual.plugin.dot

Badge — visual.plugin.badge

Tick Ring — visual.plugin.tick_ring

Pulse Dot — visual.plugin.pulse_dot

Built-in vs plugin (quick)

Authoring & validation

Recipe table

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Threshold — `logic.threshold`

Deadzone — `logic.deadzone`

Smooth (EMA) — `logic.smooth`

Temp Convert — `logic.temp_convert`

Threshold Chain (10-Stage) — `logic.threshold_chain_10`

Round — `logic.round`

AND (0/1) — `logic.boolean_and`/OR (0/1) — `logic.boolean_or`

NOT (0/1) — `logic.boolean_not`

Pick (A/B) — `logic.pick`

Percent of — `logic.percent_of`

Unit Format — `logic.unit_format`

Rate Limit — `logic.rate_limit`

Hold Peak — `logic.hold_peak`

Hold Min — `logic.hold_min`

Modulo — `logic.modulo`

Data Rate Format — `logic.data_rate_format`

Text Case — `logic.text_case`

Dot — `visual.plugin.dot`

Badge — `visual.plugin.badge`

Tick Ring — `visual.plugin.tick_ring`

Pulse Dot — `visual.plugin.pulse_dot`