unreal.AbilitySystemComponent

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

Bases: GameplayTasksComponent

The core ActorComponent for interfacing with the GameplayAbilities System

C++ Source:

  • Plugin: GameplayAbilities

  • Module: GameplayAbilities

  • File: AbilitySystemComponent.h

Editor Properties: (see get_editor_property/set_editor_property)

  • activatable_abilities (GameplayAbilitySpecContainer): [Read-Write] The abilities we can activate.

    -This will include CDOs for non instanced abilities and per-execution instanced abilities. -Actor-instanced abilities will be the actual instance (not CDO)

    This array is not vital for things to work. It is a convenience thing for ‘giving abilities to the actor’. But abilities could also work on things without an AbilitySystemComponent. For example an ability could be written to execute on a StaticMeshActor. As long as the ability doesn’t require instancing or anything else that the AbilitySystemComponent would provide, then it doesn’t need the component to function.

  • affected_anim_instance_tag (Name): [Read-Write] The linked Anim Instance that this component will play montages in. Use NAME_None for the main anim instance.

  • asset_user_data (Array[AssetUserData]): [Read-Write] Array of user data stored with the component

  • auto_activate (bool): [Read-Write] Whether the component is activated at creation or must be explicitly activated.

  • can_ever_affect_navigation (bool): [Read-Write] Whether this component can potentially influence navigation

  • component_tags (Array[Name]): [Read-Write] Array of tags that can be used for grouping and categorizing. Can also be accessed from scripting.

  • default_starting_data (Array[AttributeDefaults]): [Read-Write]

  • editable_when_inherited (bool): [Read-Write] True if this component can be modified when it was inherited from a parent actor class

  • is_editor_only (bool): [Read-Write] If true, the component will be excluded from non-editor builds

  • on_claimed_resources_change (OnClaimedResourcesChangeSignature): [Read-Write]

  • on_component_activated (ActorComponentActivatedSignature): [Read-Write] Called when the component has been activated, with parameter indicating if it was from a reset

  • on_component_deactivated (ActorComponentDeactivateSignature): [Read-Write] Called when the component has been deactivated

  • primary_component_tick (ActorComponentTickFunction): [Read-Write] Main tick function for the Component

  • replicate_using_registered_sub_object_list (bool): [Read-Write] When true the replication system will only replicate the registered subobjects list When false the replication system will instead call the virtual ReplicateSubObjects() function where the subobjects need to be manually replicated.

  • replicates (bool): [Read-Write] Is this component currently replicating? Should the network code consider it for replication? Owning Actor must be replicating first!

property activatable_abilities: GameplayAbilitySpecContainer
[Read-Only] The abilities we can activate.

-This will include CDOs for non instanced abilities and per-execution instanced abilities. -Actor-instanced abilities will be the actual instance (not CDO)

This array is not vital for things to work. It is a convenience thing for ‘giving abilities to the actor’. But abilities could also work on things without an AbilitySystemComponent. For example an ability could be written to execute on a StaticMeshActor. As long as the ability doesn’t require instancing or anything else that the AbilitySystemComponent would provide, then it doesn’t need the component to function.

Type:

(GameplayAbilitySpecContainer)

property affected_anim_instance_tag: Name

[Read-Write] The linked Anim Instance that this component will play montages in. Use NAME_None for the main anim instance.

Type:

(Name)

apply_gameplay_effect_spec_to_self(spec_handle) → ActiveGameplayEffectHandle

Applies a previously created gameplay effect spec to this component

Parameters:

spec_handle (GameplayEffectSpecHandle) –

Return type:

ActiveGameplayEffectHandle

apply_gameplay_effect_spec_to_target(spec_handle, target) → ActiveGameplayEffectHandle

Applies a previously created gameplay effect spec to a target

Parameters:
Return type:

ActiveGameplayEffectHandle

apply_gameplay_effect_to_self(gameplay_effect_class, level, effect_context) → ActiveGameplayEffectHandle

Apply a gameplay effect to self

Parameters:
Return type:

ActiveGameplayEffectHandle

apply_gameplay_effect_to_target(gameplay_effect_class, target, level, context) → ActiveGameplayEffectHandle

Apply a gameplay effect to passed in target

Parameters:
Return type:

ActiveGameplayEffectHandle

clear_ability(handle) → None

Removes the specified ability. This will be ignored if the actor is not authoritative.

Parameters:

handle (GameplayAbilitySpecHandle) – Ability Spec Handle of the ability we want to remove

