Skip to content

.cstudio

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

Project Packages (.cstudio)

How Conky Studio saves, opens, and shares portable project packages.

A .cstudio file is the preferred way to keep a full, re-editable HUD design — the node graph plus the images, fonts, and scripts it depends on, in one archive. Built themes (start.sh + conky.conf + render.lua) are for running on the desktop. .cstudio packages are for editing and remixing in Studio.

What a .cstudio file is
Format A normal ZIP archive with a fixed internal layout
Extension .cstudio (also accepted if renamed to .zip as long as the contents are valid)
Purpose Portable, self-contained source project for the Studio canvas
Runtime Not used by Conky at runtime, only by Conky Studio

Studio still builds standard Conky theme folders from the graph. The package is the authoring document, not the shipped HUD.

Package layout

When you Save as .cstudio, Studio writes a zip that typically looks like this:

MyHUD.cstudio
├── project.json          # Full node graph (nodes, edges, windows, groups, labels, canvas)
├── manifest.json         # Human metadata (name, author, description, format version)
└── assets/
    ├── images/           # PNG/SVG and other image paths referenced by nodes
    ├── fonts/            # Optional bundled .ttf/.otf/.ttc when packaging non-common fonts
    └── scripts/          # Custom/companion scripts referenced by path props
Entry Role
project.json Schema-versioned Project model: name, author, description, canvas, windows[], nodes[], edges[], optional groups[] and labels[]
manifest.json Package identity for humans and tools (format, format_version, schema_version, name, author, description, notes)
assets/ Files that used to live as absolute paths on disk; copied in and referenced with package-relative paths

Older bare .json project files still open. The next Save to a .cstudio path upgrades them into a full package (assets collected and paths rewritten).

project.json (the graph)

This is the same structure Studio uses in memory. Important fields:

Field Meaning
schema_version 1 = early canvas-only; ≥2 = explicit windows[]; ≥3 = package-aware projects with relative assets
name / author / description Project identity (folder-safe names: prefer hyphens, not spaces)
canvas Legacy / primary size, FPS, alignment, gaps, window type (mirrored from the primary window)
windows Multi-monitor list: id, name, monitor (auto / primary / output name), size, alignment, optional visible_node_ids
nodes Each node: id, type, x/y, label, props, z, visible, locked, optional click region
edges Wires: src_node → dst_node + dst_prop
groups Editor-only frames (collapse, title, member ids) — not emitted into Conky
labels Free-form canvas notes; not drawn by Conky

Canvas node: every project has a synthetic canvas.root node (id typically canvas) so window settings edit through the same property panel as other nodes.

File props: image paths (path, swap paths, fallbacks), script_path, and list props like asset_paths are rewritten to forms such as:

assets/images/logo.png
assets/scripts/my_poller.sh

so, the package works on another machine without your original absolute paths.

manifest.json

Example shape:

{
  "format": "conky-studio-package",
  "format_version": 1,
  "schema_version": 3,
  "name": "Minimal-HUD",
  "author": "you",
  "description": "Starter from Theme Wizard",
  "notes": "",
  "generic": false
}
Field Notes
format Always conky-studio-package for Studio packages
format_version Package container version (currently 1)
schema_version Matches the project graph schema
generic If true, a minimal default manifest (optional “generic package” save path)

Manifest fields can stay in sync with project.json name/author/description when you fill them on Save.

How Save works

  1. You choose a path ending in .cstudio (or Save uses the current package path).

  2. Studio stages a temporary tree:

    • Copies existing assets/ from an already-open package, if any.
    • Walks node props that reference files (images, scripts, optional fonts).
    • Copies each external file under assets/images, assets/fonts, or assets/scripts.
    • Rewrites props to relative paths inside the package.

  3. Writes project.json and manifest.json.

  4. Zips the tree (atomic write via temp file + replace).

  5. Extracts a working copy under:

    ~/.cache/conky-studio/packages/<hash-of-abspath>/

    so further edits resolve relative assets without re-reading the zip every keystroke.

