Skip to content

Plugin Creation Tool

Jump to bottom
Bobby Comet edited this page Aug 23, 2026 · 1 revision

Plugin Creation

Tools → Plugin Creation…

Plugin Creation turns a one-off Custom Node into a portable, schema-validated plugin that users can install and reuse.

It does not invent a second node system. It formalizes the same model Studio already uses:

Custom Node (escape hatch)
        ↓
  Author/refine in dialog
        ↓
  Validate against plugin schema
        ↓
  Generate manifest + plugin JSON
        ↓
  Export  ·  or  ·  Install locally
        ↓
  Community pack/local pack

Custom nodes stay the incomplete-by-design escape hatch for quick experiments. Plugin Creation is the formalization layer on top of them.

When to use Plugin Creation

Situation Use
One-time experiment, throwaway code Custom Node (visual.custom_lua, source.custom_script, etc.)
Reusable node you want to keep across projects Plugin Creation → Install locally
Share with the community/Node Vault Plugin Creation → Export JSON
Something Studio already ships Built-in node (no plugin needed)

Opening the dialog

  1. Open Conky Studio.
  2. Go to Tools → Plugin Creation….
  3. (Optional) Select a Custom Lua or Custom Script node on the canvas first; the dialog will pre-fill the code body and pick the matching category.

Dialog overview

The dialog has five tabs. Work left-to-right.

Tab What you set
1 · Identity Category, type id, label, author, version, description, output kind, poll defaults
2 · Properties The knobs users will see in the Property Panel
3 · Code body The Lua/script/conf that implements the node
4 · Media Tags, homepage, license, icon (for store listing)
5 · Validate/Export Schema check, JSON preview, export or local install

Bottom buttons:

  • Validate — run schema + id checks (does not write files)
  • Export JSON… — save a single-plugin file or mini-manifest
  • Install locally — register into ~/.config/conky-studio/plugins/ and refresh the palette

Tab 1 · Identity

Category

Choose one:

Category Typical use Required body field
logic Expressions, math, bindings lua_expr
visual Drawn widgets (rings, bars, text, effects) lua_draw_body
source Shell/data producers script_body
canvas_ext Conky config directives (own_window, gaps, etc.) conf_directives

Changing category updates the Code body tab and suggests a starter type id.

Type ID

Must match:

^(logic|visual|source|canvas_ext)(\.[a-z][a-z0-9_]*)+$

Examples:

  • visual.plugin.soft_ring
  • source.plugin.weather_local
  • logic.plugin.clamp01
  • canvas_ext.plugin.rounded_corners

Rules:

  • Lowercase letters, digits, underscores only
  • Starts with the category
  • At least one dotted segment after the category

Label, author, version, description

  • Label — what appears in the palette and property panel title
  • Author — your name or handle
  • Version — semver recommended (1.0.0)
  • Description — short help text for the store/plugins dialog

Output kind & poll (logic/source)

  • Logic nodes need an output_kind (number, percent, text, boolean, etc.).
  • Source nodes need poll_mode (interval / once / …) and usually poll_interval.

Tab 2 · Properties

Properties become the fields users edit in the Property Panel.

  1. Click Add (or Add common… for category presets).
  2. Fill:
Field Notes
Key snake_case, starts with a letter (radius, line_width)
Label Human-readable name shown in the UI
Kind float, int, bool, string, color, enum, etc.
Default Starting value
Bindable Allow wiring from other nodes (logic/visual only)
Accepts Optional list of bind kinds (percent,number)
Group Property Panel group header (e.g., Geometry, Colors)
Help Tooltip / help text

Add common… inserts typical properties for the current category (radius, color, thickness, etc.) so you don’t start from a blank list.

You can edit or remove rows later. Keys must stay unique and match the regex above.

Tab 3 · Code body

This is the implementation. The exact field depends on category.

Visual — lua_draw_body

Lua that draws inside the node’s local coordinate space. Studio already provides helpers (cairo, colors, gradients, scale, etc.).

Use placeholders for properties:

-- {radius}, {line_width}, {color} are replaced from property values
cairo_set_line_width(cr, {line_width})
-- color helpers usually take the raw property value

Optional lua_helpers box: extra functions that will be emitted into the generated Lua framework.

Logic — lua_expr

A single expression (or short chunk) that produces the output value. Placeholders work the same way.

Source — script_body

Shell (or other) script whose stdout becomes the source value. Poll settings from the Identity tab control how often it runs.

Canvas ext — conf_directives

