> For the complete documentation index, see [llms.txt](https://morningheartgames.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://morningheartgames.gitbook.io/docs/gameplay-ability-toolkit/subsystems/targeting.md).

# Targeting

> Online doc: <https://morningheartgames.gitbook.io/docs/gameplay-ability-toolkit/subsystems/targeting?fallback=true>

Targeting turns a source actor and input context into target data. Abilities use target data to apply effects, place AoEs, select enemies, or drive cues and montage events.

![Practical targeting diagram showing source, collector, filter, indicator, and target data.](/files/3qHsv2CFi8V1tAKfb1RC)

## What It Does

| Type                         | Responsibility                                                        |
| ---------------------------- | --------------------------------------------------------------------- |
| `TargetData`                 | Base target payload.                                                  |
| `TargetData_GameObjects`     | GameObject target list and source location.                           |
| `TargetCollector`            | Base component for async target acquisition.                          |
| `GeneralTargetCollector`     | Lock-on and soft-lock target selection.                               |
| `GroundPointTargetCollector` | Ground point and radius selection.                                    |
| `MultiTargetCollector`       | Shape trace collection.                                               |
| `TargetDataFilter`           | Base filter.                                                          |
| `TargetDataFilterGroup`      | AND/OR grouped filters.                                               |
| `TraceShape`                 | ScriptableObject trace definitions: sphere, box, capsule, line, cone. |
| `TargetIndicatorBase`        | Runtime target indicator base.                                        |

## When To Use It

Use targeting when an ability needs one of these:

* Confirmed enemy target.
* Ground location for AoE.
* Multi-hit trace volume.
* Lock-on/soft-lock behavior.
* Indicator before confirmation.
* Filtered targets by layer, tag, team, or self.

## Editor Setup

1. Create or choose a target collector prefab.
2. Add a collector component such as `GroundPointTargetCollector`, `MultiTargetCollector`, or a custom `GeneralTargetCollector` subclass.
3. Configure source, range, layer mask, indicator prefab, trace shape, and filters.
4. Assign the collector prefab to an ability asset or runtime field.
5. In the ability runtime, start `AbilityTask_WaitForTargetData`.
6. Bind `TargetConfirm` and `TargetCancel` in the input library and input source.
7. Test in Play Mode with the ASC `Inputs` tab visible.

Create trace shapes:

```
Assets > Create > Gameplay Ability Toolkit > Targeting > Sphere Trace
Assets > Create > Gameplay Ability Toolkit > Targeting > Box Trace
Assets > Create > Gameplay Ability Toolkit > Targeting > Capsule Trace
Assets > Create > Gameplay Ability Toolkit > Targeting > Line Trace
Assets > Create > Gameplay Ability Toolkit > Targeting > Cone Trace
```

## Configuration Fields

### General Target Collector

| Field                    | Meaning                                  |
| ------------------------ | ---------------------------------------- |
| `maxPotentialTargets`    | Non-alloc overlap buffer size.           |
| `targetLayerMask`        | Physics layer mask for candidates.       |
| `useHardLockOn`          | Hard lock mode vs soft lock mode.        |
| `maxAngle`               | Maximum selection angle.                 |
| `softLockAngle`          | Angle allowed for keeping a soft target. |
| `currentTargetIndicator` | Indicator shown on selected target.      |

### Ground Point Target Collector

| Field             | Meaning                    |
| ----------------- | -------------------------- |
| `MaxRange`        | Maximum range from source. |
| `Radius`          | AoE radius.                |
| `GroundLayer`     | Ground projection layer.   |
| `IndicatorPrefab` | Preview object.            |
| `MaxRayDistance`  | Raycast distance.          |

### Multi Target Collector

| Field                      | Meaning                          |
| -------------------------- | -------------------------------- |
| `TraceShape`               | Shape asset used for collection. |
| `TargetLayerMask`          | Physics layers.                  |
| `TriggerInteraction`       | Trigger collider policy.         |
| `MaxTargets`               | Non-alloc result capacity.       |
| `DestroyAfterConfirmation` | Whether collector self-destroys. |
| `IncludeSelf`              | Whether source can be included.  |

## Runtime Flow

```mermaid
flowchart TD
    Ability["Ability starts targeting task"] --> Collector["Spawn or use TargetCollector"]
    Collector --> Indicator["Show indicator"]
    Collector --> Confirm["Wait for confirm/cancel input"]
    Confirm --> Collect["Collect candidates"]
    Collect --> Filters["Run TargetDataFilterGroup"]
    Filters --> Data["Create TargetData"]
    Data --> AbilityContinue["Ability continues"]
    AbilityContinue --> Effects["Apply effects or cues"]
    Confirm -->|cancel| Cleanup["Hide indicator and cancel task"]
```

## Filters

| Filter                  | Use                                                 |
| ----------------------- | --------------------------------------------------- |
| `TargetDataFilter`      | Self filtering and reverse filtering base behavior. |
| `TargetDataFilterGroup` | Combine filters with AND/OR.                        |
| `EngineTagFilter`       | Unity tag filtering.                                |
| `GameplayTagFilter`     | ASC owned tag requirements.                         |
| `LayerMaskFilter`       | Unity layer filtering.                              |
| `CharacterOnlyFilter`   | Game Creator character-only targets.                |

## Debugging Checklist

* If no target is found, check physics layer masks and range first.
* If the indicator shows but confirmation does nothing, check `TargetConfirm` input binding.
* If self is included unexpectedly, inspect self filter and `IncludeSelf`.
* If GameObject targets do not pass filters, confirm they have ASCs or required Unity tags.
* If a collector works once and disappears, inspect `DestroyAfterConfirmation`.

## Common Mistakes

| Mistake                                            | Result                                 | Fix                                      |
| -------------------------------------------------- | -------------------------------------- | ---------------------------------------- |
| Filtering by gameplay tags on targets without ASCs | All targets fail                       | Add ASCs or use Unity layer/tag filters. |
| Range too small for ground ray                     | Indicator never reaches expected point | Increase max range/ray distance.         |
| Missing confirm/cancel inputs                      | Targeting task appears stuck           | Configure input library and source.      |
| Too-small non-alloc buffers                        | Targets are silently capped            | Raise max target/collider counts.        |

## Extension Points

* Subclass `TargetCollector` for custom flows.
* Subclass `GeneralTargetCollector` for game-specific input direction and lock switching.
* Implement custom `TargetDataFilter`.
* Add custom indicators by subclassing `TargetIndicatorBase`.

## Examples and Tests

* Cookbook: [Ground-Targeted AoE](/docs/gameplay-ability-toolkit/build-with-it/07-cookbook.md#ground-targeted-aoe).
* Arena Demo: target markers and target zones.
* Tests: `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Targeting/GeneralTargetCollectorTests.cs`, `MultiTargetCollectorTests.cs`, `TraceShapeTests.cs`, `TargetDataFilterGroupNullSafetyTests.cs`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://morningheartgames.gitbook.io/docs/gameplay-ability-toolkit/subsystems/targeting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.