Scripting

The Scripting panel holds functions of your own, saved with the show. If you keep writing the same idea into lanes and effects, give it a name once and call it everywhere. Change the function, and every formula using it changes too.

Add the panel with the layout button in the header: split a panel and choose Scripting. See Screen layouts.

Write a function

A function is a name, its parameters, =, and a formula, ending in a semicolon:

// A wave crossing the group: beats per cycle, and cycles across it.
wave(beats, across) = sine(beat / beats - x * across);

// A hit on every beat that fades at this rate.
hit(rate) = decay(beat, rate);

// Between two levels, slowly.
swell(low, high) = mix(low, high, sine(beat / 8));

Lines starting with // are comments; one directly above a function becomes its description when the formula editor offers it. Press Apply (⌘Enter) to save the script, which is one undo step. Until then nothing changes, so a half-written function can't break anything, and mistakes are underlined as you type.

Then call a function in any lane or effect formula, like a built-in one:

wave(4, 1) * energy
max(hit(6), swell(0.2, 0.6))

What a function can do

A body is one formula. It can read its parameters, the built-in variables such as beat and x, your variables, and call built-in functions and any function above it in the script. A function can't call itself or one further down, which is what keeps every formula quick to run. Parameters can be numbers or colors.

A call costs what the formula would cost written out in place. Each call also has its own smooth and delay memory, so slow(level) - slow(bass) keeps two separate histories.

Function names can't be ones the formula language already uses, or a variable's. A function a formula still calls can't be removed or renamed; change the formula first. If a change to a function's body would break a formula that calls it, Apply says where and keeps the script as it was.