Example: Melee Attack¶

Overview¶

A melee attack ability that demonstrates the full GAS pipeline working together. The character swings a weapon, pays a stamina cost, respects a cooldown, and deals damage at a precise point in the attack animation using an AnimNotify and WaitGameplayEvent. This covers montage-driven timing, SetByCaller damage, the PendingDamage meta attribute pattern, and proper ability lifecycle management.

What We're Building¶

• Stamina cost of 15 per swing
• Cooldown of 1 second between attacks
• Montage-driven hit timing -- damage fires at a specific animation frame, not on button press
• SetByCaller damage -- the damage amount is data-driven, not hardcoded in the effect
• PendingDamage meta attribute -- damage flows through a processing pipeline before reaching Health
• AnimNotify integration -- the montage tells the ability when the weapon connects
• Tag-based blocking -- can't attack while dead or hard-stunned

Prerequisites¶

Step 1: Create the Effects¶

We create the effects first, before the ability. This is intentional -- effects are the data that defines what an ability actually does. The ability is just the orchestrator that decides when and how to apply them. Think of effects as the nouns and the ability as the verb.

All three effects are created in the Unreal Editor. Right-click in the Content Browser and select Blueprint Class > GameplayEffect as the parent class.

GE_Cost_MeleeAttack¶

This effect represents the stamina cost. GAS checks costs automatically before an ability activates -- if the character can't afford it, the ability simply won't fire. No manual checks needed.

GE_Cooldown_MeleeAttack¶

The cooldown effect uses GAS's built-in cooldown system. When an ability activates, it applies this effect. While the effect is active, the ability checks for the cooldown tag and blocks re-activation.

The magic is in the tag. Your ability will be configured to check for Cooldown.Ability.BasicAttack -- while this effect is active and that tag is present on the ASC, the ability can't activate. When the 1-second duration expires, the effect is removed, the tag is removed, and the ability is available again. No timers, no manual cleanup.

GE_Damage_Melee¶

This is the damage effect. Instead of hardcoding a damage number, we use SetByCaller -- the ability sets the damage value at runtime when it creates the effect spec. This means a single damage effect class can be reused with different damage values, and those values can come from attributes, data tables, or calculations.

Notice we target PendingDamage, not Health. This is the meta attribute pattern from Project Setup -- damage flows into PendingDamage, gets processed in PostGameplayEffectExecute (armor, shields, etc.), and the final result is applied to Health. This gives you a single processing pipeline for all damage sources.

Step 2: Create the Ability¶

Create a new Blueprint class in the Content Browser. The parent class should be your YourProjectGameplayAbility (the base ability class from Project Setup). Name it GA_MeleeAttack.

Class Defaults¶

Open the Blueprint and set these in the Class Defaults panel:

Event Graph¶

Here's the ability logic. This runs when the ability activates (after cost and cooldown checks pass):

flowchart LR
    A["ActivateAbility"]:::event --> B["PlayMontageAndWait\nAM_MeleeAttack"]:::task
    A --> C["WaitGameplayEvent\nEvent.Montage.MeleeHit"]:::task
    C -->|Hit Event| D["MakeOutgoingGESpec\nGE_Damage_Melee"]:::func
    D --> E["SetByCaller\nDamage = 25"]:::func
    E --> F["ApplyGESpec\nto Target"]:::func
    B -->|Completed / BlendOut| G["EndAbility"]:::endpoint
    B -->|Interrupted / Cancelled| G

    classDef event fill:#5c1a1a,stroke:#ff6666,color:#fff
    classDef func fill:#2a2a4a,stroke:#9b89f5,color:#fff
    classDef task fill:#1a3a5c,stroke:#4a9eff,color:#fff
    classDef endpoint fill:#1a4a2d,stroke:#6bcb3a,color:#fff

