unreal.GameplayAbility

class unreal.GameplayAbility(outer: Object | None = None, name: Name | str = 'None')

Bases: Object

Abilities define custom gameplay logic that can be activated by players or external game logic

C++ Source:

  • Plugin: GameplayAbilities

  • Module: GameplayAbilities

  • File: GameplayAbility.h

Editor Properties: (see get_editor_property/set_editor_property)

  • ability_tags (GameplayTagContainer): [Read-Write] This ability has these tags

  • ability_triggers (Array[AbilityTriggerData]): [Read-Write] Triggers to determine if this ability should execute in response to an event

  • activation_blocked_tags (GameplayTagContainer): [Read-Write] This ability is blocked if the activating actor/component has any of these tags

  • activation_owned_tags (GameplayTagContainer): [Read-Write] Tags to apply to activating owner while this ability is active. These are replicated if ReplicateActivationOwnedTags is enabled in AbilitySystemGlobals.

  • activation_required_tags (GameplayTagContainer): [Read-Write] This ability can only be activated if the activating actor/component has all of these tags

  • block_abilities_with_tag (GameplayTagContainer): [Read-Write] Abilities with these tags are blocked while this ability is active

  • cancel_abilities_with_tag (GameplayTagContainer): [Read-Write] Abilities with these tags are cancelled when this ability is executed

  • cooldown_gameplay_effect_class (type(Class)): [Read-Write] This GameplayEffect represents the cooldown. It will be applied when the ability is committed and the ability cannot be used again until it is expired.

  • cost_gameplay_effect_class (type(Class)): [Read-Write] This GameplayEffect represents the cost (mana, stamina, etc) of the ability. It will be applied when the ability is committed.

  • current_activation_info (GameplayAbilityActivationInfo): [Read-Write] This is information specific to this instance of the ability. E.g, whether it is predicting, authoring, confirmed, etc.

  • current_event_data (GameplayEventData): [Read-Write] Information specific to this instance of the ability, if it was activated by an event

  • instancing_policy (GameplayAbilityInstancingPolicy): [Read-Write] How the ability is instanced when executed. This limits what an ability can do in its implementation.

  • mark_pending_kill_on_ability_end (bool): [Read-Write] Flag that is set by AbilitySystemComponent::OnRemoveAbility to indicate the ability needs to be cleaned up in AbilitySystemComponent::NotifyAbilityEnded

  • net_execution_policy (GameplayAbilityNetExecutionPolicy): [Read-Write] How does an ability execute on the network. Does a client “ask and predict”, “ask and wait”, “don’t ask (just do it)”.

  • net_security_policy (GameplayAbilityNetSecurityPolicy): [Read-Write] What protections does this ability have? Should the client be allowed to request changes to the execution of the ability?

  • replicate_input_directly (bool): [Read-Write] If true, this ability will always replicate input press/release events to the server.

  • replication_policy (GameplayAbilityReplicationPolicy): [Read-Write] How an ability replicates state/events to everyone on the network. Replication is not required for NetExecutionPolicy.

  • retrigger_instanced_ability (bool): [Read-Write] if true, and trying to activate an already active instanced ability, end it and re-trigger it.

  • server_respects_remote_ability_cancellation (bool): [Read-Write] If this is set, the server-side version of the ability can be canceled by the client-side version. The client-side version can always be canceled by the server.

  • source_blocked_tags (GameplayTagContainer): [Read-Write] This ability is blocked if the source actor/component has any of these tags

  • source_required_tags (GameplayTagContainer): [Read-Write] This ability can only be activated if the source actor/component has all of these tags

  • target_blocked_tags (GameplayTagContainer): [Read-Write] This ability is blocked if the target actor/component has any of these tags

  • target_required_tags (GameplayTagContainer): [Read-Write] This ability can only be activated if the target actor/component has all of these tags

activate_ability() → None

The main function that defines what an ability does. -Child classes will want to override this -This function graph should call CommitAbility -This function graph should call EndAbility

Latent/async actions are ok in this graph. Note that Commit and EndAbility calling requirements speak to the K2_ActivateAbility graph. In C++, the call to K2_ActivateAbility() may return without CommitAbility or EndAbility having been called. But it is expected that this will only occur when latent/async actions are pending. When K2_ActivateAbility logically finishes, then we will expect Commit/End to have been called.

activate_ability_from_event(event_data) → None

K2 Activate Ability from Event

Parameters:

event_data (GameplayEventData) –

add_gameplay_cue(gameplay_cue_tag, context, remove_on_ability_end=True) → None

Adds a persistent gameplay cue to the ability owner. Optionally will remove if ability ends

Parameters:
add_gameplay_cue_with_params(gameplay_cue_tag, gameplay_cue_parameter, remove_on_ability_end=True) → None

Adds a persistent gameplay cue to the ability owner. Optionally will remove if ability ends

Parameters:
apply_gameplay_effect_spec_to_owner(effect_spec_handle) → ActiveGameplayEffectHandle

