Parameter expressions

Type = in any parameter to drive it with a live formula, referencing time, maths, or another node's value.

Most parameters hold a plain number set by hand. Any of them can instead hold a formula that recomputes every frame. Click into a parameter, type =, and what follows drives the value.

= sin($T) * 10
= circle1.radius * 2
= value + 1

This is the Expression language used in an Expression node, applied inline to a single parameter rather than across a whole collection.

Writing a formula

Start the parameter with =. The = marks the contents as a formula and is stripped before the maths runs.

The time globals are $F (current frame), $T (time in seconds), $FPS and $DT (one frame's duration), so = sin($T * 2) * 5 gives a wobble that follows playback. Maths constants are $PI, $TAU, $E, $PHI, $SQRT2, $LN2 and $LN10.

Those eleven are the whole set here. A parameter formula is evaluated on the CPU against one frame, so the globals that describe an element, a canvas, the transport or the wall clock all read 0 rather than erroring. $BPM and $BEAT in particular are a trap: to follow a musical clock, wire it in from a tempo source instead.

The functions are the 46 scalar maths ones: trigonometry, abs, floor, round, pow, sqrt, min, max, clamp, lerp, mix, smoothstep, step, fit, fit01, remap, saturate, the wave shapers, hash, noise and random. Anything that touches a collection is not among them, so this is a smaller set than the Expression node's. It runs the other way too: noise and random work here and are rejected inside an Expression node.

An expression that fails to parse or evaluate falls back to the parameter's literal value, and the reason is logged to the console.

Clearing a formula

Empty the field and commit. That, and only that, hands the parameter back to a plain number.

Typing a number over a formula does not undo it. A green field takes whatever you type as the formula, so typing 5 leaves the parameter computed, with 5 as the thing it computes. It reads the same and behaves the same for now, and it means the parameter is still shadowing its keyframes and any wire into it. Clear the field if what you wanted was a plain value back.

Formulas a node ships with

A few parameters arrive already carrying one, because the useful default is motion rather than a number. phase on Pattern is the current example: in Wave mode it starts as $T * 90.0, a quarter turn per second, so a fresh Pattern animates without being asked. It behaves like any other formula from there. Edit it, or clear the field to stop it and hold a value by hand.

Referencing another node

Type a node's name, a dot, then the parameter: circle1.radius. The reference binds to the node's current name, whether that is a name you gave it or the automatic name derived from its type.

= circle1.radius * 2
= transform1.position.x + 50

The dot path reaches into a single axis of a multi-part value, so transform1.position.x reads only the X of that node's position.

A reference of this kind wires the two nodes together, so the referenced node always computes first and the parameter updates the moment it changes. That wire is real and it is drawn: typing the reference adds an edge from the referenced parameter into this one, and deleting the reference from the formula removes it again.

A parameter can also reference another node's computed output, such as a maths node's result. Wire that output into the parameter, then reference it by name in the formula.

A reference that would create a cycle is rejected. If node A already depends on node B, B cannot reference A back.

The value token

Inside a parameter formula, value means this parameter's own current value, whatever it would be from its keyframes or hand-set number. A formula can therefore build on top of animation rather than replacing it.

= value + sin($T) * 2     # add a wobble on top of a keyframed value
= value * 1.5             # scale whatever's already there

On a dropdown (menu) parameter, value is the current option's position in the list, so = value + 1 advances to the next option. Referencing another node's dropdown reads it as a number the same way.

Per-axis formulas

A position, scale or colour has several axes, and each carries its own formula. Drive the X of a position with a formula while Y and Z stay hand-set.

When the Expression node is the right tool instead

Inline parameter formulas work on one value at a time. Writing @P or @Cd into one is rejected outright, with an error naming the attribute and pointing you here. Fields and textures cannot be sampled, and $PTNUM and $NUMPT read 0 rather than failing, which is the quieter version of the same limit. To drive every point of a collection differently, use the Expression node, which runs the formula across the whole thing.

See also