void UGA_MeleeAttack::ActivateAbility(
    const FGameplayAbilitySpecHandle Handle,
    const FGameplayAbilityActorInfo* ActorInfo,
    const FGameplayAbilityActivationInfo ActivationInfo,
    const FGameplayEventData* TriggerEventData)
{
    if (!CommitAbility(Handle, ActorInfo, ActivationInfo))
    {
        EndAbility(Handle, ActorInfo, ActivationInfo, true, true);
        return;
    }

    // --- Play the attack montage ---
    UAbilityTask_PlayMontageAndWait* MontageTask =
        UAbilityTask_PlayMontageAndWait::CreatePlayMontageAndWaitProxy(
            this,
            NAME_None,
            AttackMontage,  // UPROPERTY: TObjectPtr<UAnimMontage>
            1.0f);

    MontageTask->OnCompleted.AddDynamic(
        this, &UGA_MeleeAttack::OnMontageCompleted);
    MontageTask->OnBlendOut.AddDynamic(
        this, &UGA_MeleeAttack::OnMontageCompleted);
    MontageTask->OnInterrupted.AddDynamic(
        this, &UGA_MeleeAttack::OnMontageCancelled);
    MontageTask->OnCancelled.AddDynamic(
        this, &UGA_MeleeAttack::OnMontageCancelled);
    MontageTask->ReadyForActivation();

    // --- Wait for the AnimNotify hit event ---
    UAbilityTask_WaitGameplayEvent* EventTask =
        UAbilityTask_WaitGameplayEvent::WaitGameplayEvent(
            this,
            FGameplayTag::RequestGameplayTag(
                FName("Event.Montage.MeleeHit")),
            nullptr,    // no external target
            false);     // keep listening (for combo hits)

    EventTask->EventReceived.AddDynamic(
        this, &UGA_MeleeAttack::OnHitEventReceived);
    EventTask->ReadyForActivation();
}

void UGA_MeleeAttack::OnHitEventReceived(FGameplayEventData Payload)
{
    // The payload's Target is populated by hit detection
    // (trace/overlap in the AnimNotify or weapon actor)
    if (!Payload.Target)
    {
        return;
    }

    UAbilitySystemComponent* TargetASC =
        UAbilitySystemBlueprintLibrary::GetAbilitySystemComponent(
            const_cast<AActor*>(Payload.Target.Get()));

    if (!TargetASC)
    {
        return;
    }

    // Create the damage spec with caster context
    FGameplayEffectSpecHandle DamageSpec =
        MakeOutgoingGameplayEffectSpec(
            DamageEffectClass,  // UPROPERTY: TSubclassOf<UGameplayEffect>
            GetAbilityLevel());

    DamageSpec.Data->SetSetByCallerMagnitude(
        FGameplayTag::RequestGameplayTag(
            FName("SetByCaller.Damage")),
        DamageAmount);  // UPROPERTY: float, default 25.0

    TargetASC->ApplyGameplayEffectSpecToSelf(
        *DamageSpec.Data.Get());
}

void UGA_MeleeAttack::OnMontageCompleted()
{
    EndAbility(
        CurrentSpecHandle,
        CurrentActorInfo,
        CurrentActivationInfo,
        true, false);
}

void UGA_MeleeAttack::OnMontageCancelled()
{
    EndAbility(
        CurrentSpecHandle,
        CurrentActorInfo,
        CurrentActivationInfo,
        true, true);
}

The AnimNotify¶

Open your attack montage (AM_MeleeAttack) in the Montage Editor. At the frame where the weapon should connect with a target, add an AnimNotify that sends a gameplay event:

1. Right-click the Notifies track at the desired frame
2. Add Notify > AN_SendGameplayEvent (or your custom notify class)
3. Set the Event Tag to Event.Montage.MeleeHit
4. The event payload should include the target actor (populated by your hit detection logic -- a trace, overlap, etc.)

Step 3: Wire Input¶

You need three things to connect a keyboard/gamepad input to your ability:

1. InputAction Asset¶

Create an Input Action asset in the editor (right-click > Input > Input Action). Name it IA_PrimaryAttack. Set the Value Type to Digital (Bool) -- it's a press, not an axis.

2. InputMappingContext¶

Open (or create) your Input Mapping Context (IMC_Default or similar). Add a mapping:

• Input Action: IA_PrimaryAttack
• Key: Left Mouse Button (or whatever you prefer)

3. Route Input to the ASC¶

The connection between Enhanced Input and GAS happens in your character. The exact implementation depends on your input binding approach, but the core idea is: when IA_PrimaryAttack fires, find all granted abilities whose InputTag matches InputTag.Combat.Primary and try to activate them.

void AYourCharacter::SetupPlayerInputComponent(
    UInputComponent* PlayerInputComponent)
{
    Super::SetupPlayerInputComponent(PlayerInputComponent);

    if (UEnhancedInputComponent* EnhancedInput =
        Cast<UEnhancedInputComponent>(PlayerInputComponent))
    {
        EnhancedInput->BindAction(
            PrimaryAttackAction,  // UPROPERTY: TObjectPtr<UInputAction>
            ETriggerEvent::Started,
            this, &AYourCharacter::OnPrimaryAttackInput);
    }
}

