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

# Effects

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

Effects are reusable gameplay rule assets for changing attributes, granting tags, granting abilities, firing cues, and running duration or periodic logic.

![Practical effect stacking and overflow lifecycle diagram.](/files/uVGoeG7WQTYC4LBXYwRE)

## What It Does

| Layer             | Type               | Responsibility                                                                                          |
| ----------------- | ------------------ | ------------------------------------------------------------------------------------------------------- |
| Definition        | `EffectDefinition` | Serialized effect data: type, duration, period, modifiers, tags, cues, stacking, overflow, calculation. |
| Runtime           | `EffectRuntime`    | Per-spec behavior hooks and lifecycle logic.                                                            |
| Spec              | `EffectSpec`       | Active or executing effect instance with level, context, stack count, timers, granted handles.          |
| Runtime subsystem | `RuntimeEffects`   | Applies, executes, stacks, inhibits, removes, ticks, and indexes effects.                               |

## When To Use It

Use effects for:

* Damage, healing, mana cost, resource gain.
* Buffs and debuffs.
* Cooldowns.
* Passive stat modifiers.
* Damage-over-time or healing-over-time.
* Status tags.
* Cue playback.
* Granting temporary abilities.

## Editor Setup

1. Open `Tools > Gameplay Ability Toolkit > Dashboard`.
2. Select `Effects`, or right-click in Project.
3. Choose `Assets > Create > Gameplay Ability Toolkit > Effects > Base Gameplay Effect Definition`.
4. Name the asset with `GE_`, such as `GE_FireDamage`.
5. Pick the effect `Type`: Instant, Duration, or Infinite.
6. Add modifiers or assign an `EffectCalculation`.
7. Configure duration, period, stacking, tags, cues, and granted abilities as needed.
8. Apply the effect from an ability, initial ASC effects, Game Creator instruction, or code.

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

## Configuration Fields

| Field                                          | Meaning                                                                                |
| ---------------------------------------------- | -------------------------------------------------------------------------------------- |
| `Type`                                         | Instant executes immediately; Duration lives for a time; Infinite lives until removed. |
| `Duration`                                     | Level-based duration for Duration effects.                                             |
| `IsPeriodic` / `Period`                        | Enables repeated execution for non-Instant effects.                                    |
| `ExecutePeriodicEffectOnApply`                 | Runs first periodic execution immediately on application.                              |
| `MaxStack`                                     | Level-based stack cap.                                                                 |
| `StackingKeyPolicy`                            | Determines whether stacks group by definition or another key.                          |
| `StackingDurationPolicy`                       | Whether successful application refreshes duration.                                     |
| `StackingPeriodPolicy`                         | Whether successful application resets period timing.                                   |
| `StackingExpirationPolicy`                     | What happens when a timed stack expires.                                               |
| `Modifiers`                                    | Attribute changes produced by the effect.                                              |
| `Cues`                                         | Gameplay cue tags fired by the effect.                                                 |
| `AssetTags`                                    | Tags identifying the effect asset.                                                     |
| `GrantedTags`                                  | Tags granted to the target while active.                                               |
| `RemoveEffectWithTags`                         | Removes existing active effects with matching tags.                                    |
| `RequiredTags` / `RequiredQuery`               | Application requirements.                                                              |
| `OngoingRequiredTags` / `OngoingRequiredQuery` | Active-state requirements.                                                             |
| `OngoingBlockedTags`                           | Tags that deactivate the effect while present.                                         |
| `InhibitionTags` / `InhibitionQuery`           | Tags that suppress modifiers while the spec remains active.                            |
| `GrantedAbilities`                             | Abilities granted while the effect is active.                                          |
| `Calculation`                                  | Custom execution calculation.                                                          |
| `ConditionalEffects`                           | Follow-up effects applied when target conditions match.                                |
| `OverflowEffects`                              | Effects applied when a new stack exceeds max stack.                                    |
| `DenyOverflowApplication`                      | Drops the overflowing application.                                                     |
| `ClearStackOnOverflow`                         | Clears the current stack on overflow.                                                  |

