Example: Network-Predicted Ability¶

// GA_PredictedMeleeAttack.h
#pragma once

#include "CoreMinimal.h"
#include "YourProjectGameplayAbility.h"
#include "GA_PredictedMeleeAttack.generated.h"

UCLASS()
class UGA_PredictedMeleeAttack : public UYourProjectGameplayAbility
{
    GENERATED_BODY()

public:
    UGA_PredictedMeleeAttack();

    virtual void ActivateAbility(
        const FGameplayAbilitySpecHandle Handle,
        const FGameplayAbilityActorInfo* ActorInfo,
        const FGameplayAbilityActivationInfo ActivationInfo,
        const FGameplayEventData* TriggerEventData) override;

    virtual void EndAbility(
        const FGameplayAbilitySpecHandle Handle,
        const FGameplayAbilityActorInfo* ActorInfo,
        const FGameplayAbilityActivationInfo ActivationInfo,
        bool bReplicateEndAbility,
        bool bWasCancelled) override;

protected:
    UPROPERTY(EditDefaultsOnly, Category = "Damage")
    TSubclassOf<UGameplayEffect> DamageEffectClass;

    UPROPERTY(EditDefaultsOnly, Category = "Damage")
    float BaseDamageAmount = 25.0f;

    UPROPERTY(EditDefaultsOnly, Category = "Animation")
    TObjectPtr<UAnimMontage> AttackMontage;

private:
    UFUNCTION()
    void OnMontageCompleted();

    UFUNCTION()
    void OnMontageInterrupted();

    UFUNCTION()
    void OnDamageEventReceived(FGameplayEventData Payload);
};

// GA_PredictedMeleeAttack.cpp
#include "GA_PredictedMeleeAttack.h"
#include "AbilitySystemComponent.h"
#include "Abilities/Tasks/AbilityTask_PlayMontageAndWait.h"
#include "Abilities/Tasks/AbilityTask_WaitGameplayEvent.h"

UGA_PredictedMeleeAttack::UGA_PredictedMeleeAttack()
{
    InstancingPolicy = EGameplayAbilityInstancingPolicy::InstancedPerActor;
    NetExecutionPolicy = EGameplayAbilityNetExecutionPolicy::LocalPredicted;
}

void UGA_PredictedMeleeAttack::ActivateAbility(
    const FGameplayAbilitySpecHandle Handle,
    const FGameplayAbilityActorInfo* ActorInfo,
    const FGameplayAbilityActivationInfo ActivationInfo,
    const FGameplayEventData* TriggerEventData)
{
    // -------------------------------------------------------
    // PREDICTION WINDOW IS OPEN HERE
    // Everything in this callstack (before return) is predicted.
    // -------------------------------------------------------

    if (!HasAuthorityOrPredictionKey(ActorInfo, &ActivationInfo))
    {
        return;
    }

    // CommitAbility is prediction-aware:
    // - On the CLIENT: predicts cost deduction and cooldown application
    // - On the SERVER: actually applies cost and cooldown
    // - If the server rejects, the client's predicted cost/cooldown
    //   are automatically rolled back
    if (!CommitAbility(Handle, ActorInfo, ActivationInfo))
    {
        EndAbility(Handle, ActorInfo, ActivationInfo, true, true);
        return;
    }

    // Play montage — this is also predicted.
    // The client starts the montage immediately (feels responsive).
    // The server also plays it. If the server rejects the ability,
    // the client's predicted montage is cancelled.
    UAbilityTask_PlayMontageAndWait* MontageTask =
        UAbilityTask_PlayMontageAndWait::CreatePlayMontageAndWaitProxy(
            this,
            NAME_None,
            AttackMontage,
            1.0f);

    MontageTask->OnCompleted.AddDynamic(
        this, &UGA_PredictedMeleeAttack::OnMontageCompleted);
    MontageTask->OnInterrupted.AddDynamic(
        this, &UGA_PredictedMeleeAttack::OnMontageInterrupted);
    MontageTask->OnCancelled.AddDynamic(
        this, &UGA_PredictedMeleeAttack::OnMontageInterrupted);
    MontageTask->ReadyForActivation();

    // Wait for the hit event from the anim notify.
    // This fires OUTSIDE the prediction window (it's a callback
    // that happens later in the montage). That's fine — we'll
    // handle the damage application on the server only.
    UAbilityTask_WaitGameplayEvent* EventTask =
        UAbilityTask_WaitGameplayEvent::WaitGameplayEvent(
            this,
            FGameplayTag::RequestGameplayTag(
                FName("Event.Montage.MeleeHit")));

    EventTask->EventReceived.AddDynamic(
        this, &UGA_PredictedMeleeAttack::OnDamageEventReceived);
    EventTask->ReadyForActivation();

    // -------------------------------------------------------
    // PREDICTION WINDOW CLOSES when this function returns.
    // After this point, anything we do is NOT automatically
    // predicted unless we open a new FScopedPredictionWindow.
    // -------------------------------------------------------
}

