GASDocumentation

GASDocumentation is a community-driven resource designed to explain the major concepts and classes of Unreal Engine 5's GameplayAbilitySystem (GAS) plugin. It provides commentary based on practical experience with a multiplayer sample project to help bridge the gap between official documentation and the 'tribal knowledge' often required to use GAS effectively.

Important Notes:

• This is not official Epic Games documentation.
• The content is current with Unreal Engine 5.3 (UE5).
• For older engine versions, use the corresponding branches, though they are unsupported and may contain inaccuracies.
• The most authoritative documentation remains the plugin's source code.

The Gameplay Ability System (GAS) is a flexible framework developed by Epic Games for building RPG or MOBA-style abilities, attributes, and status effects. It provides out-of-the-box solutions for:

• GameplayAbilities: Level-based character skills with costs and cooldowns.
• Attributes: Numerical values belonging to actors.
• GameplayEffects: Status effects applied to actors.
• GameplayTags: Tagging actors for state management.
• GameplayCues: Visual or sound effects.
• Replication: Built-in networking and client-side prediction for abilities, animations, attributes, tags, and cues.

Note: GAS must be set up in C++, though GameplayAbilities and GameplayEffects can be authored in Blueprints.

The AbilitySystemComponent (ASC) is the core of the Gameplay Ability System (GAS). It is a UActorComponent (UAbilitySystemComponent) that manages GameplayAbilities, Attributes, and GameplayEffects.

Key concepts:

• OwnerActor: The actor that owns the ASC (e.g., a PlayerState for persistent stats).
• AvatarActor: The physical representation of the ASC in the world (e.g., a Character).
• IAbilitySystemInterface: Both the OwnerActor and AvatarActor should implement this interface by overriding UAbilitySystemComponent* GetAbilitySystemComponent() const to allow internal GAS interactions.
• Ability List Locking: When iterating over ActivatableAbilities.Items, you must use ABILITYLIST_SCOPE_LOCK(); to prevent crashes if abilities are removed during iteration. Do not attempt to remove an ability while the lock is active.

In the Gameplay Ability System (GAS), prediction is used to minimize latency for the player. However, Epic recommends predicting the minimum amount of state possible to avoid complex reconciliation issues.

Predicted elements:

• Ability activation
• Triggered Events
• GameplayEffect application (Attribute modification and GameplayTag modification; Note: ExecutionCalculations are NOT predicted)
• Gameplay Cue events
• Montages
• Movement (via UCharacterMovement)

Non-predicted elements:

• GameplayEffect removal
• GameplayEffect periodic effects (e.g., DOTs ticking)

Workaround for GE removal: Since GameplayEffect removal cannot be predicted, you can predict the inverse effect (e.g., applying a 40% speed buff to 'remove' a 40% speed slow) and then remove both effects simultaneously when the server confirms.

To see why an ability failed to activate in logs or the showdebug AbilitySystem HUD, you must define specific GameplayTags and map them in your project configuration.

1. Add tags to your project (e.g., Activation.Fail.OnCooldown, Activation.Fail.CantAffordCost).
2. Map these tags in DefaultGame.ini under the [/Script/GameplayAbilities.AbilitySystemGlobals] section.

[/Script/GameplayAbilities.AbilitySystemGlobals]
ActivateFailIsDeadName=Activation.Fail.IsDead
ActivateFailCooldownName=Activation.Fail.OnCooldown
ActivateFailCostName=Activation.Fail.CantAffordCost
ActivateFailTagsBlockedName=Activation.Fail.BlockedByTags
ActivateFailTagsMissingName=Activation.Fail.MissingTags
ActivateFailNetworkingName=Activation.Fail.Networking

An ASC can have multiple AttributeSets. You can choose between two main organizational patterns:

1. Monolithic Approach: One large AttributeSet shared by all Actors. This is simple but may contain unused attributes.
2. Modular Approach: Multiple specialized AttributeSets (e.g., a HealthAttributeSet, a ManaAttributeSet) added to Actors only when needed (e.g., heroes get mana, minions do not).

Constraints:

• Class Uniqueness: You should not have more than one AttributeSet of the same class on a single ASC. If you attempt to add multiple instances of the same class, the ASC will only use one and ignore the others.
• Naming: Attributes are internally referenced using the format AttributeSetClassName.AttributeName. Subclassing an AttributeSet preserves the parent class's name as the prefix for all inherited attributes.

You can assign SourceTags and TargetTags to individual Modifiers. These function like Application Tag requirements for a GameplayEffect: they are evaluated only at the moment the effect is applied. For periodic or infinite effects, these tags are checked during the initial application, but not during subsequent periodic executions.

Additionally, Attribute Based modifiers support SourceTagFilter and TargetTagFilter. These filters are used when determining the magnitude of the backing attribute to exclude specific modifiers that do not meet the tag requirements.

To reduce network traffic in multiplayer games, change the Replication Mode of the ASC:

• Full Replication Mode (Default): Replicates all GameplayEffects to every client. Suitable for single-player.
• Mixed Replication Mode: Set this for player-owned ASCs. It replicates GameplayEffects only to the owner.
• Minimal Replication Mode: Set this for AI-controlled characters. GameplayEffects applied to AI will never replicate to clients.

Note: GameplayTags and GameplayCues (unreliable NetMulticast) will still replicate to all clients regardless of the mode.