Scripting API

The node library as functions inside the JavaScript node. Generate, filter, and blend images in code.

Inside a JavaScript node, magerie.generators and magerie.ops put the node library at your fingertips as plain functions. Anything you can wire up as nodes, you can also write as a line of code:

//@output image out

let { noise } = magerie.generators
let { mul, blur } = magerie.ops

let a = noise("voronoi", 234234)
let b = noise("simplex", { scale: 2.4 })
out.value = blur(mul(a, b), 4)

Results are images. Pass them to other ops, assign one to an image output to feed the graph, or ctx.drawImage(img, x, y) it inside a draw recipe. The editor autocompletes every function with its full signature and options.

Calling ops#

Every function follows one convention:

1. Images first. Filters take one (blur(img, ...)), blends and warps take two (mul(a, b)).
2. A kind string, when the op has modes: noise("voronoi"), blend(a, b, "screen"), invert(img, "g").
3. A primary number: the seed for noise, radius for blur, opacity for blends, gamma for levels.
4. An options object for everything else: noise("voronoi", 7, { scale: 4, octaves: 6 }). Options are validated: unknown names and bad enum values throw with the valid choices listed, numbers clamp to their slider ranges.

Ops with a -> { ... } in their signature produce several images at once. Destructure the result: let { r, g, b } = channelSplit(img). Each member is a normal image you can pass along or dispose() independently.

Calls are cached per node: the same call with the same inputs reuses its texture instead of re-rendering, so calling ops inside a per-frame draw recipe is free as long as the parameters hold still. Everything a script creates is freed automatically the next time the node runs.

Errors land on the node itself: a typo like noise({ sclae: 2 }) shows the message on the node's error strip when you press Run.

magerie.generators#

noise(type?, seed?, opts?)#

Generates procedural noise textures using various algorithms

gradient(type?, opts?)#

Generates color gradients in various styles

solidColor(color?, opts?)#

Generates a solid color fill

sdfShape(shape?, size?, opts?)#

Generates signed distance field shapes with configurable geometry and colors as a colored image

pattern(type?, scale?, opts?)#

Generates procedural patterns like checkerboard, stripes, dots, and grid

scatter(stamp, layout?, count?, opts?) -> { image, id }#

Stamps copies of an input image across the output (random or grid layout), with per-instance random scale / rotation / opacity. Also emits a per-instance ID map for downstream variation.

magerie.ops#

blend(a, b, mode?, opacity?, opts?)#

Combines two images using various blend modes

mul(a, b, opacity?, opts?)#

Blend a and b with mode "multiply" (fixed: mode="multiply")

add(a, b, opacity?, opts?)#

Blend a and b with mode "add" (fixed: mode="add")

sub(a, b, opacity?, opts?)#

Blend a and b with mode "subtract" (fixed: mode="subtract")

screen(a, b, opacity?, opts?)#

Blend a and b with mode "screen" (fixed: mode="screen")

overlay(a, b, opacity?, opts?)#

Blend a and b with mode "overlay" (fixed: mode="overlay")

darken(a, b, opacity?, opts?)#

Blend a and b with mode "darken" (fixed: mode="darken")

lighten(a, b, opacity?, opts?)#

Blend a and b with mode "lighten" (fixed: mode="lighten")

difference(a, b, opacity?, opts?)#

Blend a and b with mode "difference" (fixed: mode="difference")

blur(img, radius?, opts?)#

Applies Gaussian blur to soften an image

levels(img, gamma?, opts?)#

Adjusts input/output black and white points with gamma correction

colorAdjust(img, opts?)#

Adjusts brightness and contrast (legacy hue/saturation in the collapsed group; prefer HSL Adjust for those)

sharpen(img, amount?, opts?)#

Enhances edge detail using unsharp mask

transform(img, opts?)#

Applies geometric transformations to an image

invert(img, channels?, opts?)#

Inverts image colors to create a negative

threshold(img, threshold?, opts?)#

Converts image to black and white based on brightness threshold

gradientMap(img, opts?)#

Remaps image luminance to a user-defined color gradient

hslAdjust(img, hue?, opts?)#

Adjusts hue, saturation, and lightness with optional per-hue targeting

tile(img, repeatX?, opts?)#

Tiles/repeats an image across the output

crop(img, opts?)#

Crops image to a rectangular sub-region

warp(src, displacement, strength?, opts?)#

Displaces pixels using a displacement map

mask(img, mask, opts?)#

Uses a grayscale mask to modulate the alpha channel

channelSplit(img) -> { r, g, b, a }#

Splits an image into its R, G, B, A channels as separate grayscale images

colorSpaceDecompose(img, colorSpace?, opts?) -> { c1, c2, c3, a }#

Splits an image into channels of HSL, HSV, LAB, or OKLCH color spaces

magerie.anim#

