ASComponent

Inherits: Node

Core component for managing abilities, attributes, and effects.

Description

The [ASComponent] (ASC) is the central hub for an actor’s logic. It handles the lifecycle of abilities, applies effects, and tracks attribute values. Must be a child of [CharacterBody2D] or [CharacterBody3D].

Properties

Type	Name	Default
`ASContainer`	container
The archetype blueprint for this actor.
`ASStateSnapshot`	snapshot_state
The resource used for capturing and restoring the component’s state. Primarily used for players and persistence.

Methods

Return	Name
`float`	_on_calculate_custom_magnitude( effect_spec: `ASEffectSpec`, modifier_index: `int`) `virtual const`
Virtual callback for computing custom magnitude values for effect modifiers.
`void`	add_attribute_set( set: `ASAttributeSet`)
Adds a unique instance of the attribute set to this component.
`void`	add_tag( tag: `StringName`)
Adds a tag to the actor.
`void`	apply_container( container: `ASContainer`, level: `int` = 1)
Initializes the component with an archetype blueprint (AttributeSet, Catalog, and Initial Effects).
`void`	apply_effect_by_resource( effect: `ASEffect`, level: `float` = 1.0, target_node: `Object` = null)
Directly applies an effect to this actor without checking activation requirements.
`void`	apply_effect_by_tag( tag: `StringName`, level: `float` = 1.0, target_node: `Object` = null)
Directly applies an effect from the container catalog to this actor by its tag, without checking activation requirements.
`void`	apply_effect_spec_to_self( spec: `ASEffectSpec`)
Applies an already-built effect spec to this actor. Validates all four tag conditions on the effect resource before applying (required_all, required_any, blocked_any, blocked_all). Emits [signal effect_failed] if any tag check fails.
`void`	apply_effect_spec_to_target( spec: `ASEffectSpec`, target: `ASComponent`)
Applies an effect instance to another target component.
`void`	apply_package( package: `ASPackage`, level: `float` = 1.0, source_component: `ASComponent` = null)
Unpacks and applies all effects and cues contained in the [ASPackage] to this component.
`void`	apply_snapshot( tick: `int`)
Restores the component’s state (attributes, tags, and active effects) from a previously captured snapshot. Attempts to recover from the internal lightweight cache (ASStateCache) first. This cache is a circular buffer that stores the last 128 ticks automatically. If the requested tick is older than the buffer capacity, the system falls back to the assigned [member snapshot_state] resource.
`float`	calculate_effect_duration( spec: `ASEffectSpec`) `const`
Calculates the duration of an effect spec, considering custom magnitude overrides.
`float`	calculate_modifier_magnitude( spec: `ASEffectSpec`, modifier_index: `int`) `const`
Calculates the magnitude of a modifier within an effect spec.
`bool`	can_activate_ability_by_resource( ability: `ASAbility`)
Returns true if the specified ability resource is unlocked and its requirements (tags, costs, cooldown) are met.
`bool`	can_activate_ability_by_tag( tag: `StringName`)
Returns true if an ability with the specified tag is unlocked and its requirements are met.
`bool`	can_activate_cue_by_resource( cue: `ASCue`)
Checks if the specified cue resource can be activated. Verifies all four tag conditions: [member ASCue.activation_required_all_tags] (AND), [member ASCue.activation_required_any_tags] (OR), [member ASCue.activation_blocked_any_tags] (OR), and [member ASCue.activation_blocked_all_tags] (AND).
`bool`	can_activate_cue_by_tag( tag: `StringName`)
Checks if a cue with the specified tag can be activated.
`bool`	can_activate_effect_by_resource( effect: `ASEffect`)
Checks if the specified effect resource can be applied to this component. Verifies all four tag conditions: [member ASEffect.activation_required_all_tags] (AND), [member ASEffect.activation_required_any_tags] (OR), [member ASEffect.activation_blocked_any_tags] (OR), and [member ASEffect.activation_blocked_all_tags] (AND). Also verifies attribute requirements.
`bool`	can_activate_effect_by_tag( tag: `StringName`)
Checks if an effect with the specified tag can be applied.
`void`	cancel_ability_by_resource( ability: `ASAbility`)
Cancels the execution of the specified ability resource.
`void`	cancel_ability_by_tag( tag: `StringName`)
Cancels all active abilities that match the specified tag.
`void`	cancel_all_abilities( )
Forcefully cancels all currently active abilities.
`void`	cancel_cue_by_resource( cue: `ASCue`)
Cancels the specified cue resource.
`void`	cancel_cue_by_tag( tag: `StringName`)
Cancels all active cues that match the specified tag.
`void`	cancel_effect_by_resource( effect: `ASEffect`)
Cancels the specified effect resource.
`void`	cancel_effect_by_tag( tag: `StringName`)
Cancels all active effects that match the specified tag.
`void`	capture_snapshot( )
Captures the current state of attributes and tags. The state is always pushed to an internal circular buffer (lightweight cache) for multiplayer prediction and rollback. If [member snapshot_state] is assigned, it also populates that resource for persistent storage or long-term synchronization.
`void`	clear_ability_history( )
Clears the chronological buffer of ability activation events on this component.
`void`	clear_all_history( )
Clears every chronological and historical buffer on this component (Tags, Attributes, Abilities, Effects, Cues, and Events).
`void`	clear_attribute_history( )
Clears the chronological buffer of attribute changes on this component.
`void`	clear_conditional_history( )
Clears the short-term historical buffer for [constant ASTagUtils.CONDITIONAL] tags on this component.
`void`	clear_cue_history( )
Clears the chronological buffer of visual cue events on this component.
`void`	clear_effect_history( )
Clears the chronological buffer of effect application and removal events on this component.
`void`	clear_effects( )
Removes all active effects from the actor immediately.
`void`	clear_event_history( )
Clears all events from the historical buffer.
`void`	clear_name_history( )
Clears the short-term historical buffer for [constant ASTagUtils.NAME] tags on this component.
`void`	clear_tag_history( )
Clears all short-term tag history buffers (NAME and CONDITIONAL) on the component.
`void`	confirm_ability_activation( tag: `StringName`)
Confirms a previously predicted ability activation (Server-side confirmation).
`void`	dispatch_event( tag: `StringName`, instigator: `Node` = null, magnitude: `float` = 0.0, custom_payload: `Dictionary` = {})
Dispatches a transient ASEventTag to this component. The event is broadcast to all listeners and stored in the short-term historical buffer ([method has_event_occurred]). This is the preferred way to signal non-persistent occurrences (e.g. Impact, Hit, Achievement).
`ASEffect`	find_effect_by_tag( tag: `StringName`) `const`
Searches the archetype container and all currently unlocked abilities to find the [ASEffect] resource associated with the given tag.
`float`	get_ability_cooldown_preview( tag: `StringName`) `const`
Retrieves the base cooldown defined in the ability resource catalog for preview purposes.
`float`	get_ability_cost_preview( tag: `StringName`, attribute: `StringName`) `const`
Retrieves the base cost for a specific attribute of an ability from the catalog. Useful for UI tooltips.
`float`	get_ability_duration_preview( tag: `StringName`) `const`
Retrieves the base duration defined in the ability resource catalog.
`Dictionary[]`	get_ability_history( lookback_sec: `float` = 1.0) `const`
Retrieves the buffer of ability lifecycle events (Started, Finished, etc.) within the requested timeframe. Each entry is a [Dictionary] representing an ASAbilityHistorical record.
`int`	get_ability_history_size( ) `const`
Returns the current size of the ability history buffer.
`ASAbilitySpec[]`	get_active_abilities( ) `const`
Returns a list of all abilities currently executing on this actor.
`ASCueSpec[]`	get_active_cues( ) `const`
Returns a list of all active feedback cues (VFX/SFX) currently running on this actor.
`ASEffectSpec[]`	get_active_effects( ) `const`
Returns a list of all active effect instances (buffs, debuffs, etc.) applied to this actor.
`Node`	get_animation_player( ) `const`
Returns the registered AnimationPlayer or AnimatedSprite node.
`float`	get_attribute_base_value_by_resource( attribute: `ASAttribute`) `const`
Returns the unmodified base value of the specified attribute resource.
`float`	get_attribute_base_value_by_tag( tag: `StringName`) `const`
Returns the unmodified base value of the attribute identified by the tag.
`Dictionary[]`	get_attribute_history( lookback_sec: `float` = 1.0) `const`
Retrieves chronological entries of attribute modifications within the requested timeframe. Each entry is a [Dictionary] representing an ASAttributeHistorical record.
`int`	get_attribute_history_size( ) `const`
Returns the current size of the attribute history buffer.
`float`	get_attribute_last_delta( attribute: `StringName`) `const`
Retrieves the final delta (change amount) for the specified attribute from the last historical entry. Returns 0.0 if no history exists for that attribute.
`float`	get_attribute_max_value( tag: `StringName`) `const`
Retrieves the maximum value (ceiling) defined for the attribute resource.
`float`	get_attribute_percent( tag: `StringName`) `const`
Returns the ratio of [method get_attribute_value_by_tag] to [method get_attribute_max_value]. Useful for health bars and resource gauges.
`ASAttributeSet[]`	get_attribute_sets( ) `const`
Returns the list of attribute sets attached to this component.
`float`	get_attribute_value_by_resource( attribute: `ASAttribute`) `const`
Returns the current value of the specified attribute resource.
`float`	get_attribute_value_by_tag( tag: `StringName`) `const`
Returns the current value of the attribute identified by the tag.
`Node`	get_audio_player( ) `const`
Returns the registered AudioStreamPlayer node.
`int`	get_conditional_history_size( ) `const`
Returns the number of entries currently stored in the conditional history buffer.
`float`	get_cooldown_percent( ability_tag: `StringName`) `const`
Returns the completion ratio of the cooldown (remaining / initial duration). Returns 0.0 if not on cooldown.
`float`	get_cooldown_remaining( ability_tag: `StringName`) `const`
Returns the time remaining for a specific cooldown tag.
`Dictionary[]`	get_cue_history( lookback_sec: `float` = 1.0) `const`
Retrieves the buffer of visual cue events occurred within the last [param lookback_sec] seconds. Each entry is a [Dictionary] representing an ASCueHistorical record.
`int`	get_cue_history_size( ) `const`
Returns the current size of the cue history buffer.
`ASCue`	get_cue_resource( tag: `StringName`) `const`
Returns the cue resource associated with the specified tag.
`Dictionary[]`	get_effect_history( lookback_sec: `float` = 1.0) `const`
Retrieves the buffer of effect lifecycle events within the requested timeframe. Each entry is a [Dictionary] representing an ASEffectHistorical record.
`int`	get_effect_history_size( ) `const`
Returns the current size of the effect history buffer.
`int`	get_event_history_size( ) `const`
Returns the number of entries currently stored in the event history buffer.
`int`	get_name_history_size( ) `const`
Returns the number of entries currently stored in the name history buffer.
`Node`	get_node_ptr( name: `StringName`) `const`
Returns a registered node by its alias.
`ASTagSpec`	get_owned_tags( ) `const`
Exposes the internal tag manager [ASTagSpec] for detailed inspections. Use this to bypass the high-level API and access refcounts or recursive hierarchy queries directly.
`ASCue[]`	get_registered_cues( ) `const`
Returns the list of all cue resources currently registered with this component.
`StringName[]`	get_tags( ) `const`
Returns an array of all tags currently owned by the actor.
`ASAbilitySpec[]`	get_unlocked_abilities( ) `const`
Returns a list of all abilities currently unlocked for this actor.
`bool`	has_active_effect_by_resource( effect: `ASEffect`) `const`
Returns true if the specified effect resource is currently active.
`bool`	has_active_effect_by_tag( tag: `StringName`) `const`
Returns true if an effect with the specified tag is currently active.
`bool`	has_attribute_by_resource( attribute: `ASAttribute`) `const`
Returns true if the component has the specified attribute resource.
`bool`	has_attribute_by_tag( tag: `StringName`) `const`
Returns true if the component has an attribute with the specified tag.
`bool`	has_event_occurred( tag: `StringName`, lookback_sec: `float` = 1.0) `const`
Checks the internal historical buffer for a specific event tag that occurred within the last [param lookback_sec] seconds. Highly efficient for reactive logic and ability requirements.
`bool`	has_tag( tag: `StringName`) `const`
Checks for tag presence.
`bool`	is_ability_active( tag: `StringName`) `const`
Returns true if an ability with the specified tag is currently executing.
`bool`	is_ability_unlocked( tag: `StringName`) `const`
Returns true if the ability tag is present in the unlocked list of the component.
`bool`	is_montage_playing( name: `StringName`, target: `Node` = null) `const`
Returns true if a montage (animation) is currently playing on the target.
`bool`	is_on_cooldown( ability_tag: `StringName`) `const`
Checks if a specific tag is on cooldown.
`void`	lock_ability_by_resource( ability: `ASAbility`)
Removes the ability from the unlocked list and cancels it if active.
`void`	lock_ability_by_tag( tag: `StringName`)
Removes the ability matching the tag from the unlocked list.
`ASEffectSpec`	make_outgoing_spec( effect: `ASEffect`, level: `float` = 1.0, target_node: `Object` = null)
Creates a validated effect instance.
`void`	play_montage( name: `StringName`, target: `Node` = null)
Plays a montage (animation) on a specific target node.
`void`	play_sound( sound: `AudioStream`, target: `Node` = null)
Plays a sound stream on a specific target node.
`void`	register_cue_resource( cue: `ASCue`)
Registers a cue resource for runtime lookup.
`void`	register_node( name: `StringName`, node: `Node`)
Registers a node with an alias for use by cues and effects.
`void`	remove_active_effect( spec: `ASEffectSpec`)
Forcefully removes an active effect instance.
`void`	remove_all_tags( )
Removes all tags from the component and triggers associated events and ability triggers.
`void`	remove_effect_by_resource( effect: `ASEffect`)
Removes all active instances of the given effect resource.
`void`	remove_effect_by_tag( tag: `StringName`)
Removes all active effects that match the given tag.
`void`	remove_tag( tag: `StringName`)
Removes a tag.
`void`	request_activate_ability( tag: `StringName`)
Requests the server to activate an ability. Used for client-side prediction and RPC communication.
`void`	rollback_to_tick( tick: `int`)
`void`	set_animation_player( node: `Node`)
Registers the node to be used for animations (AnimationPlayer or AnimatedSprite).
`void`	set_attribute_base_value_by_resource( attribute: `ASAttribute`, value: `float`)
Directly sets the base value of the specified attribute resource.
`void`	set_attribute_base_value_by_tag( tag: `StringName`, value: `float`)
Directly sets the base value of an attribute by its tag.
`void`	set_audio_player( node: `Node`)
Registers the node to be used for audio (AudioStreamPlayer).
`void`	start_cooldown( ability_tag: `StringName`, duration: `float`, tags: `StringName[]`)
Manually starts a cooldown with a specific tag and duration.
`void`	tick( delta: `float`)
Manually advances the component’s internal simulation by [param delta] seconds. This is called automatically during the physics step.
`bool`	try_activate_ability_by_resource( ability: `ASAbility`, target_node: `Object` = null, parent_id: `int` = 0)
Attempts to activate an ability using its resource reference. Supports hierarchical linking via [param parent_id].
`bool`	try_activate_ability_by_tag( tag: `StringName`, target_node: `Object` = null)
Attempts to activate an ability by its unique tag.
`bool`	try_activate_cue_by_resource( cue: `ASCue`, data: `Dictionary` = {}, target_node: `Object` = null)
Attempts to activate a cue resource if requirements are met.
`bool`	try_activate_cue_by_tag( tag: `StringName`, data: `Dictionary` = {}, target_node: `Object` = null)
Attempts to activate a cue by tag if requirements are met.
`bool`	try_activate_effect_by_resource( effect: `ASEffect`, level: `float` = 1.0, target_node: `Object` = null)
Attempts to apply an effect resource if requirements are met.
`bool`	try_activate_effect_by_tag( tag: `StringName`, level: `float` = 1.0, target_node: `Object` = null)
Attempts to apply an effect by tag if requirements are met.
`void`	unlock_ability_by_resource( ability: `ASAbility`)
Adds an ability resource to the unlocked list in the primary attribute set.
`void`	unlock_ability_by_tag( tag: `StringName`)
Finds the ability in the catalog and adds it to the unlocked list.
`void`	unregister_cue_resource( tag: `StringName`)
Unregisters the cue resource associated with the specified tag.
`void`	unregister_node( name: `StringName`)
Unregisters the node alias.