One or more Conky config lines. Only keys in the allowed canvas_ext set are accepted (same list the loader uses).

Placeholders

Anywhere in the body you can write {property_key}. At codegen time Studio substitutes the property’s current value (or a safe default). Keep keys identical to the ones you defined on the Properties tab.

Tab 4 · Media (optional)

Used mainly for community/Node Vault listings:

  • Tags — comma-separated search keywords
  • Homepage — project or docs URL
  • License — e.g., MIT, GPLv3 (It must be either of these options)
  • Icon — path or identifier (store-dependent)
  • Screenshot/gif/video fields when you publish to a store pack

You can leave this tab empty for private local plugins.

Tab 5 · Validate/Export

Validate

Click Validate. The log shows:

  • Schema errors from plugins/schema.py + loader.validate_only
  • Type-id regex failures
  • Missing required body fields
  • Unknown property kinds
  • Placeholder keys that don’t match any property

Fix issues on the earlier tabs, then validate again until the log is clean.

Preview

The JSON preview shows the exact object that will be written (same shape as entries in a community plugins.json).

Export JSON…

Saves either:

  • A single plugin object, or
  • A mini-manifest ({ "api_version": "1.1", "plugins": [ … ] })

Choose a location (Downloads, a repo folder, etc.). Share that file, or drop it into a pack that the Plugins dialog / loader can read.

Install locally

Registers the plugin into:

~/.config/conky-studio/plugins/

and refreshes the Studio palette so the new type appears immediately under the correct category. No restart required in normal cases.

After install you can:

  1. Drag the new node from the palette onto the canvas.
  2. Edit its properties like any built-in node.
  3. Build/preview as usual.

Recommended workflow

From a Custom Node you already like

  1. Select the Custom Lua or Custom Script node on the canvas.
  2. Tools → Plugin Creation… (body + category are pre-filled).
  3. Set a proper type id and label.
  4. Add the properties you were hard-coding.
  5. Replace hard-coded numbers in the body with {key} placeholders.
  6. Validate → Install locally.
  7. Delete or keep the original Custom Node as a draft.

From scratch

  1. Tools → Plugin Creation…
  2. Pick category → fill Identity.
  3. Add common… then trim/edit properties.
  4. Write the code body (or paste from a working Custom Node).
  5. Validate → Install or Export.

Using an installed plugin

  • It appears in the palette under its category.
  • Drop it on the canvas like any other node.
  • Wire inputs if properties are bindable.
  • Property Panel shows the fields you defined.
  • Build/Export project as usual — codegen treats plugin nodes the same as built-ins.

To remove a local plugin later, use Tools → Plugins… (or delete the entry from the local plugins pack and restart/refresh).

Sharing with the community

  1. Export a clean mini-manifest or single-plugin JSON.
  2. Include author, version, description, and tags.
  3. Publish via the Node Vault/community plugins process, or open a PR against the community pack.
  4. Others install with Tools → Plugins….

Only share plugins you trust; Studio loads them with the same privileges as other user code.

Rules of thumb & common pitfalls

Do Don’t
Keep type ids unique and descriptive Reuse an existing built-in or plugin id
Validate before every export Ship JSON that fails schema checks
Use {key} placeholders that match property keys Leave magic numbers that users can’t edit
Prefer Install locally while iterating Manually edit the plugins pack by hand unless you know the format
Start from a working Custom Node Try to invent a new node model outside the four categories

Type id rejected
→ Must start with logic., visual., source., or canvas_ext. and use only [a-z0-9_].

Missing body
→ Each category requires its specific field (lua_draw_body, script_body, …).

Property key invalid
→ Lowercase, starts with a letter, only letters/digits/underscores.

Placeholder not substituted
→ Key in {…} must exactly match a property key.

Palette doesn’t update after install
→ Dialog already tries to refresh; if needed, switch tabs or reopen the project.

Architecture reminder

Studio
  ├── Built-in nodes
  └── Custom nodes  ──author──►  Plugin Creation
                                    │
                                    ├─ Schema validation
                                    ├─ Manifest / JSON
                                    └─ Export or local install
                                           │
                                           ▼
                                    Common node model → Codegen

Custom nodes remain the escape hatch. Plugins are the portable, validated form of the same idea. You never have to choose between “quick experiment” and “proper distribution”; you start with the first and promote to the second when it’s ready.

Related

  • Tools → Plugins… — browse, install, and manage plugin packs
  • Custom nodes: visual.custom_lua, source.custom_script, and related types in the palette
  • Project wiki home and Node Vault store for community packs

Clone this wiki locally