Apply a previously created gameplay effect spec to the owner of this ability

Parameters:

effect_spec_handle (GameplayEffectSpecHandle) –

Return type:

ActiveGameplayEffectHandle

apply_gameplay_effect_spec_to_target(effect_spec_handle, target_data) → Array[ActiveGameplayEffectHandle]

Apply a previously created gameplay effect spec to a target

Parameters:
Return type:

Array[ActiveGameplayEffectHandle]

apply_gameplay_effect_to_owner(gameplay_effect_class, gameplay_effect_level=1, stacks=1) → ActiveGameplayEffectHandle

Apply a gameplay effect to the owner of this ability

Parameters:

  • gameplay_effect_class (type(Class)) –

  • gameplay_effect_level (int32) –

  • stacks (int32) –

Return type:

ActiveGameplayEffectHandle

apply_gameplay_effect_to_target(target_data, gameplay_effect_class, gameplay_effect_level=1, stacks=1) → Array[ActiveGameplayEffectHandle]

Apply a gameplay effect to a Target

Parameters:
Return type:

Array[ActiveGameplayEffectHandle]

can_activate_ability(actor_info, handle) → GameplayTagContainer or None

Returns true if this ability can be activated right now. Has no side effects

Parameters:
Returns:

relevant_tags (GameplayTagContainer):

Return type:

GameplayTagContainer or None

cancel_ability() → None

Call from Blueprint to cancel the ability naturally

cancel_task_by_instance_name(instance_name) → None

Add any task with this instance name to a list to be canceled (not ended) next frame. See also EndTaskByInstanceName.

Parameters:

instance_name (Name) –

check_ability_cooldown() → bool

Checks the ability’s cooldown, but does not apply it.

Return type:

bool

check_ability_cost() → bool

Checks the ability’s cost, but does not apply it.

Return type:

bool

commit_ability() → bool

Attempts to commit the ability (spend resources, etc). This our last chance to fail. Child classes that override ActivateAbility must call this themselves!

Return type:

bool

commit_ability_cooldown(broadcast_commit_event=False, force_cooldown=False) → bool

Attempts to commit the ability’s cooldown only. If BroadcastCommitEvent is true, it will broadcast the commit event that tasks like WaitAbilityCommit are listening for.

Parameters:

  • broadcast_commit_event (bool) –

  • force_cooldown (bool) –

Return type:

bool

commit_ability_cost(broadcast_commit_event=False) → bool

Attempts to commit the ability’s cost only. If BroadcastCommitEvent is true, it will broadcast the commit event that tasks like WaitAbilityCommit are listening for.

Parameters:

broadcast_commit_event (bool) –

Return type:

bool

commit_execute() → None

BP event called from CommitAbility

confirm_task_by_instance_name(instance_name, end_task) → None

Finds all currently active tasks named InstanceName and confirms them. What this means depends on the individual task. By default, this does nothing other than ending if bEndTask is true.

Parameters:

  • instance_name (Name) –

  • end_task (bool) –

property current_activation_info: GameplayAbilityActivationInfo

[Read-Only] This is information specific to this instance of the ability. E.g, whether it is predicting, authoring, confirmed, etc.

Type:

(GameplayAbilityActivationInfo)

property current_event_data: GameplayEventData

[Read-Only] Information specific to this instance of the ability, if it was activated by an event

Type:

(GameplayEventData)

end_ability() → None

Call from blueprints to forcibly end the ability without canceling it. This will replicate the end ability to the client or server which can interrupt tasks

end_ability_locally() → None

Call from blueprints to end the ability naturally. This will only end predicted abilities locally, allowing it end naturally on the client or server

end_ability_state(optional_state_name_to_end) → None

Ends any active ability state task with the given name. If name is ‘None’ all active states will be ended (in an arbitrary order).

Parameters:

optional_state_name_to_end (Name) –

end_task_by_instance_name(instance_name) → None

Add any task with this instance name to a list to be ended (not canceled) next frame. See also CancelTaskByInstanceName.

Parameters:

instance_name (Name) –

execute_gameplay_cue(gameplay_cue_tag, context) → None

Invoke a gameplay cue on the ability owner

Parameters:
execute_gameplay_cue_with_params(gameplay_cue_tag, gameplay_cue_parameters) → None

Invoke a gameplay cue on the ability owner, with extra parameters

Parameters:
get_ability_level() → int32

Returns current level of the Ability

Return type:

int32

get_ability_level_bp(handle, actor_info) → int32

Returns current ability level for non instanced abilities. You must call this version in these contexts!

Parameters:
Return type:

int32

get_ability_system_component_from_actor_info() → AbilitySystemComponent

Returns the AbilitySystemComponent that is activating this ability

Return type:

AbilitySystemComponent

get_actor_info() → GameplayAbilityActorInfo

Returns the actor info associated with this ability, has cached pointers to useful objects

Return type:

GameplayAbilityActorInfo

get_avatar_actor_from_actor_info() → Actor