Pure motion helpers for scripted animation. Every function is a pure function of the stepped clock, so an Image to Video bake reproduces Play exactly (no Math.random / Date.now). Read the clock from a draw recipe's time argument.

ease.<curve>(t)#

Easing curves, each mapping a clamped 0..1 progress to an eased value: linear, inQuad, outQuad, inOutQuad, inCubic, outCubic, inOutCubic, outBack, outElastic (the last two overshoot within a bounded range).

const p = magerie.anim.ease.outCubic(time / 0.5)   // ease in over the first 0.5s

envelope(t, { fadeIn?, fadeOut?, duration }) -> 0..1#

An opacity ramp: fades up from 0 over fadeIn seconds, holds at 1, then fades back to 0 over the last fadeOut seconds ending at duration. fadeIn and fadeOut default to 0 (no ramp on that side).

shake(t, { freq?, amp?, seed? }) -> { x, y }#

Deterministic 2D jitter: per axis, the mean of three seeded, incommensurate sinusoids. Bounded by amp (default 1); freq sets the rate (default 15); distinct seeds stay out of phase so parallel shakes do not sync.

typewriter(text, t, { cps?, delay? }) -> string#

The leading substring of text visible at time t, revealing cps characters per second (default 20) after delay seconds (default 0).

spring(t, { frequency?, damping? }) -> number#

Analytic damped-spring step response: 0 at t <= 0, settling at 1. damping (default 0.55) below 1 overshoots and rings (bouncy entrances); 1 or above is critically damped (no overshoot). frequency (default 3) sets the oscillation rate in Hz. Closed-form, so it is a pure function of t.

const p = magerie.anim.spring(time - 0.2, { frequency: 2.2, damping: 0.5 })
ctx.fillRect(40, 240, 420 * Math.max(0, p), 90)   // panel boings open at t=0.2

stagger(t, index, { each?, duration?, delay?, ease? }) -> 0..1#

Eased progress of item index in a staggered sequence: item i starts at delay + i * each (each default 0.06) and animates over duration (default 0.35) with ease (a curve name like "outBack", default "outCubic", or a custom (t) => number). THE primitive for per-char / per-word / per-line reveals - pair it with magerie.text.layout slot indices.

cycle(t, { period, mode? }) -> 0..1#

Normalized phase of a repeating cycle: "loop" (sawtooth, default), "pingpong" (triangle 0->1->0), "sine" (smooth 0->1->0). For pulsing underlines, looping accents, breathing panels.

cueAt(t, cues) -> { index, progress }#

The active cue at time t from an array of { start, end, ... } spans: index into the array (-1 when no cue covers t - gaps count) and progress 0..1 inside the cue. The karaoke primitive: highlight word cues[index] while drawing all words.

spreadCues(text, { start?, duration, by? }) -> [{ start, end, text }]#

Split text into word (default) or char cues spread across duration seconds from start, each unit's share proportional to its character count (longer words hold longer). Word indices line up with magerie.text.layout(..., { by: "word" }) slot indices, so cueAt(...).index maps straight onto layout slots. For real speech timing, pass hand-timed cues to cueAt instead.

magerie.text#

Measurement/layout helpers for text effects. Positions are computed with the ctx's CURRENT font - set ctx.font before calling. Per-unit widths ignore kerning between neighbours (each unit measured alone); use letterSpacing to tune rhythm.

layout(ctx, text, { x, y, by?, align?, letterSpacing?, wordSpacing?, maxWidth?, lineHeight? }) -> slots#

Measures and places each char (by: "char", default) or word (by: "word") of text, returning { text, x, y, width, index, line } slots. Explicit \n breaks lines and maxWidth word-wraps (an over-wide single word keeps its own line; wrapping collapses runs of spaces). x,y anchor the FIRST line's baseline per align ("left" default, "center", "right", applied per line); further lines step by lineHeight (default 1.25x the px size parsed from ctx.font). Whitespace advances the cursor but produces no slot, so index is contiguous across the whole block and feeds anim.stagger / anim.cueAt directly; use line to stagger line-by-line (anim.stagger(t, slot.line, { each: 0.25 })). Draw a slot with ctx.fillText(slot.text, slot.x + dx, slot.y + dy).

ctx.font = "bold 56px sans-serif"
const slots = magerie.text.layout(ctx, "HELLO WORLD", { x: out.width / 2, y: 200, align: "center" })
for (const s of slots) {
    const p = magerie.anim.stagger(time, s.index, { each: 0.05, duration: 0.4, ease: "outBack" })
    ctx.globalAlpha = p
    ctx.fillText(s.text, s.x, s.y + 24 * (1 - p))   // rise-in, char by char
}
ctx.globalAlpha = 1

Next#

• Code Nodes: the JavaScript node's execution model, directives, and draw recipes