## Runtime Flow

```mermaid
flowchart TD
    Apply["RuntimeEffects.Apply"] --> Check["Required tags/query and CanApply"]
    Check -->|fail| Stop["No spec"]
    Check -->|pass| Spec["Create or stack EffectSpec"]
    Spec --> Instant{"Instant?"}
    Instant -->|yes| Execute["Execute modifiers/calculation"]
    Instant -->|no| Active["Add active spec"]
    Active --> Tags["Grant tags, abilities, cues"]
    Active --> Tick["Duration and period ticking"]
    Tick --> Inhibit{"Inhibited?"}
    Inhibit -->|yes| Suppress["Keep spec, suppress modifiers"]
    Inhibit -->|no| ApplyMods["Apply active modifiers"]
    Tick --> Expire["Expire or remove"]
    Expire --> Cleanup["Remove modifiers, tags, abilities, cues"]
```

## Choosing Effect Type

| Type     | Use for                                                 | Notes                                 |
| -------- | ------------------------------------------------------- | ------------------------------------- |
| Instant  | Damage, healing, one-shot cost, immediate resource gain | Does not remain active.               |
| Duration | Timed buff, timed debuff, DoT, cooldown                 | Needs duration. Can be periodic.      |
| Infinite | Passive aura, permanent grant, state while equipped     | Must be removed manually or by rules. |

## Stacking and Overflow

Use stacking when multiple applications of the same effect should combine. Common choices:

* Refresh duration on successful application for simple refreshable buffs.
* Remove one stack and refresh duration on expiration for stacked DoTs.
* Apply overflow effects when max stack is exceeded, such as triggering an explosion after three stacks.
* Deny overflow when extra applications should be ignored.

## Practical Usage Patterns

Apply from code:

```csharp
var request = EffectApplicationRequest.CreateResolved(
    target: targetObject,
    targetASC: targetAsc,
    instigator: sourceObject,
    instigatorASC: sourceAsc);

targetAsc.RuntimeEffects.Apply(effectDefinition, request, level: 1);
```

Remove by definition:

```csharp
targetAsc.RuntimeEffects.Remove(effectDefinition);
```

Check stacks:

```csharp
int stacks = targetAsc.RuntimeEffects.GetActiveStackCount(effectDefinition);
```

## Debugging Checklist

* If nothing changes, confirm the effect has modifiers or a calculation.
* If it will not apply, inspect `RequiredTags` and `RequiredQuery`.
* If it applies but has no current modifier impact, inspect inhibition and ongoing blocked tags.
* If periodic ticks do not happen, confirm the effect is Duration or Infinite and `IsPeriodic` is enabled.
* If stacks do not combine, inspect stack key policy and max stack.
* If cues do not play, inspect `Cues` and `GameplayCueLibrary`.

## Common Mistakes

| Mistake                                              | Result                               | Fix                       |
| ---------------------------------------------------- | ------------------------------------ | ------------------------- |
| Setting `IsPeriodic` on Instant effects              | Period is ignored                    | Use Duration or Infinite. |
| Forgetting a duration on Duration effects            | Expiration behavior is unclear       | Set level-based duration. |
| Using Infinite for cooldowns                         | Cooldown never ends                  | Use Duration.             |
| Expecting Instant effects to grant lasting abilities | Grant and removal happen immediately | Use Duration or Infinite. |

## Extension Points

* Subclass `EffectDefinition` and `EffectRuntime`.
* Add `EffectCalculation` for custom execution logic.
* Add custom modifier magnitude calculators.
* Use conditional and overflow effects to compose complex rules without hard-coding every branch.

## Examples and Tests

* Cookbook: DoT with stack refresh, armor mitigation, cooldown HUD, save/restore.
* Arena Demo: damage, burn, cooldowns, and status effects.
* Tests: `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Effects/EffectLifecycleContractTests.cs`, `EffectStackingRemovalDeepTests.cs`, `OverflowEffectsTests.cs`, `ConditionalEffectsTests.cs`, `InhibitionTagsTests.cs`, `EffectGrantedAbilitiesTests.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/effects.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.