Home > Lists & collections

< Previous: View menu (Nodes) | Next: Constants & unit conversions >

How the node graph carries lists, and the nodes that gather, count, and index them.

Wires don't only carry single things - they carry lists. A list might be a set of points, a batch of curves, or a group of tiles. Understanding how lists move through the node graph is what lets one small recipe generate a whole pattern.

When a list flows into a node, the node applies to every item in it. Rotate a list of tiles and each tile rotates; offset a list of regions and each region offsets. You don't loop or repeat anything by hand - placing the operation once is enough, because the list flows through it.

The visual cue is the fat wire: whenever a connection carries more than one item it's drawn thick, so you can see at a glance where a list is moving. See How the node graph works for the socket and wire basics.

The three list nodes together: Collect bundles separate feeds into one list, then Item at Index pulls one item back out and List Length counts them.

A list travels on a thick wire. Many node inputs are now list-aware: instead of taking one value, they map over a list, running once for each item in it.

  Series is the source of a bare number list - a run of numbers on one wire. Math maps its operation over a list: a list against a scalar broadcasts - the single value applies to every element - while two lists pair up index-for-index, matching element 0 to element 0, element 1 to element 1, and so on, down to the length of the shorter list.

The per-item inputs across the transforms and shapes are list-aware too. Rotate, Scale, and Offset's amount; Place and PlaceVariant's Rotation, Scale, and Index; Circle: Center Radius's Radius; Rectangle: Directed's Width - each now accepts a list just as readily as a single number or a field. Feed a list of radii into a circle and you get a circle per radius; feed a list of angles into a rotation and each copy turns by its own amount.

It's worth contrasting a list with a field. A field - sampled from an image - is read by position in space: move an object and it picks up whatever the field holds there. A list is read by item order: the third item gets the third value, wherever it sits. Both let one input drive many outputs - one is position-driven, the other index-driven.

The panel readouts name what a wire is carrying: a number list reads values | N, a point list reads points | N - the count N tells you how many items are on the wire at a glance.

Collect gathers several inputs into one list. It starts with a single item socket and grows a fresh one each time you fill the last, so you can keep adding as many feeds as you need. Collect keeps each input's items separate - it doesn't fuse or weld them together - it just bundles them into one list to carry downstream.

Item at Index pulls a single item back out of a list. Give it the list and an index number and it returns just that one item. Indexes are 0-based - the first item is 0 - matching the numbered badges shown on screen. A negative index counts from the end, so -1 is the last item, and an index past the end returns nothing.

List Length counts the items in a list and outputs the number. It counts the same way everything else does - each region, curve, point, or ray is one item. Feed the count into a Random node to pick among that many variants, or into an array to match a count automatically.

Because the count is a live number, it tracks the list: add or remove an item upstream and everything driven by List Length adjusts on its own.

Once a list is flowing, a small family of nodes lets you choose which items to keep and what order they're in - without ever unpacking the list by hand.

Keep some, drop the rest (each has a live Unselected output, so nothing is lost):

• Select Every Nth: thin the list by a fixed step (every 2nd, every 3rd...).
• Select Range: take a contiguous block, from Start to Start + Count.
• Select by Pattern: select by a text mask (110, FTF) or an index list (0,2,5), fed from a Text node.
• Select by Area: keep regions whose area falls in a range.

Reorder the whole list:

• Reverse: flip it end-for-end.
• Shift: rotate the order, wrapping around, to re-phase a pattern.
• Sort: order by a measured key: Area, X, Y, Radius, or Angle.

These compose: Sort by Area, then Select Range Start 0, Count 3, and you've kept the three largest items - no loop, no manual indexing.

Loose points inside a group travel with the member they belong to, not as items of their own. A group of four tiles, each holding its own corner points, reads as four items rather than twenty, so List Length, Item at Index and the variant nodes all see the tiles.

Sometimes an item is itself made of several parts - a tile built from several regions. A collection holds those whole tiles as its members rather than scattering everything into loose regions, and a group can itself hold a group, as deep as you build it. There is no fixed limit.

This matters when your members are compound shapes. With nesting, List Length counts the tiles (not their inner regions), Item at Index hands you a whole tile intact, and a scatter keeps each tile's regions together as it places them. A flat, single-region collection behaves exactly as before.

Nesting is a structure, not a cage: Flatten takes it off again. Its Levels input is how far down to go, counting from the outside in, and 0 means all the way. So a collection of tiles flattened one level gives you the tiles' parts as items, while the parts that were themselves groups stay grouped.

< Previous: View menu (Nodes) | Next: Constants & unit conversions >