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

# Gameplay Cues

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

Gameplay cues connect gameplay tags to presentation behavior such as VFX, SFX, camera shakes, decals, floating visuals, or pooled scene prefabs.

![Practical gameplay cue pooling diagram showing lookup, non-instanced cue, instanced prefab pool, and target playback.](/files/J0O0JVkkDErV0Yt8z5Eq)

## What It Does

| Type                        | Responsibility                                                        |
| --------------------------- | --------------------------------------------------------------------- |
| `GameplayCueLibrary`        | Maps cue tags to cue notify assets or cue notify prefabs.             |
| `GameplayCueMapper`         | One mapping row: tag, instanced/non-instanced mode, notify reference. |
| `GameplayCueEvent`          | Cue lifecycle event type.                                             |
| `GameplayCueParameters`     | Target/source context passed to cue notifies.                         |
| `IGameplayCueNotify`        | Common interface for cue handlers.                                    |
| `GameplayNotifyCueSO`       | Non-instanced ScriptableObject cue notify.                            |
| `GameplayNotifyCueBehavior` | Instanced MonoBehaviour cue notify prefab.                            |
| `GameplayCueManager`        | Resolves and pools instanced cue behavior.                            |
| `GameplayNotifyCuePool`     | Pool implementation for cue prefabs.                                  |

## When To Use It

Use cues when gameplay should trigger presentation without hard-coding VFX in ability/effect runtime code:

* Impact sparks.
* Status loop VFX.
* Buff start/end sound.
* Hit camera shake.
* Floating world marker.
* Parent fallback cue behavior.

## Editor Setup

1. Add cue tags to the tag asset, such as `Cue.Impact.Fire`.
2. Create a cue library with `Assets > Create > Gameplay Ability Toolkit > Gameplay Cue Library`.
3. Assign it to `GASConfiguration.defaultCueLibrary`.
4. Create cue notify script/assets from the Dashboard Cues page or cue creation menu.
5. Add a row to `GameplayCueLibrary`.
6. Set the cue tag.
7. Choose non-instanced `GameplayNotifyCueSO` or instanced `GameplayNotifyCueBehavior` prefab.
8. Add the cue tag to an `EffectDefinition.Cues` container.
9. Enter Play Mode and apply the effect.

## Configuration Fields

| Field                 | Meaning                                                                  |
| --------------------- | ------------------------------------------------------------------------ |
| Mapper `tag`          | Cue tag being handled.                                                   |
| `useInstancedCue`     | If false, use a ScriptableObject notify; if true, use a prefab behavior. |
| `notifyCue`           | Non-instanced cue asset.                                                 |
| `notifyCuePrefab`     | Instanced cue behavior prefab.                                           |
| `isOverride`          | Stops parent cue fallback when true.                                     |
| Pool config           | Prewarm/max/unique behavior for instanced cues.                          |
| `AutoDestroyOnRemove` | Whether instanced cue cleans itself up on removal.                       |

## Runtime Flow

```mermaid
flowchart TD
    Effect["Effect with cue tags"] --> Event["Cue event: OnActive, WhileActive, Executed, Removed"]
    Event --> Library["GameplayCueLibrary lookup"]
    Library --> Notify{"Instanced?"}
    Notify -->|no| SO["GameplayNotifyCueSO.HandleGameplayCue"]
    Notify -->|yes| Pool["GameplayCueManager pool"]
    Pool --> Prefab["GameplayNotifyCueBehavior instance"]
    SO --> Parent["Optional parent cue fallback"]
    Prefab --> Parent
```

## Non-Instanced vs Instanced

| Mode             | Use for                                                                 | Avoid when                                                              |
| ---------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| Non-instanced SO | Fire-and-forget sounds, simple logging, centralized presentation calls. | You need per-target scene state.                                        |
| Instanced prefab | Looping VFX, attached objects, persistent status visuals.               | The cue is extremely frequent and can be handled without scene objects. |

## Parent Cue Fallback

If `Cue.Impact.Fire.Heavy` has no override, the library can walk to parent cue data such as `Cue.Impact.Fire` or `Cue.Impact`. Use this for shared behavior and set `isOverride` when the child should fully replace the parent.

## Debugging Checklist

* If no cue plays, confirm the effect has cue tags and the cue library is assigned.
* If the wrong cue plays, inspect parent fallback and `isOverride`.
* If prefab cues leak, inspect `AutoDestroyOnRemove` and pool settings.
* If duration cues never remove, confirm the effect is removed or expires.
* If cue tags are hard to find, keep all cue tags under a `Cue` root.

## Common Mistakes

| Mistake                                            | Result                                | Fix                                          |
| -------------------------------------------------- | ------------------------------------- | -------------------------------------------- |
| Putting VFX code directly in damage effect runtime | Presentation and rules become coupled | Use cues.                                    |
| Using instanced prefabs for every tiny event       | Pool pressure                         | Use SO cues for simple events.               |
| Missing default cue library                        | Cue lookup has nowhere to resolve     | Assign `GASConfiguration.defaultCueLibrary`. |
| Forgetting parent override rules                   | Duplicate parent and child visuals    | Set `isOverride` where needed.               |

## Extension Points

* Subclass `GameplayNotifyCueSO`.
* Subclass `GameplayNotifyCueBehavior`.
* Add Game Creator instructions that trigger cue tags.
* Customize pooling behavior through cue behavior config and global defaults.

## Examples and Tests

* Basic Tutorial: cue feedback for visible cause/effect.
* Arena Demo: impact/status presentation.
* Tests: `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Cues/CueLifecycleContractTests.cs`, `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Systems/TargetingCueMontageLoggingDeepContractTests.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/gameplay-cues.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.