# 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.

!!! tip "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.

!!! example "A sphere query finds every enemy in range"
    1. Add a **Foreach** with an **Overlap Sphere 3D** collection.
    2. Center the sphere on **Source** and filter it to the enemy layer.
    3. 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](../events/control-flow.md)** — iterate a collection with **Foreach**.
- **[Game Object Signals](game-objects.md)** — select one object from a collection.
- **[Variables as lists](../variables/lists.md)** — build and modify a stored collection.