clear_all_abilities() → None

Wipes all ‘given’ abilities. This will be ignored if the actor is not authoritative.

clear_all_abilities_with_input_id(input_id=0) → None

Clears all abilities bound to a given Input ID This will be ignored if the actor is not authoritative

Parameters:

input_id (int32) – The numeric Input ID of the abilities to remove

find_all_abilities_matching_query(query) → Array[GameplayAbilitySpecHandle]

Returns an array with all abilities that match the provided Gameplay Tag Query

Parameters:

query (GameplayTagQuery) – Gameplay Tag Query to match

Returns:

out_ability_handles (Array[GameplayAbilitySpecHandle]): This array will be filled with matching Ability Spec Handles

Return type:

Array[GameplayAbilitySpecHandle]

find_all_abilities_with_input_id(input_id=0) → Array[GameplayAbilitySpecHandle]

Returns an array with all abilities bound to an Input ID value

Parameters:

input_id (int32) – The Input ID to match

Returns:

out_ability_handles (Array[GameplayAbilitySpecHandle]): This array will be filled with matching Ability Spec Handles

Return type:

Array[GameplayAbilitySpecHandle]

find_all_abilities_with_tags(tags, exact_match=True) → Array[GameplayAbilitySpecHandle]

Returns an array with all abilities that match the provided tags

Parameters:
Returns:

out_ability_handles (Array[GameplayAbilitySpecHandle]): This array will be filled with matching Ability Spec Handles

Return type:

Array[GameplayAbilitySpecHandle]

get_active_effects(query) → Array[ActiveGameplayEffectHandle]

Returns list of active effects, for a query

Parameters:

query (GameplayEffectQuery) –

Return type:

Array[ActiveGameplayEffectHandle]

get_active_effects_with_all_tags(tags) → Array[ActiveGameplayEffectHandle]

Returns list of active effects that have all of the passed in tags

Parameters:

tags (GameplayTagContainer) –

Return type:

Array[ActiveGameplayEffectHandle]

get_all_abilities() → Array[GameplayAbilitySpecHandle]

Returns an array with all granted ability handles NOTE: currently this doesn’t include abilities that are mid-activation

Returns:

out_ability_handles (Array[GameplayAbilitySpecHandle]): This array will be filled with the granted Ability Spec Handles

Return type:

Array[GameplayAbilitySpecHandle]

get_all_attributes() → Array[GameplayAttribute]

Returns a list of all attributes for this abilty system component

Returns:

out_attributes (Array[GameplayAttribute]):

Return type:

Array[GameplayAttribute]

get_attribute_set(attribute_set_class) → AttributeSet

Returns a reference to the Attribute Set instance, if one exists in this component

Parameters:

attribute_set_class (type(Class)) – The type of attribute set to look for

Return type:

AttributeSet

get_effect_context() → GameplayEffectContextHandle

deprecated: ‘get_effect_context’ was renamed to ‘make_effect_context’.

get_gameplay_attribute_value(attribute) -> (float, found=bool)

Returns the current value of the given gameplay attribute, or zero if the attribute is not found. NOTE: This doesn’t take predicted gameplay effect modifiers into consideration, so the value may not be accurate on clients at all times.

Parameters:

attribute (GameplayAttribute) – The gameplay attribute to query

Returns:

found (bool): Set to true if the attribute exists in this component

Return type:

bool

get_gameplay_effect_count(source_gameplay_effect, optional_instigator_filter_component, enforce_on_going_check=True) → int32

Get the count of the specified source effect on the ability system component. For non-stacking effects, this is the sum of all active instances. For stacking effects, this is the sum of all valid stack counts. If an instigator is specified, only effects from that instigator are counted.

Parameters:

  • source_gameplay_effect (type(Class)) – Effect to get the count of

  • optional_instigator_filter_component (AbilitySystemComponent) – If specified, only count effects applied by this ability system component

  • enforce_on_going_check (bool) –

Returns:

Count of the specified source effect

Return type:

int32

get_gameplay_effect_count_if_loaded(soft_source_gameplay_effect, optional_instigator_filter_component, enforce_on_going_check=True) → int32

Get the count of the specified source effect on the ability system component. For non-stacking effects, this is the sum of all active instances. For stacking effects, this is the sum of all valid stack counts. If an instigator is specified, only effects from that instigator are counted.

