> 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-events.md).

# Gameplay Events

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

Gameplay events are tagged payloads that let code, Game Creator instructions, ability tasks, and ability triggers communicate without directly referencing one another.

## What It Does

| Type                                   | Responsibility                                                                                |
| -------------------------------------- | --------------------------------------------------------------------------------------------- |
| `GameplayEventData`                    | Payload: event tag, instigator, target, source/target tags, magnitude, custom payload object. |
| `AbilityTriggerData`                   | Ability authoring data that activates from gameplay event tags or owned tag changes.          |
| `RuntimeAbilities.HandleGameplayEvent` | Dispatches events to trigger buckets and registered receivers.                                |
| `AbilityTask_WaitGameplayEvent`        | Lets an active ability wait for an event.                                                     |
| Game Creator event/instruction bridge  | Sends or reacts to gameplay events from visual scripting.                                     |

## When To Use It

Use gameplay events for:

* Hit confirmations.
* Combo windows.
* Animation notify payloads.
* External scripts activating abilities by tag.
* Game Creator instructions triggering toolkit abilities.
* Passing hit data, target data, or magnitudes to an ability.

Use direct method calls when the caller and receiver are already tightly coupled and no tag-based routing is needed.

## Editor Setup

1. Add an event tag to the default `GameplayTagAsset`, such as `Event.Hit.Light`.
2. Open an ability asset.
3. Add an `AbilityTriggerData` entry.
4. Set the trigger source to the gameplay event mode.
5. Assign the trigger tag.
6. In code or Game Creator, send a `GameplayEventData` with the same tag to the target ASC.
7. Enter Play Mode and inspect the ASC `Abilities` and `Events` tabs.

## GameplayEventData Fields

| Field            | Meaning                                           |
| ---------------- | ------------------------------------------------- |
| `eventTag`       | Tag that identifies the event.                    |
| `instigator`     | GameObject that initiated the event.              |
| `target`         | GameObject receiving the event.                   |
| `instigatorTags` | Snapshot or supplied tags for source-side checks. |
| `targetTags`     | Snapshot or supplied tags for target-side checks. |
| `EventMagnitude` | Optional scalar value such as damage or force.    |
| `Payload`        | Optional custom object such as hit data.          |

## Runtime Flow

```mermaid
flowchart TD
    Sender["Code, animation, Game Creator, or ability"] --> Data["GameplayEventData"]
    Data --> ASC["Target ASC RuntimeAbilities"]
    ASC --> TriggerBucket["Ability triggers by event tag"]
    ASC --> Receivers["Registered event receivers"]
    TriggerBucket --> Activate["Activate matching inactive abilities"]
    Receivers --> Tasks["WaitGameplayEvent tasks or custom handlers"]
```

## Practical Usage Patterns

Trigger a target ability:

```csharp
var data = new GameplayEventData
{
    eventTag = new GameplayTag("Event.Hit.Light"),
    instigator = attacker,
    target = defender,
    EventMagnitude = damage
};

defenderAsc.RuntimeAbilities.HandleGameplayEvent(data.eventTag, data);
```

Wait inside an ability:

```csharp
var task = new AbilityTask_WaitGameplayEvent(new GameplayTag("Event.Combo.Window"));
task.Received += data => { /* continue combo */ };
RunTask(task);
```

## Debugging Checklist

* If an event trigger does not activate, confirm the ability is granted and inactive.
* Confirm the event tag exactly matches the trigger tag.
* Confirm the event is sent to the ASC that owns the ability.
* If payload casts fail, confirm both sender and receiver agree on the payload type.
* If tag requirements block the triggered ability, inspect the ASC `Events` tab for failure reason.

## Common Mistakes

| Mistake                                                        | Result                    | Fix                                                             |
| -------------------------------------------------------------- | ------------------------- | --------------------------------------------------------------- |
| Sending to the instigator ASC when the target owns the ability | Nothing triggers          | Send to the intended receiver ASC.                              |
| Using similar but different event tags                         | No match                  | Use the tag picker and stable naming.                           |
| Expecting active abilities to re-activate from triggers        | Trigger skips active spec | End/cancel first or handle the event inside the active runtime. |
| Passing untyped payload assumptions                            | Runtime cast fails        | Document payload type per event tag.                            |

## Examples and Tests

* Game Creator integration: visual scripting event bridge.
* Tests: `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Systems/InputTargetCueDeepTests.cs`, `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Abilities/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/gameplay-events.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.