Iterator

Export

Iterator is a specialized Action State that runs its contained Actions once for each value in a list. Use it when one state should apply the same behavior to several targets or data values without duplicating the Actions.

Iterator is added as a State in the graph. It is not an Action added inside a regular Action State.

Set up an Iterator

  1. Add an Iterator State to the graph.
  2. Assign the source List.
  3. Assign a compatible Shared Variable to Element. Iterator writes the current list value to this variable before the contained Actions run.
  4. Assign Current Index when the Actions or transitions also need the zero-based list position.
  5. Set Start Index to the first list position that should be processed.
  6. Leave Entire List enabled to process every remaining value in one update when the Actions can finish immediately. Disable it and set Iterations Per Update to spread the work across updates.
  7. Add the Actions that should run for each value, then connect the Iterator’s outgoing transitions.

The Element and Current Index fields require Shared Variables so the contained Actions and outgoing Conditions can read their current values.

Watch the Lists and Iterators tutorial on YouTube.

How it runs

When the State starts, Iterator begins at Start Index. A negative value is treated as 0. For each available list value, Iterator performs this sequence:

  1. Writes the value to Element and its position to Current Index.
  2. Runs the contained Actions using the configured Sequence or Parallel execution type.
  3. Waits on the same value while any contained Action is still running.
  4. Restarts the contained Actions for the next value after the current pass finishes.

The Iterator finishes after the last available value. It also finishes without running the Actions when the list is missing, the list value is invalid, or Start Index is beyond the end of the list.

With Entire List enabled, Iterator completes as many values as possible during the current update. An Action that returns Running still pauses progress until a later update. With Entire List disabled, Iterations Per Update limits the number of completed values per update; values below 1 are treated as 1.

Choose transition timing

  • Continuous can interrupt the Iterator while its Actions are running.
  • On Iteration Complete evaluates after the Actions finish for the current list value. Use it when a Condition should inspect Element or Current Index before iteration continues.
  • On State Finished evaluates after the Iterator reaches the end of the list.

For example, an Iterator can examine a list of detected targets. Its Actions can score the current Element, while an On Iteration Complete transition can leave the State as soon as the current target satisfies the selection rule.

Verify the Iterator

Use a list with at least three known values and log Element and Current Index from a contained Action. Confirm that:

  • iteration begins at the configured Start Index;
  • each processed value and index match;
  • disabling Entire List limits completed values per update;
  • the intended transition timing either checks each value or waits for the complete list.