ASTagUtils

Inherits: RefCounted

Utility functions for tag type validation, creation, and historical queries.

Description

ASTagUtils provides comprehensive helper functions for working with Ability System tags. Includes type validation, automatic type detection from naming conventions, factory methods, and powerful historical query APIs for all three tag types.

Features three specialized historical namespaces:

NameHistory: Queries for NAME tags (State.Stunned, Class.Warrior)
ConditionalHistory: Queries for CONDITIONAL tags (Can.Parried, Immune.Fire)
EventHistory: Enhanced queries for EVENT tags (Event.Damage, Event.Ability.Activated)
UnifiedHistory: Cross-type queries and debug utilities

These utilities follow the BUSINESS_RULES.md conventions for tag naming and help maintain type safety across the system with full historical tracking.

Methods

Return	Name
`int`	cond_count_additions( tag: `StringName`, target: `Node`, lookback_sec: `float` = 1.0) `static`
Counts how many times a specific [constant CONDITIONAL] tag was added to the target within the last [param lookback_sec] seconds.
`int`	cond_count_removals( tag: `StringName`, target: `Node`, lookback_sec: `float` = 1.0) `static`
Counts how many times a specific [constant CONDITIONAL] tag was removed from the target within the last [param lookback_sec] seconds.
`Array`	cond_get_recent_additions( target: `Node`, lookback_sec: `float` = 1.0) `static`
Returns an array of conditional tag names that were added to the target within the last [param lookback_sec] seconds.
`Array`	cond_get_recent_changes( target: `Node`, lookback_sec: `float` = 1.0) `static`
Returns an array of all conditional tag events (additions and removals) that occurred within the last [param lookback_sec] seconds.
`Array`	cond_get_recent_removals( target: `Node`, lookback_sec: `float` = 1.0) `static`
Returns an array of conditional tag names that were removed from the target within the last [param lookback_sec] seconds.
`bool`	cond_had_tag( tag: `StringName`, target: `Node`, lookback_sec: `float` = 1.0) `static`
Returns true if the target had the specified conditional tag at any point during the last [param lookback_sec] seconds.
`bool`	cond_was_tag_added( tag: `StringName`, target: `Node`, lookback_sec: `float` = 1.0) `static`
Returns true if the specified conditional tag was added to the target within the last [param lookback_sec] seconds.
`bool`	cond_was_tag_removed( tag: `StringName`, target: `Node`, lookback_sec: `float` = 1.0) `static`
Returns true if the specified conditional tag was removed from the target within the last [param lookback_sec] seconds.
`int`	detect_tag_type( tag: `StringName`) `static`
Detects tag type from naming convention. Event.* -> EVENT, Can.* or Immune.* -> CONDITIONAL, others -> NAME.
`int`	event_count_occurrences( tag: `StringName`, target: `Node`, lookback_sec: `float` = 1.0) `static`
Returns the number of times the specified event occurred on the target within the last [param lookback_sec] seconds.
`bool`	event_did_occur( tag: `StringName`, target: `Node`, lookback_sec: `float` = 1.0) `static`
Returns true if the specified event occurred on the target within the last [param lookback_sec] seconds.
`Array`	event_get_all_recent_events( target: `Node`, lookback_sec: `float` = 1.0) `static`
Returns a list of all event entries that occurred on the target within the last [param lookback_sec] seconds.
`Dictionary`	event_get_last_data( tag: `StringName`, target: `Node`) `static`
Retrieves the data payload from the most recent occurrence of the specified event tag.
`Node`	event_get_last_instigator( tag: `StringName`, target: `Node`) `static`
Retrieves the instigator node from the most recent occurrence of the specified event tag.
`float`	event_get_last_magnitude( tag: `StringName`, target: `Node`) `static`
Retrieves the magnitude value from the most recent occurrence of the specified event tag.
`Array`	event_get_recent_events( tag: `StringName`, target: `Node`, lookback_sec: `float` = 1.0) `static`
Returns a list of recent entries for a specific event tag on the target.
`void`	history_dump( target: `Node`, lookback_sec: `float` = 5.0) `static`
Prints a formatted debug log of all historical entries for the target to the console.
`Array`	history_get_all_changes( target: `Node`, lookback_sec: `float` = 1.0) `static`
Returns a combined array of all Name and Conditional tag changes within the last [param lookback_sec] seconds.
`Array`	history_get_tag_history( tag: `StringName`, target: `Node`, lookback_sec: `float` = 1.0) `static`
Returns all historical entries (timeline) for a specific tag on the target.
`int`	history_get_total_size( target: `Node`) `static`
Returns the combined number of entries across all historical buffers for the target.
`bool`	history_was_tag_present( tag: `StringName`, target: `Node`, lookback_sec: `float` = 1.0) `static`
General purpose query to check if any version of the specified tag was present at any point within the target’s historical buffers.
`bool`	is_can_tag( tag: `StringName`) `static`
Returns true if tag name starts with “Can.”.
`bool`	is_class_tag( tag: `StringName`) `static`
Returns true if tag name starts with “Class.”.
`bool`	is_event_tag( tag: `StringName`) `static`
Returns true if tag name starts with “Event.”.
`bool`	is_immune_tag( tag: `StringName`) `static`
Returns true if tag name starts with “Immune.”.
`bool`	is_state_tag( tag: `StringName`) `static`
Returns true if tag name starts with “State.”.
`bool`	is_team_tag( tag: `StringName`) `static`
Returns true if tag name starts with “Team.”.
`int`	name_count_additions( tag: `StringName`, target: `Node`, lookback_sec: `float` = 1.0) `static`
Counts how many times a specific [constant NAME] tag was added to the target within the last [param lookback_sec] seconds.
`int`	name_count_removals( tag: `StringName`, target: `Node`, lookback_sec: `float` = 1.0) `static`
Counts how many times a specific [constant NAME] tag was removed from the target within the last [param lookback_sec] seconds.
`Array`	name_get_recent_additions( target: `Node`, lookback_sec: `float` = 1.0) `static`
Returns an array of name tag identifiers that were added to the target within the last [param lookback_sec] seconds.
`Array`	name_get_recent_changes( target: `Node`, lookback_sec: `float` = 1.0) `static`
Returns an array of all name tag events (additions and removals) that occurred within the last [param lookback_sec] seconds.
`Array`	name_get_recent_removals( target: `Node`, lookback_sec: `float` = 1.0) `static`
Returns an array of name tag identifiers that were removed from the target within the last [param lookback_sec] seconds.
`bool`	name_had_tag( tag: `StringName`, target: `Node`, lookback_sec: `float` = 1.0) `static`
Returns true if the target had the specified name tag at any point during the last [param lookback_sec] seconds.
`bool`	name_was_tag_added( tag: `StringName`, target: `Node`, lookback_sec: `float` = 1.0) `static`
Returns true if the specified name tag was added to the target within the last [param lookback_sec] seconds.
`bool`	name_was_tag_removed( tag: `StringName`, target: `Node`, lookback_sec: `float` = 1.0) `static`
Returns true if the specified name tag was removed from the target within the last [param lookback_sec] seconds.
`bool`	validate_tag_type( tag: `StringName`, expected_type: `int`) `static`
Validates that a tag exists and matches the expected type. Returns false if tag doesn’t exist or type doesn’t match.

Constants

Name	Value
NAME	`0`
A standard identity tag for classes, states, or teams (e.g., State.Stunned).
CONDITIONAL	`1`
A dynamic conditional tag with duration and magnitude support (e.g., Can.Attack).
EVENT	`2`
A high-frequency ephemeral tag with payload support (e.g., Event.Damage).
UNKNOWN	`255`

ASTagSpec