Returns the physical actor that is executing this ability. May be null

Return type:

Actor

get_context_from_owner(optional_target_data) → GameplayEffectContextHandle

Generates a GameplayEffectContextHandle from our owner and an optional TargetData.

Parameters:

optional_target_data (GameplayAbilityTargetDataHandle) –

Return type:

GameplayEffectContextHandle

get_cooldown_time_remaining() → float

Returns the time in seconds remaining on the currently active cooldown.

Return type:

float

get_current_montage() → AnimMontage

Returns the currently playing montage for this ability, if any

Return type:

AnimMontage

get_current_source_object() → Object

Retrieves the SourceObject associated with this ability. Can only be called on instanced abilities.

Return type:

Object

get_granted_by_effect_context() → GameplayEffectContextHandle

Retrieves the EffectContext of the GameplayEffect that granted this ability. Can only be called on instanced abilities.

Return type:

GameplayEffectContextHandle

get_owning_actor_from_actor_info() → Actor

Returns the actor that owns this ability, which may not have a physical location

Return type:

Actor

get_owning_component_from_actor_info() → SkeletalMeshComponent

Convenience method for abilities to get skeletal mesh component - useful for aiming abilities

Return type:

SkeletalMeshComponent

get_source_object_bp(handle, actor_info) → Object

Retrieves the SourceObject associated with this ability. Callable on non instanced

Parameters:
Return type:

Object

invalidate_client_prediction_key() → None

Invalidates the current prediction key. This should be used in cases where there is a valid prediction window, but the server is doing logic that only it can do, and afterwards performs an action that the client could predict (had the client been able to run the server-only code prior). This returns instantly and has no other side effects other than clearing the current prediction key.

is_locally_controlled() → bool

True if the owning actor is locally controlled, true in single player

Return type:

bool

k2_has_authority() → bool

K2 Has Authority

Return type:

bool

make_outgoing_gameplay_effect_spec(gameplay_effect_class, level=1.000000) → GameplayEffectSpecHandle

Convenience method for abilities to get outgoing gameplay effect specs (for example, to pass on to projectiles to apply to whoever they hit)

Parameters:
Return type:

GameplayEffectSpecHandle

make_target_location_info_from_owner_actor() → GameplayAbilityTargetingLocationInfo

Creates a target location from where the owner avatar is

Return type:

GameplayAbilityTargetingLocationInfo

make_target_location_info_from_owner_skeletal_mesh_component(socket_name) → GameplayAbilityTargetingLocationInfo

Creates a target location from a socket on the owner avatar’s skeletal mesh

Parameters:

socket_name (Name) –

Return type:

GameplayAbilityTargetingLocationInfo

property mark_pending_kill_on_ability_end: bool

[Read-Only] Flag that is set by AbilitySystemComponent::OnRemoveAbility to indicate the ability needs to be cleaned up in AbilitySystemComponent::NotifyAbilityEnded

Type:

(bool)

montage_jump_to_section(section_name) → None

Immediately jumps the active montage to a section

Parameters:

section_name (Name) –

montage_set_next_section_name(from_section_name, to_section_name) → None

Sets pending section on active montage

Parameters:

  • from_section_name (Name) –

  • to_section_name (Name) –

montage_stop(override_blend_out_time=-1.000000) → None

Stops the current animation montage.

Parameters:

override_blend_out_time (float) –

on_end_ability(was_cancelled) → None

Blueprint event, will be called if an ability ends normally or abnormally

Parameters:

was_cancelled (bool) –

remove_gameplay_cue(gameplay_cue_tag) → None

Removes a persistent gameplay cue from the ability owner

Parameters:

gameplay_cue_tag (GameplayTag) –

remove_gameplay_effect_from_owner_with_asset_tags(with_asset_tags, stacks_to_remove=-1) → None

Removes GameplayEffects from owner which match the given asset level tags

Parameters:
remove_gameplay_effect_from_owner_with_granted_tags(with_granted_tags, stacks_to_remove=-1) → None

Removes GameplayEffects from owner which grant the given tags

Parameters:
remove_gameplay_effect_from_owner_with_handle(handle, stacks_to_remove=-1) → None

Removes GameplayEffect from owner that match the given handle

Parameters:
remove_granted_by_effect() → None

Removes the GameplayEffect that granted this ability. Can only be called on instanced abilities.

send_gameplay_event(event_tag, payload) → None

Sends a gameplay event, also creates a prediction window

Parameters:
set_can_be_canceled(can_be_canceled) → None

Sets whether the ability should ignore cancel requests. Only valid on instanced abilities

Parameters:

can_be_canceled (bool) –

set_should_block_other_abilities(should_block_abilities) → None

Sets rather ability block flags are enabled or disabled. Only valid on instanced abilities

Parameters:

should_block_abilities (bool) –

should_ability_respond_to_event(actor_info, payload) → bool

Returns true if this ability can be activated right now. Has no side effects

Parameters:
Return type:

bool