void AYourCharacter::OnPrimaryAttackInput()
{
    if (!AbilitySystemComponent) return;

    for (FGameplayAbilitySpec& Spec :
         AbilitySystemComponent->GetActivatableAbilities())
    {
        if (const UYourProjectGameplayAbility* GA =
            Cast<UYourProjectGameplayAbility>(Spec.Ability))
        {
            if (GA->InputTag.MatchesTagExact(
                FGameplayTag::RequestGameplayTag(
                    FName("InputTag.Combat.Primary"))))
            {
                AbilitySystemComponent->TryActivateAbility(
                    Spec.Handle);
            }
        }
    }
}

4. Grant the Ability¶

Open your Character Blueprint. In Class Defaults, find the Startup Abilities array and add GA_MeleeAttack. When the character spawns and InitializeAbilities runs, this ability will be granted to the ASC and ready to activate.

Step 4: Test¶

Quick Smoke Test¶

1. Place your character Blueprint in a level
2. Hit Play
3. Press your attack button -- the character should play the attack montage
4. If you have a second character in range, they should take 25 damage

Debugging with ShowDebug¶

Open the console (`) and type:

showdebug abilitysystem

This overlay shows you everything happening in the ASC in real time:

• Granted Abilities -- you should see GA_MeleeAttack listed
• Active Abilities -- lights up while your attack is playing
• Active Effects -- you'll see the cooldown effect appear for 1 second after attacking
• Attributes -- watch Stamina drop by 15 each attack, Health drop on the target
• Tags -- the cooldown tag appears and disappears

What to Verify¶

Edge Cases¶

• Interrupted mid-swing -- another montage or stun interrupts the attack. Ability should end cleanly, no damage applied (the AnimNotify never fires)
• Target dies before hit frame -- the event still fires, but the target's ASC may reject the effect. No crash, no damage
• Spam click during cooldown -- all attempts silently fail. No animation, no cost deduction

The Full Flow¶

Let's trace the complete sequence from button press to health drop:

1. Input fires IA_PrimaryAttack
2. Your input handler finds abilities with InputTag.Combat.Primary and calls TryActivateAbility
3. The ASC checks: Can this ability activate? It evaluates:
   • Cost: Do we have 15+ Stamina? (checks GE_Cost_MeleeAttack)
   • Cooldown: Is Cooldown.Ability.BasicAttack tag present? (checks GE_Cooldown_MeleeAttack)
   • Blocked tags: Does the owner have State.Dead or CrowdControl.Hard?
4. If all checks pass, the ability activates:
   • Cost effect is applied (Stamina -15)
   • Cooldown effect is applied (tag granted for 1 second)
   • ActivateAbility fires in the Blueprint / C++
5. The ability plays a montage and waits for the Event.Montage.MeleeHit gameplay event
6. An AnimNotify in the montage fires at the exact hit frame, runs hit detection, and sends the event with the target in the payload
7. The ability receives the event, creates a damage GE spec, sets the damage amount via SetByCaller (25.0), and applies it to the target's ASC
8. The target's PostGameplayEffectExecute processes PendingDamage -- applies armor, shields, and other mitigation -- then subtracts the final result from Health
9. The montage completes, the ability calls End Ability, all tasks are cleaned up

Every piece of GAS was involved. The ASC managed it. Tags controlled flow. Effects modified attributes. The ability orchestrated the sequence. This is the GAS loop.

Variations¶

Heavy Attack¶

Same structure, but with a longer montage, higher stamina cost (30), higher damage (50), and a longer cooldown (2 seconds). You can add a State.HeavyAttack Activation Owned Tag that grants super armor (prevents interruption from light hits) during the swing. Use the same GE_Damage_Melee effect -- just set a higher SetByCaller magnitude.

Combo Chain¶

Use multiple montage sections (Swing1, Swing2, Swing3) and track which section to play next with a combo counter on the ability instance. After each hit, start a short WaitDelay task -- if the player presses attack again within the window, play the next section. If the window expires, reset to Swing1. Each section can have its own AnimNotify with different damage values.

AoE Sweep¶

Instead of a single target from the AnimNotify, run a multi-hit trace that returns all actors in the weapon's arc. Loop through the results and apply the damage spec to each target's ASC. The gameplay event payload supports TargetData for multi-target scenarios, or you can send multiple individual events.

Related Pages¶

• Dodge Roll -- stamina cost, i-frames, root motion montage
• Ranged Attack -- projectile spawning, passing GE specs to actors
• Ability Tasks -- PlayMontageAndWait, WaitGameplayEvent details
• SetByCaller -- how the damage magnitude system works
• Cooldowns and Costs -- cost/cooldown deep dive
• Damage Pipeline -- how PendingDamage flows through to Health
• Tag Architecture -- designing your tag hierarchy