Parameters:

  • soft_source_gameplay_effect (Class) – Effect to get the count of. If this is not currently loaded, the count is 0

  • optional_instigator_filter_component (AbilitySystemComponent) – If specified, only count effects applied by this ability system component

  • enforce_on_going_check (bool) –

Returns:

Count of the specified source effect

Return type:

int32

get_gameplay_effect_magnitude(handle, attribute) → float

Raw accessor to ask the magnitude of a gameplay effect, not necessarily always correct. How should outside code (UI, etc) ask things like ‘how much is this gameplay effect modifying my damage by’ (most likely we want to catch this on the backend - when damage is applied we can get a full dump/history of how the number got to where it is. But still we may need polling methods like below (how much would my damage be)

Parameters:
Return type:

float

get_gameplay_tag_count(gameplay_tag) → int32

Returns the current count of the given gameplay tag. This includes both loose tags, and tags granted by gameplay effects and abilities. This function can be called on the client, but it may not display the most current count on the server.

Parameters:

gameplay_tag (GameplayTag) – The gameplay tag to query

Return type:

int32

get_owned_gameplay_tags() → GameplayTagContainer

Get any owned gameplay tags on the asset

Returns:

tag_container (GameplayTagContainer):

Return type:

GameplayTagContainer

get_user_ability_activation_inhibited() → bool

This is meant to be used to inhibit activating an ability from an input perspective. (E.g., the menu is pulled up, another game mechanism is consuming all input, etc) This should only be called on locally owned players. This should not be used to game mechanics like silences or disables. Those should be done through gameplay effects.

Return type:

bool

give_ability(ability_class, level=0, input_id=-1) → GameplayAbilitySpecHandle

Grants a Gameplay Ability and returns its handle. This will be ignored if the actor is not authoritative.

Parameters:

  • ability_class (type(Class)) – Type of ability to grant

  • level (int32) – Level to grant the ability at

  • input_id (int32) – Input ID value to bind ability activation to.

Return type:

GameplayAbilitySpecHandle

give_ability_and_activate_once(ability_class, level=0, input_id=-1) → GameplayAbilitySpecHandle

Grants a Gameplay Ability, activates it once, and removes it. This will be ignored if the actor is not authoritative.

Parameters:

  • ability_class (type(Class)) – Type of ability to grant

  • level (int32) – Level to grant the ability at

  • input_id (int32) – Input ID value to bind ability activation to.

Return type:

GameplayAbilitySpecHandle

has_all_matching_gameplay_tags(tag_container) → bool

Check if the asset has gameplay tags that matches against all of the specified tags (expands to include parents of asset tags)

Parameters:

tag_container (GameplayTagContainer) – Tag container to check for a match

Returns:

True if the asset has matches all of the gameplay tags, will be true if container is empty

Return type:

bool

has_any_matching_gameplay_tags(tag_container) → bool

Check if the asset has gameplay tags that matches against any of the specified tags (expands to include parents of asset tags)

Parameters:

tag_container (GameplayTagContainer) – Tag container to check for a match

Returns:

True if the asset has matches any of the gameplay tags, will be false if container is empty

Return type:

bool

has_matching_gameplay_tag(tag_to_check) → bool

Check if the asset has a gameplay tag that matches against the specified tag (expands to include parents of asset tags)

Parameters:

tag_to_check (GameplayTag) – Tag to check for a match

Returns:

True if the asset has a gameplay tag that matches, false if not

Return type:

bool

init_stats(attributes, data_table) → None

K2 Init Stats

Parameters:
input_cancel() → None

Sends a local player Input Cancel event, notifying abilities

input_confirm() → None

Sends a local player Input Confirm event, notifying abilities

is_gameplay_cue_active(gameplay_cue_tag) → bool

Allows polling to see if a GameplayCue is active. We expect most GameplayCue handling to be event based, but some cases we may need to check if a GamepalyCue is active (Animation Blueprint for example)

Parameters:

gameplay_cue_tag (GameplayTag) –

Return type:

bool

make_effect_context() → GameplayEffectContextHandle

Create an EffectContext for the owner of this AbilitySystemComponent

Return type:

GameplayEffectContextHandle

make_outgoing_spec(gameplay_effect_class, level, context) → GameplayEffectSpecHandle

Get an outgoing GameplayEffectSpec that is ready to be applied to other things.

Parameters:
Return type:

GameplayEffectSpecHandle

press_input_id(input_id) → None

  • Sends a local player Input Pressed event with the provided Input ID, notifying any bound abilities

Parameters:

input_id (int32) – The Input ID to match

release_input_id(input_id) → None

Sends a local player Input Released event with the provided Input ID, notifying any bound abilities

Parameters:

input_id (int32) – The Input ID to match

remove_active_effects_with_applied_tags(tags) → int32

Removes all active effects that apply any of the tags in Tags

Parameters:

tags (GameplayTagContainer) –

Return type:

int32

remove_active_effects_with_granted_tags(tags) → int32

Removes all active effects that grant any of the tags in Tags

Parameters:

tags (GameplayTagContainer) –

Return type:

int32

remove_active_effects_with_source_tags(tags) → int32

Removes all active effects with captured source tags that contain any of the tags in Tags

Parameters:

tags (GameplayTagContainer) –

Return type:

int32

remove_active_effects_with_tags(tags) → int32

Removes all active effects that contain any of the tags in Tags

Parameters:

tags (GameplayTagContainer) –

Return type:

int32

remove_active_gameplay_effect(handle, stacks_to_remove=-1) → bool

Removes GameplayEffect by Handle. StacksToRemove=-1 will remove all stacks.

Parameters:
Return type:

bool

remove_active_gameplay_effect_by_source_effect(gameplay_effect, instigator_ability_system_component, stacks_to_remove=-1) → None

Remove active gameplay effects whose backing definition are the specified gameplay effect class

Parameters:

  • gameplay_effect (type(Class)) – Class of gameplay effect to remove; Does nothing if left null

  • instigator_ability_system_component (AbilitySystemComponent) – If specified, will only remove gameplay effects applied from this instigator ability system component

  • stacks_to_remove (int32) – Number of stacks to remove, -1 means remove all

set_active_gameplay_effect_level(active_handle, new_level) → None

Updates the level of an already applied gameplay effect. The intention is that this is ‘seemless’ and doesnt behave like removing/reapplying

Parameters:
set_active_gameplay_effect_level_using_query(query, new_level) → None

Updates the level of an already applied gameplay effect. The intention is that this is ‘seemless’ and doesnt behave like removing/reapplying

Parameters:
set_user_ability_activation_inhibited(new_inhibit) → None

Disable or Enable a local user from being able to activate abilities. This should only be used for input/UI etc related inhibition. Do not use for game mechanics.

Parameters:

new_inhibit (bool) –

target_cancel() → None

Any active targeting actors will be stopped and canceled, not returning any targeting data

target_confirm() → None

Any active targeting actors will be told to stop and return current targeting data

try_activate_abilities_by_tag(gameplay_tag_container, allow_remote_activation=True) → bool

Attempts to activate every gameplay ability that matches the given tag and DoesAbilitySatisfyTagRequirements(). Returns true if anything attempts to activate. Can activate more than one ability and the ability may fail later. If bAllowRemoteActivation is true, it will remotely activate local/server abilities, if false it will only try to locally activate abilities.

Parameters:
Return type:

bool

try_activate_ability(ability_to_activate, allow_remote_activation=True) → bool

Attempts to activate the given ability, will check costs and requirements before doing so. Returns true if it thinks it activated, but it may return false positives due to failure later in activation. If bAllowRemoteActivation is true, it will remotely activate local/server abilities, if false it will only try to locally activate the ability

Parameters:
Return type:

bool

try_activate_ability_by_class(ability_to_activate, allow_remote_activation=True) → bool

Attempts to activate the ability that is passed in. This will check costs and requirements before doing so. Returns true if it thinks it activated, but it may return false positives due to failure later in activation. If bAllowRemoteActivation is true, it will remotely activate local/server abilities, if false it will only try to locally activate the ability

Parameters:

  • ability_to_activate (type(Class)) –

  • allow_remote_activation (bool) –

Return type:

bool

try_activate_ability_by_tag(gameplay_tag_container: GameplayTagContainer, allow_remote_activation: bool = True) → bool

deprecated: ‘try_activate_ability_by_tag’ was renamed to ‘try_activate_abilities_by_tag’.

update_active_gameplay_effect_set_by_caller_magnitude(active_handle, set_by_caller_tag, new_value) → None

Dynamically update the set-by-caller magnitude for an active gameplay effect

Parameters:
update_active_gameplay_effect_set_by_caller_magnitudes(active_handle, new_set_by_caller_values) → None

Dynamically update multiple set-by-caller magnitudes for an active gameplay effect

Parameters: