Skip to content

Manifest Reference ​

plugin.json describes the plugin and every node it adds.

Plugin ​

Field
sdkrequiredSDK version the plugin targets. Currently 1. A plugin asking for a newer SDK than the installed Caddis supports won't load, and says so.
idrequiredLowercase reverse-DNS, unique to you: com.yourname.glowpack.
namerequiredShown in Manage Plugins and on hover.
versionrequiredSemver (1.2.0). The major number is part of every node's identity — see Versions below.
vendorShown on the node's pill.
description, websiteShown in Manage Plugins.
wasmPath of the WebAssembly module, for nodes with logic.
licensePaid plugins: see Selling Plugins.
assetsTextures shipped in the bundle (below).
modulesReusable blocks of passes (below).
nodesrequiredThe nodes (below).

Versions ​

A node saved in a project is identified by plugin id, node id and major version (plugin:com.yourname.glowpack/softGlow@1). Minor and patch releases replace the installed version in place: keep param ids stable and add new params with defaults that preserve old looks. Nodes already in a project follow the update straight away, including a live-reloaded dev folder: a param keeps its value while its id and type stay the same, picks up a new label, starts at its default if its type changed, and disappears if you removed it; inputs and outputs are rebuilt, and a wire into a port you removed is disconnected. So never reuse a removed id for something new. A major version is a new node type, so old projects keep using the old one while it stays installed.

Node ​

Field
idrequiredIdentifier, unique in the plugin.
labelrequiredThe node's name in the graph and menus.
descriptionShown in search and the fallback help page.
categoryThe built-in category it's closest to (Effects, Shapes…). Used for search; plugin nodes are listed under Plugins.
inputs, outputsPorts (below).
paramsSettings (below).
timestatic (default), animated, history or stateful — see Time and State.
maxLookbackHistory / stateful nodes: how many frames back any pass reads (max 64).
boundsHow the output extent relates to the input's (below).
texturesIntermediate textures by name (below).
stateTextures kept between frames (stateful nodes).
buffersGPU storage buffers by name (below).
groupsSections in Properties (below).
gizmosHandles drawn in the viewer (below).
passesGPU passes, run in order (below).
logicName of the WebAssembly export that computes the node's points / shapes / values.
docsHelp page path (default docs/<id>.md).

Ports ​

json
{ "id": "src", "type": "image", "label": "Source" }

type is one of image, mask, points, shape, text, string, scalar, vec2, vec3, color. Port ids are identifiers. Your shaders use them by name, so pick something other than reserved words (in is a GLSL keyword; prefer src).

Image ports go to and from passes. Points, shapes and values go to and from logic, and passes can read points too (see Writing Shaders).

Params ​

json
{ "id": "radius", "type": "float", "label": "Radius", "default": 20,
  "min": 0, "softMax": 200, "unit": "px", "group": "Glow", "expose": true }
