A Gameplay Ability, derived from the BP_AdvancedGameplayAbility class, defines what an in-game ability does, what (if anything) it costs to use, when or under what conditions it can be activated, etc. Because all gameplay mechanics can be created inside ability objects, this enables the creation of multiple gameplay systems which are like modular pieces of code that can be modified or replaced as needed in child/derived classes.
Granting and UnGranting Abilities
Before an actor can use an ability, that actor’s Ability System Component must be granted that ability. In order to grant & ungrant an ability you must call the following functions:
GiveAbility - grants the ability to the owning actor’s ability system component
GiveAbilityAndActivateOnce - grants the ability to the owning actor’s ability system component & activates the ability immediately. After the ability completes the ability is ungranted.
ClearAbility - Ungrants & removes the ability from the actor’s ability system component
ClearAbilties - Ungrants & removes multiple abilities from the actor’s ability system component
Basic Usage
A the flow of logic execution for a Gameplay Ability after being granted to an actor’s ability system component is like this:
CanActivateAbility? - This function will perform a condition check that will check if an ability can be activated before the ability is executed.
ActivateAbility - executes game code associated with the ability.
This is the function that users need to override in order to create custom functionality for an ability.
The CommitAbility function can be called on ActivateAbility to apply the costs of activating an ability. Such as the cost for resources required for the gameplay ability.
TryActivateAbility is how you can execute abilities, this function is called from the ability system component and tries to activate the ability if the costs & tag requirements pass the condition checks.
End Ability - Ends the ability when it is finished executing & calls on On Ability Ended. Typically used to call any functionality needed to set code back or disable certain things when an ability ends.
When an ability ends, the ability system will call functions required to handle an ability ending and also call a function “On Ability End” which will return an enum value that will allow you to write different functionality based on if the ability was finished, interrupted, or cancelled.
IMPORTANT NOTE - do NOT override “Ability End”, “Cancel Ability”, & “Interrupt Ability” without first using the call to parent function. The reason is because the parent function calls functionality needed for handling ending abilities. All abilities need to use the call to parent function for those functions when overriding. However, not all abilities will need to call to parent function when overriding “OnAbilityEnd”. For that function it depends on what you need for the ability.
Tags
Gameplay Tags can be used to determine when a gameplay ability can be activated or blocked and which abilities to cancel. Gameplay tags can also be used to activate a specific ability by all tags or with a single tag.
Gameplay tags also add a lot of flexibility & power to the system. Any number of gameplay abilities can be granted that all share the same tag which will allow you to try to activate all granted abilities with that tag. Then you can use the blocked tags, requied tags, or CanActivateAbility? condition check to determine which ability is activated.
Here I will describe the ability tag variables included in the base gameplay ability
Ability Tags - This variable is used to give the ability default tags. This is a gameplay tag container so this will allow you to add multiple tags to a certain ability which can be used by the TryActivateAbilitiesByTags function. These tags can also be used to look for abilities by tags. There are functions in the ability system component to find & filter abilities by the tags.
Activation Owned Tags - When the ability is activated, these tags are given to the activating actor. These tags are removed when the ability ends.
Activation Required Tags - Gameplay tags that the owning actor MUST have before the ability can be activated
Activation Blocked Tags - the ability cannot be activated if the activating actor has these tags
Cancel Abilities with Tags - Any activate abilities with any of these tags will be cancelled when this ability is activated