Overview

Nubu Motion scripts are small JavaScript programs that compute property values every frame. Where keyframes record motion by hand, a script DESCRIBES motion as a rule: follow that layer, drift gently, count down, fade with distance. The rule stays live - retime a keyframe, rename a layer, scrub a control, and everything driven by the rule follows along.

One surface: the Scripts panel#

Scripts live in ONE place: the Scripts destination in the editor's left rail. The panel lists every script in the project with a per-script enable toggle and an evaluated status chip; opening a script raises the floating IDE with completions, live evaluation, lint and the @ pick whip. There are no per-property expression boxes to hunt through: a script declares the properties it drives in its outputs list, and the timeline marks each driven property row with a small read-only indicator naming the script.

A script is a tiny module:

export const outputs = ["layer_1:transform.position"];

export function frame() {
  return [value[0] + wiggle(0.8, 24), value[1]];
}

The engine calls frame() once for every frame it shows. A script with one output simply returns the value; a script driving several properties calls set(target, value) for each. Everything a script can see - the clock, the comp, layers, properties, expression controls - is documented in the General and Objects chapters, and every member's page carries a worked example you can rebuild.

The controller pattern#

The most useful shape to learn early: put expression controls (sliders, checkboxes, colours, points, dropdowns, angles) on a layer - conventionally a null named after its job, like Rig - and let a script read them:

export const outputs = ["layer_2:transform.opacity"];

export function frame() {
  return control("Show planet").value ? 100 : 0;
}

The control is the surface people touch; the script is the wiring underneath. Controls can be keyframed, exposed as Dynamic Fields and driven by templates and flows, so one honest switch on a rig can steer arbitrarily rich behaviour in the scene - and the same pattern travels inside library components, whose embedded scripts read the component's own controls per instance.

What the editor shows is what the farm renders#

There is exactly ONE script runtime, embedded in the editor and in the render farm alike, with the same budgets and the same seeded randomness. A frame you scrub in the editor is the frame the farm renders - deterministically, on every machine. Scripts cannot reach the network, the file system or the clock; a runaway loop is stopped by budget and reported as a typed status, never a freeze. The Determinism page explains why this holds by construction.

Where to start#

Work through the Quick start: six small scripts with their scenes spelled out, then a project script driving two comps at once. After that, References and ids explains the name-over-id model the editor uses, and Project scripts covers outputs, scheduling and the rules that keep evaluation predictable.