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] 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
  • 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_matching_tag_query (GameplayTagQuery): [Read-Write] Abilities matching query are cancelled when this ability is executed
  • 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] Current Event Data
  • instancing_policy (GameplayAbilityInstancingPolicy): [Read-Write] Instancing Policy
  • 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] Net Execution Policy
  • 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] Protected properties
  • 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) –
Returns:
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:
Returns:

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) –
Returns:

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:
Returns:

Return type:

Array(ActiveGameplayEffectHandle)

can_activate_ability(actor_info) → GameplayTagContainer or None

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

Parameters:actor_info (GameplayAbilityActorInfo) –
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.

Returns:
Return type:bool
check_ability_cost() → bool

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

Returns:
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!

Returns:
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) –
Returns:

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) –
Returns:
Return type:bool
commit_execute() → None

BP event called from CommitAbility

confirm_task_by_instance_name(instance_name, end_task) → None

Destroys instanced-per-execution abilities. Instance-per-actor abilities should ‘reset’. Non instance abilities - what can we do?

Parameters:
  • instance_name (Name) –
  • end_task (bool) –
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.

current_event_data

(GameplayEventData) – [Read-Only] Current Event Data

end_ability() → None

Call from kismet to end the ability naturally

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

Returns:
Return type:int32
get_ability_system_component_from_actor_info() → AbilitySystemComponent

Returns the AbilitySystemComponent that is activating this ability

Returns:
Return type:AbilitySystemComponent
get_actor_info() → GameplayAbilityActorInfo

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

Returns:
Return type:GameplayAbilityActorInfo
get_avatar_actor_from_actor_info() → Actor

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

Returns:
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) –
Returns:
Return type:GameplayEffectContextHandle
get_cooldown_time_remaining() → float

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

Returns:
Return type:float
get_current_montage() → AnimMontage

Returns the currently playing montage for this ability, if any

Returns:
Return type:AnimMontage
get_current_source_object() → Object

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

Returns:
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.

Returns:
Return type:GameplayEffectContextHandle
get_owning_actor_from_actor_info() → Actor

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

Returns:
Return type:Actor
get_owning_component_from_actor_info() → SkeletalMeshComponent

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

Returns:
Return type:SkeletalMeshComponent
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.

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:
Returns:

Return type:

GameplayEffectSpecHandle

make_target_location_info_from_owner_actor() → GameplayAbilityTargetingLocationInfo

Creates a target location from where the owner avatar is

Returns:
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) –
Returns:
Return type:GameplayAbilityTargetingLocationInfo
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

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

Kismet 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:
Returns:

Return type:

bool