Plugins

Plugins

Plugins extend the node palette with extra logic and visual types. They are data only: JSON metadata + Lua templates. Conky Studio does not execute Python from a plugin pack. Lua runs inside Conky at preview and build time.

Trust model

Plugin Lua has the same privileges as theme scripts inside Conky (io.popen, os.execute, etc. may exist). Only install packs you trust.

Installing

Method	How
In-app	Tools → Plugins; fetch from a manifest URL or load a local pack
Local drop-in	Place *.json under ~/.config/conky-studio/plugins/ (loaded on startup)
Remote default	Project plugins.json (e.g., via the documented GitHub raw URL in the Plugins dialog)

After loading, refresh the palette if needed (reopen Studio or use the dialog’s load flow). Missing plugin types on an opened project may show placeholders or warnings instead of a hard crash, depending on version — install the pack and reload the project.

What plugins can be

Category	Required fields	Role
logic	output_kind, lua_expr	Single Lua expression between sources and visuals
visual	lua_draw_body	Draw statements using Cairo context cr (and W, H)

There are no plugin categories for source or canvas (those need real polling or fixed window semantics).

Using plugin nodes

Same as built-ins: drag from the palette, set properties, wire bindable inputs. Optional lua_helpers define shared functions emitted once per plugin type in a build.

Authoring plugins (summary)

Manifest sketch

{
  "api_version": "1.1",
  "updated_at": "2026-07-30",
  "plugins": [
    {
      "id": "logic.clamp",
      "category": "logic",
      "label": "Clamp",
      "output_kind": "number",
      "properties": [
        { "key": "value", "label": "Value", "kind": "float", "default": 50, "bindable": true, "accepts": ["number", "percent"] },
        { "key": "lo", "label": "Min", "kind": "float", "default": 0 },
        { "key": "hi", "label": "Max", "kind": "float", "default": 100 }
      ],
      "lua_expr": "math.min({hi}, math.max({lo}, {value}))"
    }
  ]
}

Critical rules

Rule	Detail
id	Must match logic.* or visual.* with lowercase segments: ^(logic|visual)(\.[a-z][a-z0-9_]*)+$
Placeholders	Only {property_key}; every {name} in templates must be a declared property (hard error otherwise)
cr, W, H	Bare Lua names in draw bodies, not {W} / {H}
color kind	Substitutes as r, g, b numbers for Cairo, not hex
output_kind	percent · celsius · number · text · category · boolean
Property kinds	float · int · bool · color · string · enum · font · path · code (enum needs choices)

Validate without registering

from conkystudio.plugins.loader import load_manifest_file, validate_only

m = load_manifest_file("my-pack.json")
print(validate_only(m))  # empty list = OK

Sharing projects that use plugins

Document required plugin ids and where to get the pack. Recipients need the same packs installed, or the graph will lack those node types. Prefer shipping a built theme if they only need to run the HUD.