Warnings: missing assets are reported (path left as-is or noted) rather than silently dropping the node.

Legacy JSON Save: writing a plain .json path still works (graph only, no asset bundling). Prefer .cstudio when sharing or moving machines.

How Open/Load works

Input Behaviour
*.cstudio Treat as zip; extract to package work dir; load project.json
*.zip containing project.json Same as package (renamed packages still open)
Bare *.json / Hud.json Load graph only; package_root is empty until first asset import or package Save

On package load:

  1. Validate zip.
  2. Extract to ~/.cache/conky-studio/packages/....
  3. Prefer root project.json; if missing, first root-level *.json is tried.
  4. Set package_root and source_path on the Project so relative paths resolve against the extracted tree.

Relative paths and resolution

While a package is open, Studio resolves a path by checking, in order:

  1. Absolute path that already exists on disk
  2. Under package_root and common subfolders (assets/, assets/images, assets/fonts, assets/scripts, legacy images/, fonts/, scripts/)
  3. Path as given relative to the current working directory

Import asset into package: when you pick an image or script for a node, Studio can copy it into assets/... and store the relative path in props so the next Save stays self-contained.

Fonts: common families (Sans, DejaVu, Liberation, Noto, Ubuntu, etc.) are not forced into the package. Uncommon families can be listed for optional bundling when packaging.

Multi-window projects in the package

windows[] is part of project.json. Each entry can include:

  • Monitor pin (auto, primary, or a concrete output name from xrandr/discovery)
  • Size, alignment, gaps, FPS
  • Optional visible_node_ids so one window only draws a subset of visuals

The primary window stays mirrored onto legacy canvas fields so older tools and single-window paths still read a coherent size/FPS. Schema is bumped to at least 2 when more than one window is stored, and 3 when packaging with assets.

Groups and labels

These are stored in the package for editor UX only:

  • Groups — frames around nodes; collapse/expand; do not change generated Lua
  • Labels — free-form notes on the canvas; not drawn by Conky

They round-trip in project.json so collaborators keep the same graph layout annotations.

What is not in the package

Not stored Why
Generated conky.conf / render.lua / start.sh Produced by Build; recipients who only run the HUD get a theme folder, not the package
Installed plugin Lua from disk (except as graph type ids) Plugins must be installed on the machine that opens the graph, or nodes appear as missing
System-wide fonts by default Only optionally bundled uncommon font files
Live Preview scratch dirs Temporary under the system temp area

Sharing recommendations

Goal Share
Someone only wants to run the HUD Built theme folder (or zip of that folder) under ~/.config/conky/<Name>/
Someone wants to edit/remix in Studio .cstudio package (or project JSON + assets + note required plugins)
Public release Prefer built theme for end users; optionally attach .cstudio for remixers

Plugin friction: if the graph uses community node types, document the plugin pack ids. Missing plugins do not unpack the zip; they show as missing/placeholder nodes until the pack is installed.

Names: use hyphenated project names (Minimal-HUD). Spaces break install paths and lock files when you Build & Install.

Schema versions (summary)

Version Meaning
1 Early projects; canvas-centric
2 Explicit windows[] multi-monitor support
3 Package format with relative assets/ paths

Load always migrates older files into a coherent in-memory Project (e.g., synthesizing windows[0] from canvas when needed). Save writes the current schema so re-open is lossless.

Troubleshooting

Symptom Check
Package won’t open Valid zip? Contains project.json (or a single root JSON)?
Images blank after open on another PC Were they absolute paths never packaged? Re-open original, re-pick assets, Save as .cstudio
“Missing: visual.plugin…” Install the plugin pack that registered that type
Huge package size Large PNGs/scripts under assets/; compress images before import
Edits not in the zip on disk Save again; work tree is under ~/.cache/...; Save rewrites the .cstudio file

Related wiki pages

Clone this wiki locally