Spread
Spread an offset across a set's elements, shaped by an ordering, a distribution pattern, and an easing curve. Operates on the ordinal axis (which element, in what order) over collections, number, vector, colour and integer arrays, scalars, and lists; Range, Curve, and Gradient remap the magnitude axis.
What it does
Spread offsets the elements of a set one at a time, staggered by their order rather than by distance from something. Give it an ordering attribute (index, normalised position, or a custom one), pick how that order is reshuffled (sequential, reversed, from the centre out, random, zigzag) and shape the ramp with an easing curve. The result drives a position offset per element, and can also drive a frame delay or a named custom attribute.
This is the ordinal-axis tool: it answers which element, in what order, which is a different job from magnitude remappers like Range, Curve or Gradient. Spread works on Collections directly, and on NumberArray, Vec3Array, ColorArray, IntArray, single numbers, vectors and colours, and Lists. For non-Collection inputs the ordering comes from each element's position in the array.
When to use it
A cascading animation where each element starts a beat after the last: raise Time Offset and wire the frame delay downstream.
A staggered layout: a row of shapes fanning out, rippling or zigzagging from their base positions.
A reusable 0–1 ramp shaped by distribution and easing, to drive colour, opacity or any other attribute: take the Weight output instead of the offset position and wire it into a Gradient or Channel node.
The shape of a stagger (From Center, Random, Zigzag, Steps) mattering more than a specific offset amount: tune Distribution and Easing before Strength.
| Parameter | Type | Default |
|---|---|---|
input | Any | — |
ordering | String | "u" |
distribution | String | "Sequential" |
easing | OneOf([Curve]) | Curve(Easing(BezierSpline { points: [... |
strength | Number | 1 |
seed | Number | 42 |
offset | Number | 0 |
vec3_offset | OneOf([Vec3, Vec3Array]) | — |
color_offset | OneOf([Color, ColorArray]) | — |
rotation_offset | OneOf([Vec3, Vec3Array]) | — |
scale_offset | OneOf([Vec3, Vec3Array, Number]) | — |
time_offset | Number | 0 |
custom_attribute | String | "" |
custom_offset | Number | 0 |
Gotchas
Step Count appears only when Easing is set to Steps, and Seed only when Distribution is set to Random. Controls that do not apply are hidden rather than left inert.
Custom Attribute needs both a name and a non-zero Custom Offset. An empty name or a zero offset leaves that attribute untouched, and it is Collection mode only.
Weight is populated for a Collection input only. Fed a NumberArray, Vec3Array, or a single number, colour or vector, Weight comes back as an empty array: the ordinal ramp is meaningful only across a set of elements.
Worked example
Add a Spread node and feed it a Collection of instances.
Set Ordering to
@index, or a custom attribute written earlier, and pick a Distribution. From Center moves the outer elements first.Raise Strength and wire a value into Vec3 Offset to fan the elements out from their base positions.
Switch Easing to Steps and raise Step Count for a chunky, quantised stagger instead of a smooth ramp.
For an animation cascade, raise Time Offset. It writes
@time_offsetper element, ready to feed an Iterator's time input.
See also
Displace · Warp · Channel · Collections