unreal.GameplayAbility

class unreal.GameplayAbility(outer=None, name='None')

Bases: unreal.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] Ability Tags: This ability has these tags

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

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

  • activation_owned_tags (GameplayTagContainer): [Read-Write] Activation Owned Tags: 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] Activation Required Tags: This ability can only be activated if the activating actor/component has all of these tags

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

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

  • cooldown_gameplay_effect_class (type(Class)): [Read-Write] Cooldown Gameplay Effect Class: 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] Cost Gameplay Effect Class: 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] Current Activation Info: 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] Current Event Data: Information specific to this instance of the ability, if it was activated by an event

  • instancing_policy (GameplayAbilityInstancingPolicy): [Read-Write] Instancing Policy: 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] Mark Pending Kill on Ability End: 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] Net Execution Policy: 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] Net Security Policy: 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] Replicate Input Directly: If true, this ability will always replicate input press/release events to the server.

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

  • retrigger_instanced_ability (bool): [Read-Write] Retrigger Instanced Ability: 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] Server Respects Remote Ability Cancellation: 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] Source Blocked Tags: This ability is blocked if the source actor/component has any of these tags

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

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

  • target_required_tags (GameplayTagContainer): [Read-Write] Target Required Tags: 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)

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)

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

[Read-Only] Current Activation Info: 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

[Read-Only] Current Event Data: 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 he 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

[Read-Only] Mark Pending Kill on Ability End: 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