Process list actions are just like command actions, but they act on one entity at a time from a collection. Process list actions can be used either to select one or more entities from a collection and act only on those, or to act on every member of a collection in some way.

Like all actions, process list actions come with predefined references to the parent (owning entity) and the invoker (entity that owns the trigger). Process list actions also come with a third reference, to the current entity being processed. The name of the reference is always the name of the entity type being processed with the prefix "ref". So if your action is acting on a collection of gazelles, the reference called "refGazelle" points to whichever particular gazelle is being acted on at the moment.

To create a process list action, create a new action,

and choose "Process List" as the Kind.

Next, name the collection whose members your action will act upon. This can be a named full collection, as shown here, or it can be a reference to a subcollection.

The "filter" field determines which members of the collection are included for processing. As shown, the action will only apply to gazelles weighing more than 200 pounds*. To process all members of the collection, enter true in the filter field.  

Next, choose the order in which the entities will be processed. As shown here, the list of gazelles is sorted by weight, descending from heaviest to lightest. Thus the heaviest gazelle will be sorted first, the next heaviest second, and so on, down to the lightest gazelle that still meets the filter condition. Process list actions currently sort collections only by variables' value (so, numerical values), not attributes or other properties. So you can sort by weight, but not alphabetically by (say) color. You may, however, put any numerical expression you wish in the sort field, as long as it produces a value for each entity in the collection. You can sort, for example, on the function Random() to process the entities in random order.

Process list actions do not have to process all the entities that meet the filter condition. The Process While field is used to determine when the action should stop processing entities. Here, the action will continue while the parent (a Lion entity) weighs less than 400 pounds. If the lion entity who owns this action should gain enough weight to cross 400 pounds (perhaps by eating gazelles, one at a time), then the action will stop. If you wish for an action to process every entity in a collection that meets the filter condition, enter true in the Process While field.

Finally, the description is a place to enter any explanatory notes or comments about the action.

_____________

* or whatever weight units are used in the definition of the Weight variable of the Gazelle entity.

Process list actions can do commands on members of the target collection, the parent or the invoker, or entities connected by references to any of those.

WARNING:

Process List actions can be nested using triggers to invoke other process list actions.   If the lists are long, this may severely degrade model execution time.