List Map

Overview

Applies the same expression to every item in a list. For example, it transforms [1,2,3] into [2,4,6] with item * 2, processing a sequence of values all at once. Its main role is preparing numeric sequences for variants and batch processing.

Usage tips

• A typical use is transforming an evenly spaced sequence from variant_range or a similar node into a nonlinear sequence with an expression such as item * item (quadratic curve) or sin(item * pi) (arch).
• Because index / count are available, you can also create values based on item position. Use index / max(count - 1, 1) when the first item must be 0 and the last item must reach 1.
• Expressions use the same engine as expression_float. Debugging is easier if you first test the expression in a standalone expression_float node.

Related nodes

• expression_float — single-value version using the same expression engine
• list_zip / list_enumerate — merge lists or add indices before this node
• variant_range / seed_range — generate input lists
• list_create — create a list manually

Read this first

• expression is evaluated once for every item in the list.
• For list = [1, 2, 3] and expression = item * 2, this means:
  • The first item evaluates 1 * 2.
  • The second item evaluates 2 * 2.
  • The third item evaluates 3 * 2. These evaluations run in order.

Item-type names and defaults

Names derived from the current item depend on its type. item is not available for every type. When item_type changes, expression switches to the valid default below only while it still contains an automatic default. An expression you edited is kept.

With Any, a runtime Number, Color, Vec2, Vec3, or Map item exposes the names for its actual type during evaluation. The default is 0 because it remains valid for a mixed list.

The following common names are available regardless of item type.

When an item is a Map

When an item is a Map, a non-reserved key that is a valid identifier (such as value, a, or _seed) can be written directly in the expression. Every valid key is also exposed with the item_ prefix.

For example, given this item:

{ "index": 0, "value": 0.25 }

You can write these expressions directly:

value < 0.5
item_index + 1

index always means the current position in the list. Use item_index to read the Map's index key. The reserved names item, index, count, x, y, z, w, vec, vx, vy, flag, time, frame, and total_frames keep their standard meaning; use item_<key> for a Map value with one of those names. A valid identifier starts with an ASCII letter or _ and continues with ASCII letters, digits, or _; other keys are not exposed as expression variables.

How to read common inputs:

Common expressions

• item * 2
  • Doubles each number.
• item + index
  • Offsets each value by its item index.
• item * x
  • Transforms every item using a coefficient supplied from outside.
• value < 0.5
  • Reads value from a Map and produces a Bool.
• a + b
  • Adds the two values from ListZip.
• vec2(item, index)
  • Creates a Vec2 list from a numeric list.

Detailed examples

Example 1: Double numbers

Input:

[1, 2, 3]

Settings:

• item_type = Number
• output_type = Float
• expression = item * 2

Output:

list = [2.0, 4.0, 6.0]
count = 3

Example 2: Convert a Map to Bool

Input:

[
  { "index": 0, "value": 0.25 },
  { "index": 1, "value": 0.75 }
]

Settings:

• item_type = Map
• output_type = Bool
• expression = value < 0.5 && item_index == 0

Output:

list = [true, false]
count = 2

Example 3: Add the results of ListZip

Input:

[
  { "index": 0, "a": 1, "b": 10 },
  { "index": 1, "a": 2, "b": 20 }
]

Settings:

• item_type = Map
• output_type = Float
• expression = a + b

Output:

list = [11.0, 22.0]
count = 2

Example 4: Change the multiplier for all items using a variable or auxiliary input

Input:

[1, 2, 3]

Settings:

• item_type = Number
• output_type = Float
• expression = item * x
• x = 10

Output:

list = [10.0, 20.0, 30.0]
count = 3

You can enter x directly in the Inspector or connect Variable Ref to the x input pin.

When to use it

• To convert the result of a range, seed, zip, or enumerate operation into another sequence of values
• To lightly process value candidates before passing them to BatchRender

Notes

• Version 1 uses constrained expressions.
• It does not run an arbitrary subgraph for every item.
• Standard variables take priority over reserved Map keys. Read a same-named Map value through item_<key>.