Collections#

A Collection Signal produces multiple values for iteration, aggregation, or selection. Collections contain values, game objects, or scriptable objects, and a field offers only sources with a compatible element type.

How a collection is used#

A Collection Signal produces its entries when an operation reads it. It doesn't keep a stored list between reads, which has two consequences:

Each read evaluates the source again. A physics collection reruns its query each time, so it reflects the current scene.
Repeated reads repeat the evaluation cost. An On Update Event that reads a physics overlap collection can run the query every frame.

Capture expensive collections

When a sequence reads the same collection more than once, evaluate it once and store the result in a variable. Later reads use the stored entries instead of rerunning the source query.

Collections of values#

Value collections produce entries from variables, typed lists, ranges, or text:

Source	Produces
Variables	Every entry in a variable container.
Variables with Tag	The first value of every container holding that tag.
Numbers	A list you type in.
Number Range	A sequence between two bounds.
Strings	A list of text you type in.
String Characters	Each character of a piece of text.
String Split	The pieces of text separated by a delimiter.

To repeat an operation ten times, use Foreach with a Number Range from 0 to 9.

Collections of game objects#

Game Object collections gather scene objects from hierarchy, tags, components, variables, or physics queries.

Source	Produces
Transform Children	Every child of an object.
Scene Root	Every root object in a scene.
With Tag	Every object carrying a tag.
With Component	Every object with a given component.
Variables	The objects held in a variable.
Variables with Tag	The first object of every container holding that tag.

Physics queries#

Physics collections gather objects that overlap a shape or intersect a ray:

Source	Produces
Overlap Sphere 3D	Everything inside a sphere.
Overlap Box 3D	Everything inside a box.
Overlap Capsule 3D	Everything inside a capsule.
Raycast 3D	Everything a ray passes through.
Overlap Circle 2D	Everything inside a circle.
Overlap Box 2D	Everything inside a box.
Overlap Capsule 2D	Everything inside a capsule.
Overlap Point 2D	Everything at a point.
Raycast 2D	Everything a ray passes through.

Layer masks restrict each query to the relevant physics layers.

A sphere query finds every enemy in range

Add a Foreach with an Overlap Sphere 3D collection.
Center the sphere on Source and filter it to the enemy layer.
Add the ability's Instructions inside the loop and point them at Target.

Each loop iteration applies the ability to one enemy returned by the sphere query.

Transforming collections#

These sources combine or transform other collections:

Source	Produces
Filter	Only the entries passing a set of Conditions.
Sort by Distance	The same entries, ordered by proximity to a point.
Concatenate	Two collections joined into one.
Empty	Nothing. Useful as a default.

You can nest these sources. To gather nearby enemies with low health in distance order, filter a distance-sorted overlap collection.

Inside a Foreach#

Each pass of a Foreach makes three values available to everything nested inside:

Parameter	Is
Item	The current entry, typed to match the collection.
Index	Its position, starting at `0`.
Count	The total number of entries.

When the item is a game object or a component, Foreach also sets Target to it for that pass. The previous Target is restored when the loop ends.

Aggregating#

Number Signals can reduce a collection to a single value: Count, Sum, Average, Minimum, Maximum and Random.

Use these Signals to calculate total damage across several hits, an average distance, or the number of enemies still standing without adding a Foreach.

Where to go next#

Control flow — iterate a collection with Foreach.
Game Object Signals — select one object from a collection.
Variables as lists — build and modify a stored collection.