ue-gameplay-abilities

What this skill does

# Gameplay Ability System (GAS)

You are an expert in Unreal Engine's Gameplay Ability System (GAS).

## Context Check

Before proceeding, read `.agents/ue-project-context.md` to determine:
- Whether the GameplayAbilities plugin is enabled
- Which actors own the AbilitySystemComponent (PlayerState vs Character)
- The replication mode in use (Minimal, Mixed, Full)
- Any existing AttributeSets or ability base classes

## Information Gathering

Ask the developer:
1. What type of abilities are needed? (active, passive, triggered, instant)
2. What attributes are required? (health, mana, stamina, custom stats)
3. Is this multiplayer? If so, which actors carry the ASC?
4. Are cooldowns and costs required, or is this a passive/trigger system?
5. Do abilities need prediction (local-only feedback before server confirms)?

---

## GAS Architecture Overview

GAS has three pillars that live on `UAbilitySystemComponent` (ASC):

| Pillar | Class | Purpose |
|--------|-------|---------|
| Abilities | `UGameplayAbility` | Logic for what happens when activated |
| Effects | `UGameplayEffect` | Data-driven stat mutations (instant, duration, infinite) |
| Attributes | `UAttributeSet` | Float properties representing character stats |

GameplayTags thread through all three as requirements, grants, and blockers.

---

## GAS Setup

### 1. Enable the Plugin

Enable `GameplayAbilities` in `.uproject` Plugins array, then in `[ProjectName].Build.cs`:
```csharp
PublicDependencyModuleNames.AddRange(new string[]
{
    "GameplayAbilities", "GameplayTags", "GameplayTasks"
});
```

### 2. AbilitySystemComponent Ownership

**PlayerState (recommended for multiplayer):** ASC persists across respawns because PlayerState
is not destroyed on death. Use this for player characters in networked games.

**Character/Pawn:** Simpler. Use for AI characters or single-player games where persistence
across respawns is not required.

See `references/gas-setup-patterns.md` for full initialization sequences for both patterns.

### 3. IAbilitySystemInterface

Every actor that owns or exposes an ASC must implement `IAbilitySystemInterface`:

```cpp
#include "AbilitySystemInterface.h"

UCLASS()
class AMyCharacter : public ACharacter, public IAbilitySystemInterface
{
    GENERATED_BODY()
public:
    virtual UAbilitySystemComponent* GetAbilitySystemComponent() const override
        { return AbilitySystemComponent; }
    UPROPERTY(VisibleAnywhere, BlueprintReadOnly, Category = "GAS")
    TObjectPtr<UAbilitySystemComponent> AbilitySystemComponent;
};
```

### 4. Replication Modes

Set on the ASC after creation (server-side only):

```cpp
// In BeginPlay or PossessedBy on the server:
AbilitySystemComponent->SetReplicationMode(EGameplayEffectReplicationMode::Mixed);
```

| Mode | When to Use |
|------|-------------|
| `Minimal` | AI or non-player actors; no GE replication to simulated proxies |
| `Mixed` | Player-controlled characters (owner gets full info, others get minimal) |
| `Full` | Non-player games or debugging; all GEs replicate to all clients |

### 5. InitAbilityActorInfo

Must be called on both server and client after possession. Call in `PossessedBy` (server)
and `OnRep_PlayerState` (client): `ASC->InitAbilityActorInfo(OwnerActor, AvatarActor)`.
See `references/gas-setup-patterns.md` for full dual-path code with respawn handling.

---

## GameplayAbilities

### Subclass UGameplayAbility

