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

# Gameplay Tags

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

Gameplay tags are hierarchical names used to describe state, identity, events, requirements, blockers, and cues. Tags are the main language that lets abilities, effects, targeting, and UI communicate without hard-coded boolean fields.

![Practical tag gating diagram showing tags flowing through an activation gate.](/files/w49jsoGd3UWXNyiwMQuo)

## What It Does

| Type                        | Responsibility                                                                                    |
| --------------------------- | ------------------------------------------------------------------------------------------------- |
| `GameplayTagAsset`          | Project tag catalog, metadata, deprecation, redirects, validation.                                |
| `GameplayTag`               | A single tag value.                                                                               |
| `GameplayTagContainer`      | A list/set of tags used by assets and runtime state.                                              |
| `GameplayTagQuery`          | Structured tag requirements beyond simple container matching.                                     |
| `GameplayTagCountContainer` | Counted runtime ownership. Multiple systems can add the same tag and remove only their own count. |
| `RuntimeTags`               | Actor-level tag state owned by an ASC.                                                            |

## When To Use It

Use tags for:

* Blocking activation: `State.Stunned`, `State.Silenced`.
* Required states: `Weapon.Sword.Equipped`.
* Ability identity: `Ability.Fireball`, `Ability.Dodge`.
* Status identity: `Status.Burning`, `Status.Poisoned`.
* Gameplay events: `Event.Hit`, `Event.Combo.Window`.
* Cue identifiers: `Cue.Impact.Fire`, `Cue.Status.Burning`.
* Target filtering: `Team.Enemy`, `Faction.Player`.

## Editor Setup

1. Open `Tools > Gameplay Ability Toolkit > Dashboard`.
2. On `Setup`, create or assign the default tag asset.
3. Select the `GameplayTagAsset`.
4. Add tags through the asset inspector or tag search/add UI.
5. Use dot-separated hierarchy: `Status.Burning`, `State.Stunned`, `Ability.Melee.Light`.
6. Assign tags in ability, effect, cue, targeting, and Game Creator assets through the tag drawers.

Create path:

```
Assets > Create > Gameplay Ability Toolkit > Gameplay Tag Asset
```

## Configuration Fields

| Field          | Meaning                                                          |
| -------------- | ---------------------------------------------------------------- |
| `Tags`         | Sorted list of valid tag names.                                  |
| `TagMetadata`  | Per-tag metadata such as deprecation reason and redirect target. |
| `TagRedirects` | Old tag name to new tag name mapping.                            |
| `Version`      | Catalog version string.                                          |
| `Description`  | Human-readable catalog description.                              |

Adding a child tag automatically adds missing parents. Removing a tag with children is blocked unless child removal is requested.

## Runtime Flow

```mermaid
flowchart TD
    TagAsset["GameplayTagAsset"] --> Drawers["Tag drawers and validation"]
    Ability["Ability grants activation owned tags"] --> RuntimeTags["RuntimeTags"]
    Effect["Effect grants tags"] --> RuntimeTags
    RuntimeTags --> AbilityRules["Ability tag requirements"]
    RuntimeTags --> EffectRules["Effect ongoing rules and inhibition"]
    RuntimeTags --> Events["Owned tag added/removed events"]
    Events --> TriggeredAbilities["Triggered abilities"]
```

Runtime tag ownership is counted. If two effects grant `Status.Burning`, removing one effect decrements the count but the actor keeps the tag until all owners remove it.

## Tag Query and Gating

Use simple containers for common cases:

| Asset field                                         | Meaning                                                       |
| --------------------------------------------------- | ------------------------------------------------------------- |
| Ability `ActivationRequiredTags`                    | Actor must own these tags.                                    |
| Ability `ActivationBlockedTags`                     | Actor must not own these tags.                                |
| Ability `SourceRequiredTags` / `TargetRequiredTags` | Source or target must satisfy tags.                           |
| Effect `RequiredTags`                               | Target must own these tags to apply.                          |
| Effect `OngoingRequiredTags`                        | Effect remains active only while these tags are present.      |
| Effect `OngoingBlockedTags`                         | Effect is deactivated while these tags are present.           |
| Effect `InhibitionTags`                             | Effect remains active but suppresses modifiers while matched. |

Use `GameplayTagQuery` when you need nested logic such as "has any of these tags and none of those tags".

## Naming Strategy

Use stable roots:

| Root      | Example            | Use                                                  |
| --------- | ------------------ | ---------------------------------------------------- |
| `Ability` | `Ability.Fireball` | Ability identity and activation by tags.             |
| `Status`  | `Status.Burning`   | Effects and UI status.                               |
| `State`   | `State.Stunned`    | Actor state and blockers.                            |
| `Event`   | `Event.Hit.Light`  | Gameplay events.                                     |
| `Cue`     | `Cue.Impact.Fire`  | Gameplay cue playback.                               |
| `Team`    | `Team.Player`      | Target filters.                                      |
| `Input`   | `Input.Ability1`   | Optional input metadata, not required by core input. |

## Debugging Checklist

* If a tag picker is empty, confirm `GASConfiguration.defaultTagAsset` is assigned.
* If an ability is blocked, inspect the ASC `Tags` tab and the ability's required/blocked fields.
* If a duration effect is active but not changing attributes, inspect `InhibitionTags` and ongoing requirements.
* If a cue does not play, confirm the cue tag exists and is mapped in `GameplayCueLibrary`.
* If a removed effect leaves a tag behind, check whether another active source still owns the same tag count.

## Common Mistakes

| Mistake                                         | Result                        | Fix                                                 |
| ----------------------------------------------- | ----------------------------- | --------------------------------------------------- |
| Using inconsistent roots                        | Hard to search and debug      | Choose roots early and document them.               |
| Using tags for numeric state                    | No magnitude or clamp support | Use attributes.                                     |
| Removing a tag manually while an effect owns it | Counts can be confusing       | Prefer effect-owned granted tags for effect states. |
| Renaming tags without redirects                 | Old assets become misleading  | Use deprecation and redirects.                      |

## Extension Points

* Use custom tag queries in ability/effect assets.
* Add Game Creator conditions/events that react to tag changes.
* Add custom target filters based on `RuntimeTags`.

## Examples and Tests

* Basic Tutorial: ability tags, status tags, and input-related activation.
* Arena Demo: melee state tags, cooldown/status feedback, target filters.
* Tests: `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Tags/GameplayTagQueryContractTests.cs`, `RuntimeTagsTests.cs`, `RuntimeTagsEventSymmetryTests.cs`, `AttributeModifierTagDeepTests.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/tags.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.