> 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/abilities.md).

# Abilities

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

Abilities are reusable gameplay actions. An ability asset defines authoring data; a runtime object runs logic; an ability spec stores the actor's granted instance, level, input binding, activation state, and runtime instances.

![Practical ability lifecycle diagram showing activation checks, commit, active state, finish, and cancel paths.](/files/BXklKqeWQh2BaGVPBo06)

## What It Does

| Layer             | Type                | Responsibility                                                                                       |
| ----------------- | ------------------- | ---------------------------------------------------------------------------------------------------- |
| Definition        | `AbilityDefinition` | Serialized authoring data: title, icon, tags, costs, cooldown, triggers, effects, instancing policy. |
| Runtime           | `AbilityRuntime`    | Activation logic, commit, task use, cancellation, event handling.                                    |
| Spec              | `AbilitySpec`       | Per-actor grant: definition, level, input binding, active state, runtime instance references.        |
| Runtime subsystem | `RuntimeAbilities`  | Grants, activates, cancels, removes, ticks, triggers, and indexes abilities.                         |

## When To Use It

Use an ability when the action:

* Can be granted or removed from an actor.
* Has activation rules.
* Has costs or cooldowns.
* Applies effects.
* Waits for input, time, target data, animation, or events.
* Needs cancellation or active lifetime.

For one-off passive stat changes, use an effect directly instead of an ability.

## Editor Setup

Create an ability script or asset:

1. Open `Tools > Gameplay Ability Toolkit > Dashboard`.
2. Select `Abilities`.
3. Use the ability creation panel, or right-click the Project window.
4. Choose `Assets > Create > Gameplay Ability Toolkit > Ability Script...` for a new C# definition/runtime pair.
5. After scripts compile, create the ability asset from its `[CreateAssetMenu]` path.
6. Configure title, icon, levels, tags, cost, cooldown, effects, and triggers.
7. Grant the asset through the actor setup, tutorial bootstrap, demo content, or code.
8. Bind logical input through `AbilityInputBindingSet` if the ability should activate from input.

![Unity Editor screenshot of the Dashboard Abilities page.](/files/IJvKLtJvOgsB4ZUPJ5cI)

![Unity Editor screenshot of the Create Ability Asset picker.](/files/wh1RKiz6z5yI3cP5Nc68)

## Configuration Fields

| Field                          | Meaning                                                                                         |
| ------------------------------ | ----------------------------------------------------------------------------------------------- |
| `Title`, `Description`, `Icon` | UI-facing display metadata.                                                                     |
| `Priority`                     | Sort/selection priority, especially when activating by tags.                                    |
| `InitialLevel`, `MaxLevel`     | Default grant level and upper bound.                                                            |
| `InstancingPolicy`             | Runtime object lifetime.                                                                        |
| `CommitPolicy`                 | Whether cost/cooldown commit happens automatically on activation or explicitly in runtime code. |
| `AbilityTriggers`              | Gameplay event or owned tag triggers.                                                           |
| `Costs` / `CostEffect`         | Attribute costs. Inspector can sync a cost effect asset.                                        |
| `Cooldowns`                    | Level-based cooldown duration.                                                                  |
| `Effects`                      | Effects applied by the ability runtime when it chooses to apply them.                           |
| `AbilityTags`                  | Identity tags used for selection, cancellation, and blocking.                                   |
| `CancelAbilitiesWithTags`      | Active abilities with matching tags are cancelled when this ability activates.                  |
| `BlockAbilitiesWithTags`       | Other abilities with matching tags are blocked while this ability is active.                    |
| `ActivationOwnedTags`          | Tags granted to the owner while this ability is active.                                         |
| Required/blocked tag fields    | Activation gates for owner, source, and target.                                                 |
| Required queries               | Structured tag query gates.                                                                     |

## Instancing Policy

| Policy                  | Use when                                                              | Avoid when                                                    |
| ----------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------- |
| `NonInstanced`          | Runtime has no mutable state and no async lifetime.                   | Ability uses tasks, timers, target data, or per-actor fields. |
| `InstancedPerActor`     | Most abilities. Runtime state belongs to one actor and can be reused. | Multiple overlapping activations need isolated state.         |
| `InstancedPerExecution` | Complex multi-phase or overlapping activations.                       | Ability is simple and frequent, to avoid extra allocations.   |

## Runtime Flow

```mermaid
flowchart TD
    Grant["RuntimeAbilities.AddAbility"] --> Spec["Create AbilitySpec"]
    InputOrEvent["Input, code, tag trigger, or gameplay event"] --> Check["CanActivateAbility"]
    Spec --> Check
    Check -->|fail| Failure["EventActivationFailed"]
    Check -->|pass| Runtime["Get or create AbilityRuntime"]
    Runtime --> Commit["Commit cost and cooldown"]
    Commit --> Active["Spec becomes active"]
    Active --> Tasks["Tasks, effects, target data, montage"]
    Tasks --> End["EndAbility or CancelAbility"]
    End --> Cleanup["Remove activation tags, dispose execution runtime, notify ended"]
```

## Practical Usage Patterns

Grant and activate by definition:

```csharp
asc.RuntimeAbilities.AddAbility(abilityDefinition, level: 1);
asc.RuntimeAbilities.TryActivateByDefinition(abilityDefinition);
```

Activate by tags:

```csharp
var tags = new GameplayTagContainer(new GameplayTag("Ability.Fireball"));
asc.RuntimeAbilities.TryActivateByTags(tags);
```

Cancel by tags:

```csharp
asc.RuntimeAbilities.CancelWithTags(cancelTags);
```

## Debugging Checklist

* If activation fails, inspect ASC `Events` and `AbilityFailureReason`.
* If cost fails, confirm the target attributes exist and have enough current value.
* If cooldown fails, inspect active effects and cooldown tags/effects.
* If trigger does not fire, confirm the trigger tag exactly matches the event or owned tag change.
* If input press is visible but ability does not activate, confirm `ActivateOnInputPressed` on the input binding.
* If cancellation leaves effects behind, confirm runtime cleanup calls the appropriate end/cancel path.

## Common Mistakes

| Mistake                                      | Result                        | Fix                                                 |
| -------------------------------------------- | ----------------------------- | --------------------------------------------------- |
| Storing actor state on the definition asset  | State is shared across actors | Store state on runtime/spec.                        |
| Using `NonInstanced` with async tasks        | State collisions              | Use `InstancedPerActor` or `InstancedPerExecution`. |
| Forgetting to commit explicit abilities      | No cost/cooldown              | Call commit in runtime code or use auto commit.     |
| Blocking with the same tag used for identity | Self-blocking reactivation    | Review `AbilityTags` and `BlockAbilitiesWithTags`.  |

## Extension Points

* Subclass `AbilityDefinition` and return a custom `AbilityRuntime`.
* Use `AbilityTask` subclasses for async steps.
* Use target collectors for targeting flows.
* Use montage tasks for animation-driven abilities.
* Use gameplay events for external triggers.

## Examples and Tests

* Tutorial: [How To Add an Ability](/docs/gameplay-ability-toolkit/tutorial-details/howtoaddability.md).
* Arena Demo: melee, dodge, projectile, channel, and ground target abilities.
* Tests: `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Abilities/AbilityLifecycleContractTests.cs`, `AbilityGrantActivationDeepTests.cs`, `AbilityDeepContractTests.cs`, `RuntimeAbilitiesActivationEventTests.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/abilities.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.