void UGA_PredictedMeleeAttack::OnDamageEventReceived(
    FGameplayEventData Payload)
{
    // This callback fires when the AnimNotify sends the hit event.
    // We are OUTSIDE the original prediction window.
    //
    // IMPORTANT: We apply damage on the SERVER ONLY.
    // The client should NOT predict damage application because:
    // 1. Execution Calculations don't support prediction
    // 2. The target's health is server-authoritative
    // 3. Predicting damage creates complex rollback scenarios

    if (!GetActorInfo().IsNetAuthority())
    {
        // Client: don't apply damage, let the server handle it.
        // The target's health change will replicate down normally.
        return;
    }

    // Server: apply the damage effect
    if (Payload.Target && DamageEffectClass)
    {
        FGameplayEffectSpecHandle SpecHandle =
            MakeOutgoingGameplayEffectSpec(
                DamageEffectClass, GetAbilityLevel());

        if (SpecHandle.IsValid())
        {
            SpecHandle.Data->SetSetByCallerMagnitude(
                FGameplayTag::RequestGameplayTag(
                    FName("SetByCaller.Damage")),
                BaseDamageAmount);

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

            if (TargetASC)
            {
                ApplyGameplayEffectSpecToTarget(
                    GetCurrentAbilitySpecHandle(),
                    GetCurrentActorInfo(),
                    GetCurrentActivationInfo(),
                    SpecHandle,
                    TargetASC);
            }
        }
    }
}

void UGA_PredictedMeleeAttack::OnMontageCompleted()
{
    EndAbility(
        GetCurrentAbilitySpecHandle(),
        GetCurrentActorInfo(),
        GetCurrentActivationInfo(),
        true, false);
}

void UGA_PredictedMeleeAttack::OnMontageInterrupted()
{
    EndAbility(
        GetCurrentAbilitySpecHandle(),
        GetCurrentActorInfo(),
        GetCurrentActivationInfo(),
        true, true);
}

void UGA_PredictedMeleeAttack::EndAbility(
    const FGameplayAbilitySpecHandle Handle,
    const FGameplayAbilityActorInfo* ActorInfo,
    const FGameplayAbilityActivationInfo ActivationInfo,
    bool bReplicateEndAbility,
    bool bWasCancelled)
{
    Super::EndAbility(Handle, ActorInfo, ActivationInfo,
        bReplicateEndAbility, bWasCancelled);
}

void UGA_SomeAbility::OnSomeDelayedCallback()
{
    // We're outside the original prediction window.
    // Open a new one to predict this effect application.
    UAbilitySystemComponent* ASC = GetAbilitySystemComponentFromActorInfo();
    if (!ASC)
    {
        return;
    }

    // This creates a new dependent prediction key
    FScopedPredictionWindow ScopedPrediction(ASC, true);

    // Now we can apply effects that will be predicted
    FGameplayEffectSpecHandle SpecHandle =
        MakeOutgoingGameplayEffectSpec(BuffEffectClass, GetAbilityLevel());
    ApplyGameplayEffectSpecToOwner(
        GetCurrentAbilitySpecHandle(),
        GetCurrentActorInfo(),
        GetCurrentActivationInfo(),
        SpecHandle);

    // When ScopedPrediction goes out of scope, the window closes.
    // The new prediction key is sent to the server as a dependent key.
}