```cpp
#include "Abilities/GameplayAbility.h"

UCLASS()
class UMyFireballAbility : public UGameplayAbility
{
    GENERATED_BODY()
public:
    UMyFireballAbility();
    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;
    // Ability Tasks — async building blocks for latent abilities:
    // UAbilityTask_WaitTargetData    — waits for targeting (crosshair/AoE confirm)
    // UAbilityTask_WaitGameplayEvent — waits for a GameplayEvent tag (e.g., anim notify)
    // UAbilityTask_WaitDelay         — simple timer
    // UAbilityTask_PlayMontageAndWait — montage with callbacks (see ue-animation-system)
    // See references/ability-task-reference.md for full list and custom task pattern.
    // CancelAbility — called by CancelAbilitiesWithTag or ASC->CancelAbility(Handle)
    // Internally calls EndAbility with bWasCancelled=true. Override to add cleanup:
    virtual void CancelAbility(const FGameplayAbilitySpecHandle Handle,
        const FGameplayAbilityActorInfo* ActorInfo,
        const FGameplayAbilityActivationInfo ActivationInfo,
        bool bReplicateCancelAbility) override;
    // Custom activation guard — return false to block activation beyond tag checks
    virtual bool CanActivateAbility(const FGameplayAbilitySpecHandle Handle,
        const FGameplayAbilityActorInfo* ActorInfo, /*...*/) const override;
    // Must call Super first. Add custom checks (resource availability, cooldown state).
protected:
    UPROPERTY(EditDefaultsOnly, Category = "GAS")
    TSubclassOf<UGameplayEffect> DamageEffect;
};
```

### ActivateAbility Pattern

```cpp
void UMyFireballAbility::ActivateAbility(const FGameplayAbilitySpecHandle Handle,
    const FGameplayAbilityActorInfo* ActorInfo,
    const FGameplayAbilityActivationInfo ActivationInfo,
    const FGameplayEventData* TriggerEventData)
{
    // 1. Commit: validates and applies cost + cooldown
    if (!CommitAbility(Handle, ActorInfo, ActivationInfo))
    {
        EndAbility(Handle, ActorInfo, ActivationInfo, true, true);
        return;
    }
    // 2. Apply effect / spawn projectile / etc.
    FGameplayEffectSpecHandle Spec = MakeOutgoingGameplayEffectSpec(DamageEffect, GetAbilityLevel());
    FGameplayAbilityTargetDataHandle TargetData =
        UAbilitySystemBlueprintLibrary::AbilityTargetDataFromActor(
            ActorInfo->AvatarActor.Get());
    ApplyGameplayEffectSpecToTarget(Handle, ActorInfo, ActivationInfo, Spec, TargetData);
    // 3. End (instant abilities end immediately; latent abilities wait for tasks)
    EndAbility(Handle, ActorInfo, ActivationInfo, true, false);
}
```

`CommitAbility` is shorthand for `CommitAbilityCost` + `CommitAbilityCooldown`. Call them
separately when needed -- e.g., commit cost without starting cooldown for a channeled ability,
or commit cooldown without cost for a free ability.

### Instancing and Net Execution Policy

Set in the ability constructor:

```cpp
UMyFireballAbility::UMyFireballAbility()
{
    // InstancedPerActor  - one instance per actor; cheapest for persistent abilities
    // InstancedPerExecution - new instance each activation; safe for concurrency
    // NonInstanced       - CDO runs the ability; no per-execution state
    InstancingPolicy = EGameplayAbilityInstancingPolicy::InstancedPerActor;

    // LocalPredicted  - client runs immediately, server validates (player abilities)
    // ServerOnly      - authority only, no prediction
    // LocalOnly       - local client only (UI, cosmetic)
    // ServerInitiated - server activates, clients run non-authoritative predicted copy
    NetExecutionPolicy = EGameplayAbilityNetExecutionPolicy::LocalPredicted;
}
```

### Granting and Activating Abilities

```cpp
// Grant (server/authority only):
FGameplayAbilitySpecHandle Handle = ASC->GiveAbility(
    FGameplayAbilitySpec(UMyFireballAbility::StaticClass(), 1 /*Level*/));

ASC->TryActivateAbility(Handle);                                       // by handle
ASC->TryActivateAbilityByClass(UMyFireballAbility::StaticClass());    // by class
ASC->TryActivateAbilitiesByTag(                                        // by tag
    FGameplayTagContainer(FGameplayTag::RequestGameplayTag("Ability.Sk