unreal.GameplayAbility
¶
- class unreal.GameplayAbility(outer: Optional[Object] = None, name: Union[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] Ability Tags: This ability has these tagsability_triggers
(Array[AbilityTriggerData]): [Read-Write] Ability Triggers: Triggers to determine if this ability should execute in response to an eventactivation_blocked_tags
(GameplayTagContainer): [Read-Write] Activation Blocked Tags: This ability is blocked if the activating actor/component has any of these tagsactivation_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 tagsblock_abilities_with_tag
(GameplayTagContainer): [Read-Write] Block Abilities with Tag: Abilities with these tags are blocked while this ability is activecancel_abilities_with_tag
(GameplayTagContainer): [Read-Write] Cancel Abilities with Tag: Abilities with these tags are cancelled when this ability is executedcooldown_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 eventinstancing_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::NotifyAbilityEndednet_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 tagssource_required_tags
(GameplayTagContainer): [Read-Write] Source Required Tags: This ability can only be activated if the source actor/component has all of these tagstarget_blocked_tags
(GameplayTagContainer): [Read-Write] Target Blocked Tags: This ability is blocked if the target actor/component has any of these tagstarget_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:
gameplay_cue_tag (GameplayTag) –
context (GameplayEffectContextHandle) –
remove_on_ability_end (bool) –
- 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:
gameplay_cue_tag (GameplayTag) –
gameplay_cue_parameter (GameplayCueParameters) –
remove_on_ability_end (bool) –
- 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:
- apply_gameplay_effect_spec_to_target(effect_spec_handle, target_data) Array[ActiveGameplayEffectHandle] ¶
Apply a previously created gameplay effect spec to a target
- Parameters:
effect_spec_handle (GameplayEffectSpecHandle) –
target_data (GameplayAbilityTargetDataHandle) –
- Return type:
- 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:
- Return type:
- 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:
target_data (GameplayAbilityTargetDataHandle) –
gameplay_effect_level (int32) –
stacks (int32) –
- Return type:
- can_activate_ability(actor_info, handle) GameplayTagContainer or None ¶
Returns true if this ability can be activated right now. Has no side effects
- Parameters:
actor_info (GameplayAbilityActorInfo) –
handle (GameplayAbilitySpecHandle) –
- Returns:
relevant_tags (GameplayTagContainer):
- Return type:
GameplayTagContainer or None
- 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) –
- 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:
- 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.
- 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.
- 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.
- property current_activation_info: GameplayAbilityActivationInfo¶
[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:
- property current_event_data: GameplayEventData¶
[Read-Only] Current Event Data: Information specific to this instance of the ability, if it was activated by an event
- Type:
- 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:
gameplay_cue_tag (GameplayTag) –
context (GameplayEffectContextHandle) –
- execute_gameplay_cue_with_params(gameplay_cue_tag, gameplay_cue_parameters) None ¶
Invoke a gameplay cue on the ability owner, with extra parameters
- Parameters:
gameplay_cue_tag (GameplayTag) –
gameplay_cue_parameters (GameplayCueParameters) –
- 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:
handle (GameplayAbilitySpecHandle) –
actor_info (GameplayAbilityActorInfo) –
- Return type:
int32
- get_ability_system_component_from_actor_info() AbilitySystemComponent ¶
Returns the AbilitySystemComponent that is activating this ability
- Return type:
- get_actor_info() GameplayAbilityActorInfo ¶
Returns the actor info associated with this ability, has cached pointers to useful objects
- Return type:
- get_avatar_actor_from_actor_info() Actor ¶
Returns the physical actor that is executing this ability. May be null
- Return type:
- 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:
- get_cooldown_time_remaining() float ¶
Returns the time in seconds remaining on the currently active cooldown.
- Return type:
- get_current_montage() AnimMontage ¶
Returns the currently playing montage for this ability, if any
- Return type:
- get_current_source_object() Object ¶
Retrieves the SourceObject associated with this ability. Can only be called on instanced abilities.
- Return type:
- 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:
- get_owning_actor_from_actor_info() Actor ¶
Returns the actor that owns this ability, which may not have a physical location
- Return type:
- get_owning_component_from_actor_info() SkeletalMeshComponent ¶
Convenience method for abilities to get skeletal mesh component - useful for aiming abilities
- Return type:
- get_source_object_bp(handle, actor_info) Object ¶
Retrieves the SourceObject associated with this ability. Callable on non instanced
- Parameters:
handle (GameplayAbilitySpecHandle) –
actor_info (GameplayAbilityActorInfo) –
- Return type:
- 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:
- 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:
- make_target_location_info_from_owner_actor() GameplayAbilityTargetingLocationInfo ¶
Creates a target location from where the owner avatar is
- Return type:
- 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:
- property mark_pending_kill_on_ability_end: bool¶
[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
- 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:
with_asset_tags (GameplayTagContainer) –
stacks_to_remove (int32) –
- 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:
with_granted_tags (GameplayTagContainer) –
stacks_to_remove (int32) –
- remove_gameplay_effect_from_owner_with_handle(handle, stacks_to_remove=-1) None ¶
Removes GameplayEffect from owner that match the given handle
- Parameters:
handle (ActiveGameplayEffectHandle) –
stacks_to_remove (int32) –
- 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:
event_tag (GameplayTag) –
payload (GameplayEventData) –
- 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:
actor_info (GameplayAbilityActorInfo) –
payload (GameplayEventData) –
- Return type: