unreal-gas

Unreal Engine Gameplay Ability System (GAS) -- C++ Guide

Official Documentation (always consult for latest details)

These are the authoritative sources. Reference them for up-to-date API details, as GAS evolves across engine versions:

The community docs by tranek are the most comprehensive single resource for GAS. They cover advanced topics (prediction internals, optimization, replication modes, pitfalls) that Epic's official docs do not. Always check them for edge cases and production patterns.

The Lyra Sample Project is Epic's recommended working reference implementation for GAS.

Plugin Setup

1. Enable Gameplay Abilities plugin in the editor
2. Add to Build.cs:

   PublicDependencyModuleNames.AddRange(new string[] {
       "GameplayAbilities", "GameplayTags", "GameplayTasks"
   });
3. UE 5.2 and earlier: call UAbilitySystemGlobals::Get().InitGlobalData() in your AssetManager or GameInstance. UE 5.3+ does this automatically.

Core Architecture

See references/core-classes.md for the full class reference, setup patterns, and C++ code snippets.

System overview:

Actor
  +-- UAbilitySystemComponent (ASC) --- manages everything below
        +-- UGameplayAbility instances (granted abilities)
        |     +-- UAbilityTask instances (async execution)
        +-- UAttributeSet instances (numeric data)
        +-- Active UGameplayEffect specs (modifiers)
        +-- FGameplayTag container (status/state)
        +-- GameplayCue triggers (cosmetic FX)

Key relationships:

• ASC is the central hub; one per Actor (place on Pawn or PlayerState)
• Abilities create/apply Effects to modify Attributes and Tags on targets
• Effects auto-trigger Cues when their tags match GameplayCue.* tags
• Tags control ability activation, blocking, and cancellation systemically
• AbilityTasks handle async work (montages, delays, targeting) within abilities

Gameplay Effects Quick Reference

See references/effects-and-attributes.md for detailed GE patterns, modifier math, stacking, cooldowns, and attribute handling.

Duration types:

• Instant -- modifies BaseValue permanently, never tracked as active
• Duration -- modifies CurrentValue, auto-reverts on expiry
• Infinite -- persists until explicitly removed

Modifier aggregation: ((Base + Additive) * Multiplicative) / Division

• Multiply/Divide uses 1 + Sum(Mods - 1) -- two +50% multipliers = +100%, not +125%

Ability Lifecycle

GiveAbility() -> TryActivateAbility() -> CanActivateAbility()
  -> ActivateAbility() [override this] -> CommitAbility() [apply cost/cooldown]
  -> ... do work (AbilityTasks) ... -> EndAbility()

Four activation methods: explicit handle, GameplayEvent, GameplayEffect tags, Input codes.

Instancing policies:

• InstancedPerActor -- recommended default; one instance reused per actor
• InstancedPerExecution -- new instance each activation; simplest but heaviest
• NonInstanced -- uses CDO; best performance, C++ only, no state/delegates/RPCs

Networking & Prediction

See references/networking.md for replication modes, prediction details, and multiplayer patterns.

Net Execution Policies: LocalPredicted, LocalOnly, ServerOnly, ServerInitiated.

Key rules:

• ASC replicates Attributes and Tags to all clients, but NOT abilities/effects (bandwidth optimization)
• Non-instant GEs support prediction rollback; instant GEs (damage) do NOT
• Cues use unreliable replication -- cosmetic only, never gameplay logic
• ASC's owning Actor must be locally controlled for remote activation to work
• For PlayerState-based ASC: use Mixed replication for players, Minimal for AI

Common Patterns & Pitfalls

See references/patterns-and-pitfalls.md for implementation recipes and known issues.

Critical pitfalls:

• PreAttributeChange clamping does NOT permanently change modifiers -- clamp BaseValue in PostGameplayEffectExecute instead
• Server Respects Remote Ability Cancellation causes more trouble than it's worth -- disable it
• Replication Policy on GameplayAbility is misleadingly named -- do not use it
• PlayerState NetUpdateFrequency defaults too low -- increase it or enable Adaptive Network Update Frequency
• Removing AttributeSets at runtime can crash clients
• Animation montages must use PlayMontageAndWait AbilityTask, not direct PlayMontage, for replication