typeStored asIn shadersProperties control
floatnumberf32number field
intnumberi32whole-number field
angledegreesf32 radiansnumber field with ° and a dial
boolbooli32 0 / 1checkbox
enumthe option's texti32 index into optionsmenu
vec2x, yvec2<f32>linked pair
pointx, yvec2<f32>pair, plus a handle in the viewer
vec3x, y, zvec3<f32>triple
colorr, g, b, avec4<f32>, linear, straight alphacolor picker
string, text, filetext— (logic only)field / multi-line / file picker
gradient, curverampa 256×1 lookup texture via @param.<id>gradient / curve editor
colorCurvesfour curves (master, R, G, B)@param.<id>: each channel's curve applied after the master in .rgb, the master alone in .athe Curves editor, with the input's histogram
levelsthe Levels values@param.<id>, laid out like colorCurvesthe Levels editor, with the input's histogram
toneRangestart, end, softness, channelvec4(start, end, softness, channel), channel 0–3 = Luma / Red / Green / Blue; @param.<id> is the selection weight (0–1) by brightnessrange selector over the input's histogram
triggerkeyframesf32 frames since the latest key, −1 if noneFire Here button
customtext, in a format you choosewith "bake": a lookup via @param.<id>a control your plugin draws (optionally over the input's histogram), see Custom Controls
button——a button: runs "action" (a WebAssembly export) or "resets" settings to their defaults
label——a line of text ("text")
divider——a hairline between rows

Other fields:

Field
labelDefaults to the id, split into words.
defaultA number, [x, y], [r, g, b, a], true / false or a string. Gradients take { "stops": [{ "position": 0, "color": [r,g,b,a] }, …], "interpolation": "linear" }, plus an optional "blendSpace" — the gradient editor's Color Blend: "linearLight" (the default), "srgb", "oklab", "oklch" or "oklchLong"; @param.<id> is baked in it — curves { "points": [{ "position": 0, "value": 1 }, …], "interpolation": "smooth" }, ranges { "lo": 0.5, "hi": 1, "soft": 0.1, "channel": "Luma" }.
min, maxHard limits. Values past them are clamped.
softMin, softMaxSlider range only. Typing past it is allowed.
stepDrag step.
unitShown after the label: px, %, Hz.
optionsenum choices, in menu order.
groupThe section the row sits in: a declared group's id (see Groups), or any name for a plain section. Rows without a group sit at the top level. Properties keeps your order.
visibleWhenAn expression (below). The row hides while it's false.
exposeAdds an E port (<id>_in) so a wire can drive the setting.
keyframeablefalse hides the keyframe diamond.
tooltipHover text.
extensionsfile params: allowed file extensions.
rowSettings with the same row id, next to each other, share one row in Properties under the first one's label, with one keyframe diamond for all of them. Numbers, angles, toggles and menus only.
shortIn a row: the tag before this field (1–2 characters; default the label's first letter).
textlabel rows: the text.
actionbutton: the WebAssembly export to run when pressed (see CPU Logic).
resetsbutton: setting ids or group ids to put back to their defaults when pressed, e.g. ["edges"]. No code needed.
restartstrigger params on a stateful node: each key restarts the node's state and its replay (see Time and State).
palettesgradient params: palettes your plugin ships, listed first in the gradient editor's palette button. Each is shaped like a gradient default: { "stops": [{ "position": 0, "color": [r, g, b, a] }, …], "interpolation": "smooth" }, optionally with a "blendSpace" (see default).

Point coordinates are composition pixels with the origin at the center of the comp, +y down.

Groups ​

Sections in Properties. Declare them to fold, nest or hide them; a param's group names one by id.

json
"groups": [
  { "id": "glow",  "label": "Glow" },
  { "id": "edges", "label": "Edges", "parent": "glow", "collapsed": true },
  { "id": "grain", "label": "Grain", "visibleWhen": "params.mode == 'Grain'" }
]
Field
idRequired. What params' group refers to.
labelHeader text (defaults to the id).
collapsedStarts folded. A section opens by itself when a setting inside it changes or is wired, until the user folds it.
parentNests the section inside another.
visibleWhenAn expression; the whole section hides while it's false.

label and divider entries in params lay out the panel (a line of help text, a hairline). They have no value and aren't saved with the node, but take group and visibleWhen like any row.

Viewer handles ​

Every point param gets a draggable handle in the viewer while its node is selected. gizmos add guides tied to params:

json
"gizmos": [
  { "type": "line",   "from": "start",  "to": "end" },
  { "type": "circle", "center": "center", "radius": "radius" },
  { "type": "angle",  "center": "center", "angle": "direction", "length": 80 },
  { "type": "box",    "min": "topLeft", "max": "bottomRight" },
  { "type": "custom", "draw": "light_draw", "event": "light_event" }
]
TypeDrawsDrags
linea line between two point (or vec2) paramsboth ends
circlea circle of a float radius (comp px) around a pointthe center; the rim sets the radius
anglea dial at a pointthe tip sets an angle param (degrees, 0 = right, clockwise). Shift snaps to 15°. length is in screen pixels.
boxa rectangle between two corner pointsboth corners
customwhatever your draw export returns, see Custom Controlshandles you draw; your event export sets params

Handle drags keyframe like any edit and are one undo step. A param driven by a wire has no handle.

Textures ​

json
"textures": {
  "half":  { "size": { "of": "src", "scale": 0.5 } },
  "flow":  { "size": { "of": "src", "scale": 0.125 }, "format": "rgba32f" },
  "lut":   { "size": { "width": 256, "height": 1 }, "format": "r32f" }
}

size is relative (of an image input, another texture, or "canvas" — the default — times scale, at most 4), or fixed width/height in pixels. Relative sizes follow quality level and overscan automatically. Add "ignoreQuality": true to a relative size to measure it in composition pixels instead, so it is the same size at Draft, Preview, Full and export: use it for a simulation that steps a fixed number of pixels per frame, so it finishes at the same time at every quality (it costs more at Draft, since the texture doesn't shrink).

format: rgba16f (default, the working format), rgba32f, r32f. 32-bit textures can't be filtered: sample them with samp_point or textureLoad.

Bundled textures (assets) ​

Images shipped inside the plugin: blue noise, dither matrices, grain plates, lookup tables. Declared once for the whole plugin, read by any pass as @asset.<name>.

json
"assets": {
  "blueNoise": { "file": "textures/bluenoise64.png", "filter": "nearest", "wrap": "repeat", "colorSpace": "data" }
}
Field
filePNG, JPEG, TIFF or EXR in the bundle.
filterlinear (default) or nearest.
wrapclamp (default), repeat or mirror.
colorSpacesrgb (default for 8- and 16-bit images): decoded to linear light like footage. linear: already linear (the default for EXR). data: used exactly as stored, for noise, matrices and lookup tables.

Assets load as 16-bit float. --protect encrypts them along with your shaders. In GLSL, texture(blueNoise, uv) uses the asset's own filter and wrap. In WGSL, sample with blueNoise_samp.

Buffers ​

GPU storage buffers, for work that doesn't fit in a texture: histograms, sorting, particle state, counters.

json
"buffers": {
  "bins":  { "elements": 256, "type": "uint", "atomic": true },
  "parts": { "elements": "params.maxParticles", "type": "vec4", "state": true }
}
Field
elementsCapacity: a number or an expression.
typefloat, int, uint, vec2 or vec4.
atomicint / uint only: the items and the count are atomics, so many invocations can add to them at once.
stateKept from frame to frame (stateful nodes), replayed and checkpointed like state textures, so it scrubs correctly.

A buffer starts each frame zeroed (or, with state, as last frame left it). Each has a count alongside its items, which you can use as an append counter. Passes name buffers as @buffer.<name> in reads or writes. See Writing Shaders for the shader side.

Modules ​

A module is a block of passes written once and called from any node's pass list, like a function: a blur, a bloom, a sort.

json
"modules": {
  "gaussian": {
    "params": [{ "id": "radius", "type": "float", "default": 10 }],
    "textures": { "across": { "size": { "of": "@in" } } },
    "passes": [
      { "shader": "shaders/blur.glsl", "reads": [{ "input": "@in", "as": "img" }], "writes": "across", "defines": { "AXIS": 0 } },
      { "shader": "shaders/blur.glsl", "reads": [{ "input": "across", "as": "img" }], "writes": "@out", "defines": { "AXIS": 1 } }
    ]
  }
}

Call it from a node's passes:

json
{ "module": "gaussian", "reads": ["bright"], "writes": "blurred",
  "params": { "radius": "params.glowRadius * 0.5" }, "when": "params.glowRadius > 0" }
  • @in is the call's first read (@in.1, @in.2… the others). Unless you rename it with as, its binding name is src (src1, src2…).
  • @out is what the call writes.
  • A module's textures are private to each call, so two calls never share them. "of": "@in" sizes one like the call's input.
  • Each module param binds to an expression in the caller's scope. params.<id> alone passes the caller's param whole, including vectors and colors. An unbound param takes its default.
  • Module params are the value types: numbers, bools, enums, angles, vectors, points and colors. Inside the module's shaders they're the params; the node's own params aren't visible.
  • Modules can call other modules, up to 8 deep. They can't use state, buffers, @param lookups or the node's textures yet.

Passes ​

json
"passes": [
  { "shader": "shaders/threshold.wgsl", "reads": ["src"], "writes": "half" },
  { "repeat": "params.iterations", "pingPong": ["half", "half2"], "passes": [
    { "shader": "shaders/blur.wgsl", "reads": [{ "input": "@prev", "as": "prev" }], "writes": "@next",
      "defines": { "AXIS": 1 } }
  ]},
  { "shader": "shaders/composite.wgsl", "reads": ["src", "@last"], "writes": "out" }
]
Field
shaderA .wgsl or .glsl file in the bundle.
kindfragment (default) or compute.
readsTextures the pass samples, in order. Each is a name, or { "input": …, "frame": …, "as": …, "attributes": […] }.
writesAn image output, a texture, @state.<name>, @next, or (compute) @buffer.<name>.
definesCompile-time constants: one shader file, several variants.
whenAn expression. The pass is skipped while it's false.
workgroupCompute: workgroup size, default [8, 8].
dispatchCompute: what one invocation is for (below).

Compute dispatch:

dispatchRunsEntry
(absent)once per texel of the target, or, for a pass that writes only a buffer, of its first texture readkernel(p)
{ "over": "<texture>" }once per texel of an input, texture, @state.x or @asset.xkernel(p)
"<points binding>"once per point of a @points readkernel_point(i)
{ "count": "<expr>" }i = 0 … count−1 (up to about 4 million)kernel_index(i)
{ "countFrom": "@buffer.x" }i = 0 … x.count−1, read on the GPU (at most the buffer's capacity)kernel_index(i)

What a pass can read:

Name
an image input or texture nameby itself
{ "input": "src", "frame": -1 }the input one frame back (history / stateful nodes)
@state.<name>last frame's state texture
@previnside a pingPong repeat: the texture the previous iteration wrote (the first one before the loop starts)
@lastafter a pingPong repeat: what its last iteration wrote
@param.<id>a gradient, curve, curves, levels or range param as a 256×1 texture (binding <id>_lut)
@points.<port>a points / shape input (or logic output) as a storage buffer
@asset.<name>a bundled texture
@buffer.<name>a storage buffer (compute passes can write it too)

A pass can't sample the texture it writes. Use a second texture, or pingPong. State is the exception: reading and writing @state.x in one pass is the normal feedback step.

repeat takes an expression (capped at 1,024 iterations). pingPong names two textures. If the second isn't declared, it copies the first's size and format.

Bounds ​

Caddis sizes each layer's canvas before rendering, so it needs to know whether your node grows its content:

bounds
"passthrough"Output sits where the input does (color effects, distortions within the image). The default for nodes with an image input.
{ "expand": "params.radius * 3" }Output can extend this many composition pixels beyond the input on every side (glows, blurs, drop shadows).
"generator" / "full"Output fills the comp. The default for nodes with no image input.

Points and shapes your logic outputs are measured automatically.

Expressions ​

repeat, when, bounds.expand and visibleWhen use a small expression language: numbers, 'strings', + - * / %, == != < <= > >=, && || !, a ? b : c, and min max clamp floor ceil round abs sqrt pow log2 exp.

Names: params.<id> (vectors also as params.<id>.x / .y / .z / .w or .r / .g / .b / .a; enums as their option text), scale (render pixels per comp pixel), frame, time (seconds), fps (the composition's frame rate, so a per-second rate becomes a count: "repeat": "round(params.stepsPerSecond / fps)"), width, height (comp size), and iteration inside a repeat. frame, time and fps are known to repeat and when; bounds.expand and visibleWhen see only params.

json
"visibleWhen": "params.mode == 'Glow' && params.radius > 0"