> 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/tutorial-details/advancedtopics.md). # Advanced Topics > Online doc: The Basic Tutorial teaches the everyday loop: attributes, tags, simple effects, instant/held abilities, cues, targeting, and HUD observation. This page points to deeper systems that are useful once you start building production abilities. Each topic includes when to use it, where it lives, and how to verify it through tests. > Tests are off by default. Enable them from `Tools > Gameplay Ability Toolkit > Dashboard > Dependencies` before opening the Test Runner. ## How To Use This Page Read one topic at a time. Each section answers: | Question | Why it matters | | --------------------- | -------------------------------------------------------------- | | When should I use it? | Prevents reaching for advanced APIs too early. | | Where is it authored? | Tells you whether to inspect assets, prefabs, or C# classes. | | What should I verify? | Turns an advanced feature into a Play Mode or testable result. | If a topic feels abstract, open the Arena demo after reading the section. Arena uses many of these systems in visible combat situations. ## Enable Tests In The Editor Use this path before opening the Unity Test Runner: 1. Open `Tools > Gameplay Ability Toolkit > Dashboard > Dependencies`. 2. Enable the test dependencies required by the toolkit. 3. Wait for Unity to recompile. 4. Open `Window > General > Test Runner`. 5. Select the Editor or PlayMode tab named by the section. If tests do not appear, re-open the dashboard and confirm the dependency toggle is still enabled. ## Ability Tasks Use `AbilityTask` when an ability waits across frames: delay, input release, montage completion, target confirmation, or gameplay event. Reach for it when you would otherwise write a coroutine for ability timing. ```csharp protected override void OnActivate(GameplayEventData eventData) { var wait = RunTask(new AbilityTask_WaitDelay(0.6f)); wait.Completed += () => { // Windup complete. Apply the hit effect here. EndAbility(); }; } ``` Where to look: * `Core/Task/AbilityTask.cs` * `Core/Task/AbilityTasks_Input.cs` * `Core/Task/AbilityTasks_Montage.cs` * `Core/Task/AbilityTasks_Reactive.cs` Tests: * `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Tasks/AbilityTaskContractTests.cs` * `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Tasks/ReactiveTaskTests.cs` * `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Tasks/InputHoldDoubleTapTaskTests.cs` Editor reading path: 1. Select an ability asset that needs timing. 2. Open the runtime class that implements that ability. 3. Find where the runtime starts a task. 4. Confirm cancellation or ability end cleans up the task. What to verify: * The task completes when the expected event happens. * Cancelling the ability prevents late callbacks. * Re-activating the ability does not reuse stale task state. ## Effect Stacking, Overflow, and Conditional Application Use stacking for DoTs, buffs, poison counters, combo marks, escalating status, or repeated pickups. Use overflow when reaching the cap should trigger something special, such as a poison explosion. Use conditional effects when an extra effect should apply only if the target has matching tags. Where to look: * `Core/Effects/EffectDefinition.cs` * [Authoring Effects](/docs/gameplay-ability-toolkit/build-with-it/04-authoring-effects.md) Tests: * `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Effects/EffectStackingRemovalDeepTests.cs` * `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Effects/OverflowEffectsTests.cs` * `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Effects/ConditionalEffectsTests.cs` Editor setup checklist: 1. Open the `GE_*` asset. 2. Confirm the effect type is `Duration` or `Infinite` if it should remain active. 3. Set max stack count and refresh behavior. 4. Add overflow effects only after normal stacking works. 5. Add conditional effects only after the required target/source tags are validated. What to verify: | Feature | Expected signal | | ------------------ | --------------------------------------------------------- | | Stacking | Stack count changes in event log or HUD. | | Overflow | Extra effect applies at max stack. | | Conditional effect | Extra effect applies only when matching tags are present. | ## Targeting With Collectors, Filters, and Indicators Use targeting systems when an ability needs something more explicit than "apply to self." Examples: * A meteor that waits for ground confirmation. * A heal that only affects allies in range. * A projectile or trace that excludes blocked line-of-sight. * A melee cone that filters by team. Runtime pattern: ```csharp protected override void OnActivate(GameplayEventData eventData) { var task = new AbilityTask_WaitForTargetData( this, TargetingConfirmation.Instant, collectorPrefab); task.TargetDataReady += data => { foreach (var target in data.GetTargets()) { // Apply effects to each target. } }; RunTask(task); } ``` Where to look: * `Core/Targeting/` * `Core/Targeting/Tracing/TraceShape.cs` * `Core/Targeting/Indicator/GroundAOETargetIndicator.cs` Tests: * `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Targeting/GeneralTargetCollectorTests.cs` * `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Targeting/MultiTargetCollectorTests.cs` * `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Targeting/TraceShapeTests.cs` Editor setup checklist: 1. Open the collector prefab or asset. 2. Confirm the shape, radius, range, layer mask, and origin. 3. Confirm filters are assigned only when you need team, tag, or component constraints. 4. Assign the collector to the ability asset. 5. Use debug draw in Tutorial or Arena before adding VFX polish. What to verify: * One target inside the shape is collected. * One target outside the shape is ignored. * Cancelled targeting removes indicators and does not apply effects. ## Inhibition Tags Use inhibition when an effect should remain active but temporarily stop contributing modifiers. Examples: * Stealth suppresses regeneration. * Silence pauses a healing aura. * A scripted state suspends a passive bonus without removing it. The spec remains alive, duration keeps counting, and modifier contribution resumes when the inhibition condition clears. Test: * `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Effects/InhibitionTagsTests.cs` Editor setup checklist: 1. Open the effect asset that should be suppressible. 2. Add the inhibition tag query. 3. Apply the effect in Play Mode and confirm it contributes normally. 4. Add the inhibiting tag to the actor. 5. Confirm contribution stops while the active effect spec remains alive. 6. Remove the tag and confirm contribution resumes. Use inhibition when "pause this buff" is clearer than "remove and later recreate this buff." ## Attribute Hooks Two extension points handle attribute reactions: | Rule belongs to | Use | | -------------------------------------------------------- | --------------------------- | | This actor's components, gear, stance, shield, or status | `IAttributeChangeHook` | | The attribute definition itself | `RuntimeAttribute` subclass | Examples: * Armor mitigation before Health drops. * Shield overflow into Health. * Custom clamp curves for a specific attribute schema. Tests: * `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Attributes/AttributeChangeHookTests.cs` * `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Attributes/RuntimeAttributeSubclassHookTests.cs` Editor setup checklist: 1. Decide whether the rule belongs to the actor or the attribute schema. 2. For actor-owned rules, add the hook component to the actor that owns the ASC. 3. For definition-owned rules, configure the runtime attribute subclass through the attribute definition. 4. Apply a small effect and inspect the before/after values. What to verify: * The hook runs on the target actor you expect. * Clamp behavior still applies after the hook. * Derived or transient attributes reset when your schema expects them to reset. ## Modifier Magnitudes and Custom Calculators Use the built-in magnitude strategies first: | Strategy | Example | | ---------------- | ------------------------------------------------ | | `LevelBased` | Damage scales from ability level. | | `AttributeBased` | Fireball damage scales from caster SpellPower. | | `SetByCaller` | Fall damage passes the fall distance at runtime. | Use a custom calculator when one modifier needs reusable formula logic that cannot be expressed with the built-ins. Tests: * `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/ModifierMagnitudeTests.cs` * `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Attributes/ModifierMagnitudeDeepContractTests.cs` Editor decision guide: | Need | Use | | ---------------------------------------------- | -------------------------- | | A constant number | Fixed magnitude. | | A number that scales with ability/effect level | Level-based magnitude. | | A number based on source or target attributes | Attribute-based magnitude. | | A runtime value supplied by the caller | Set-by-caller magnitude. | | A reusable formula with several inputs | Custom calculator. | What to verify: * Missing set-by-caller values fail loudly or use an intentional fallback. * Source and target attribute reads use the actor you intended. * Level-based values match the asset curve/table at several levels. ## Effects That Grant Abilities and Effect Calculations Effects can grant abilities for their active lifetime. Use this for power-ups, equipment, temporary forms, or buffs that unlock actions. `EffectCalculation` is for "one effect application emits several related modifiers." Use it when a single gameplay rule needs to produce multiple writes together. Tests: * `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Effects/EffectGrantedAbilitiesTests.cs` * `DevelopmentTests/GameplayAbilityToolkit/Core.Tests/Editor/Effects/EffectCalculationTests.cs` Editor setup checklist: 1. Open the effect asset. 2. Add granted abilities only if the ability should exist for the effect lifetime. 3. Confirm removal policy when the effect expires. 4. For calculations, keep the emitted modifiers easy to inspect in tests. 5. Test applying, stacking, and removing the effect. What to verify: * The granted ability appears only while the effect is active. * Removing the effect removes or disables the granted ability according to policy. * Calculation output modifies all expected attributes in one application. ## What the Basic Tutorial Does Not Cover The Basic scene deliberately does not cover everything: * Overflow effects. * Full ground-target confirmation UI. * Inhibition. * Custom attribute hooks. * Custom magnitude calculators. * Effect calculations. * Save/load. * Network replication or prediction. For complete gameplay examples, inspect the [Arena Demo](/docs/gameplay-ability-toolkit/try-it/arena.md). For implementation recipes, read the [Cookbook](/docs/gameplay-ability-toolkit/build-with-it/07-cookbook.md). --- # 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/tutorial-details/advancedtopics.md?ask= ``` 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.