Signals

ability_activated( ability_spec: Object)
Emitted when an ability starts.
ability_ended( ability_spec: Object, was_cancelled: bool)
Emitted when an ability stops.
ability_failed( ability_name: StringName, reason: String)
Emitted when an ability fails to activate, providing the reason.
attribute_changed( attribute_name: StringName, old_value: float, new_value: float)
Emitted on stat changes.
cooldown_ended( ability_tag: StringName)
Emitted when a cooldown duration reaches zero.
cooldown_started( ability_tag: StringName, duration: float)
Emitted when a new cooldown starts.
cue_failed( cue_name: StringName, reason: String)
Emitted when a cue fails to activate.
effect_applied( effect_spec: Object)
Emitted when an effect is successfully applied to the component.
effect_failed( effect_name: StringName, reason: String)
Emitted when an effect fails to apply.
effect_removed( effect_spec: Object)
Emitted when an active effect is removed.
event_received( tag: StringName, instigator: Object, magnitude: float, custom_payload: Dictionary)
Emitted when an ASEventTag is dispatched to this component. Used for transient signals.
tag_changed( tag_name: StringName, is_present: bool)
Emitted when persistent tags (states) are added or removed.
tag_event_received( event_tag: StringName, data: Dictionary)
Emitted when a tag-based event containing a data payload is received. Similar to [signal event_received] but optimized for logic requiring specific data dictionaries without instigator or magnitude metadata.

ASDelivery