Skip to content

Concepts

Jump to bottom
Bobby Comet edited this page Aug 3, 2026 · 2 revisions

Concepts

Conky Studio is a visual node-based authoring environment for creating Conky HUDs.

Instead of manually editing Conky configuration files, Lua drawing code, and scripts, Studio lets you build a project as a graph:

Source → Logic → Visual

The graph describes what data exists, how it is transformed, and how it is displayed. When you build a theme, Conky Studio converts that graph into normal Conky files that run independently.

The Core Idea

Conky Studio separates three jobs:

Layer Purpose
Sources Provide data
Logic Transform or process data
Visuals Draw information on screen

A simple CPU widget might look like:

CPU Usage
   ↓
Smooth
   ↓
Arc Gauge

The CPU source provides the value.

The Smooth node reduces jitter.

The Arc Gauge displays the result.

Nodes

Nodes are the building blocks of a Conky Studio project.

Each node has a specific purpose and exposes properties that control its behavior.

A node may have:

  • Inputs
  • Outputs
  • Properties
  • Generated code behavior

Nodes are connected using wires. The connection determines how information flows through the project.

Sources

Sources are where data enters the graph.

Examples:

  • CPU usage
  • Memory usage
  • Temperature sensors
  • Network statistics
  • Battery information
  • Weather data
  • Custom scripts

Sources usually provide one output value.

Example:

source.cpu_percent
        |
        ↓
      42%

Sources do not decide how data looks. They only provide information.

Logic

Logic nodes transform data.

They sit between sources and visuals when additional processing is needed.

Examples:

  • Smooth noisy values
  • Map one range to another
  • Compare values
  • Create triggers
  • Convert units
  • Format text

Example:

GPU Temperature
        |
        ↓
   Map Range
        |
        ↓
   Danger Indicator

Logic allows complex behavior without manually writing Lua.

Visuals

Visual nodes draw the HUD.

Examples:

  • Text labels
  • Bars
  • Gauges
  • Graphs
  • Effects
  • Decorative animations Visuals receive data but do not normally output data.

Example:

CPU Usage
    |
    ↓
CPU Gauge
    |
    ↓
Pixels on screen

A visual can also work without a connection by using a constant value from its properties.

Canvas

The Canvas node is a special project settings node.

It does not draw anything.

It controls the HUD environment:

  • Width and height
  • Position
  • Window behavior
  • Transparency
  • Draw rate
  • Sensor refresh rate

The Canvas defines the workspace where visuals are rendered.

See Node Reference for more in depth details

Data Types

Connections between nodes are type-aware.

Common data kinds include:

Type Meaning
percent 0–100 values such as CPU or battery
celsius Temperature values
number General numeric values
text Strings
category Labels or states
boolean True/false signals

A node can only connect to compatible inputs.

This prevents invalid graphs and makes projects easier to understand.

Plugins

Plugins extend the node system.

Conky Studio uses a declarative plugin architecture.

Plugins describe:

  • New nodes
  • Properties
  • Inputs and outputs
  • Generated Lua behavior

Plugins do not modify the Studio application itself.

The core defines the system. Plugins expand what can be created.

Core
 |
 +-- Built-in Nodes
 |
 +-- Official Plugins
 |
 +-- Community Plugins

Custom Lua

Conky Studio provides Custom Lua as an escape hatch.

Most projects can be built entirely with nodes, but advanced users can create custom Cairo drawing code when a specific effect or behavior is needed.

Custom Lua allows:

  • Custom rendering
  • Advanced effects
  • Legacy theme migration
  • Specialized visuals

It exists alongside the node system rather than replacing it.

Projects vs Themes

A Studio project and a built theme are different things.

Project

The editable source:

  • Node graph
  • Properties
  • Connections
  • Plugin requirements

Usually stored as JSON.

Built Theme

The generated output:

  • conky.conf
  • Lua files
  • Scripts
  • Assets
  • Runtime files

A built theme runs independently of Conky Studio.

Conky Studio is used to design, build, and manage themes, but it does not need to stay open for a theme to run.

After building, a theme is a normal Conky setup with its own scripts and configuration.

You can run a theme manually without the Studio manager:

* Open a terminal
* Navigate to the theme folder:
  cd ~/.config/conky/<theme-folder>
* Start the theme:
  ./start.sh

Project JSON
      ↓
 Conky Studio Build
      ↓
 Standalone Theme

The Build Pipeline

When a project is built:

Node Graph
     ↓
Validation
     ↓
Dependency Resolution
     ↓
Lua Generation
     ↓
Conky Files
     ↓
Running HUD

The generated theme is the final product.

Studio is an authoring tool, not a runtime requirement.

Design Philosophy

Conky Studio follows a simple principle:

Make complex HUD creation accessible without hiding the power of Conky.

The goal is not to replace Conky.

The goal is to provide a visual way to design, organize, and generate real Conky themes.

Start simple:

2 nodes → 1 widget

Scale when needed:

Sources
   ↓
Logic
   ↓
Visuals
   ↓
Custom Lua
   ↓
Complete HUD systems

Conky Studio grows with the complexity of the creator.

Clone this wiki locally