Module ability_utils 

AbilityUtils — utility functions for ability resolution.

Mirrors Java’s AbilityUtils.java. This is the single source of truth for helper functions used across effects. The effects::helpers module re-exports everything from here for backward compatibility.

Enums

DefinedCardToken

Static (non-prefix) Defined$ tokens that refer to a set of cards. Prefix-based tokens (Triggered*, ValidGraveyard <filter>, …) stay as separate branches below since strum can’t match open-ended suffixes.

DefinedPlayerToken

Resolve a Defined$ parameter to a player ID. Mirrors Java’s AbilityUtils.getDefinedPlayers().

Functions

add_splice_effect

Add a single splice effect from a card onto a spell ability. Mirrors Java’s AbilityUtils.addSpliceEffect(SpellAbility, Card).

add_splice_effects

Add splice effects to a spell ability. Mirrors Java’s AbilityUtils.addSpliceEffects(SpellAbility).

apply_ability_text_change_effects

Apply ability text change effects (for non-descriptive ability text). Mirrors Java’s AbilityUtils.applyAbilityTextChangeEffects(String, CardTraitBase).

apply_description_text_change_effects

Apply description text change effects (includes strikethrough in Java UI; in the Rust engine we just do the replacement). Mirrors Java’s AbilityUtils.applyDescriptionTextChangeEffects(String, CardTraitBase).

apply_keyword_text_change_effects

Apply keyword text change effects. Mirrors Java’s AbilityUtils.applyKeywordTextChangeEffects(String, Card).

apply_mana_color_conversion

Apply mana color conversion rules to a mana conversion matrix. Mirrors Java’s AbilityUtils.applyManaColorConversion(ManaConversionMatrix, String).

apply_text_change_effects

Apply text change effects from a card’s SVars to a string. Mirrors Java’s AbilityUtils.applyTextChangeEffects(String, boolean, Map, Map).

calculate_amount

Calculate a numeric amount from a parameter string. Handles simple integers and “X” references.

calculate_unless_cost

Calculate the cost for an UnlessCost$ clause. Mirrors Java’s AbilityUtils.calculateUnlessCost(SpellAbility, String, boolean).

count_card_types_from_list

Count distinct card types among a list of cards. Mirrors Java’s AbilityUtils.countCardTypesFromList(Iterable<Card>, boolean).

count_sub_types_from_list

Count distinct subtypes among a list of cards. Mirrors Java’s AbilityUtils.countSubTypesFromList(Iterable<Card>).

count_super_types_from_list

Count distinct supertypes among a list of cards. Mirrors Java’s AbilityUtils.countSuperTypesFromList(Iterable<Card>).

do_x_math

Apply arithmetic operators to a base value. Mirrors Java’s AbilityUtils.doXMath(int num, String operators, Card c, CardTraitBase ctb).

filter_list_by_type

Filter a list of card IDs by a type/valid-cards expression. Mirrors Java’s AbilityUtils.filterListByType(CardCollectionView, String, SpellAbility).

get_basic_spells_from_play_effect

Collect the basic spell abilities that a Play$ effect could cast from tgt_card. Mirrors Java AbilityUtils.getBasicSpellsFromPlayEffect(Card, Player).

get_defined_cards

Resolve Defined$ strings to a list of card IDs. Mirrors Java’s AbilityUtils.getDefinedCards().

get_defined_entities

Resolve a Defined$ expression to a combined player + card list. Mirrors Java AbilityUtils.getDefinedEntities(Card, String, CardTraitBase).

get_defined_objects

Resolve a Defined$ expression to a combined list of the targeted GameObjects — cards + players + spell abilities. Mirrors Java AbilityUtils.getDefinedObjects(Card, String, CardTraitBase).

get_defined_players

Resolve Defined$ strings to a list of player IDs. Mirrors Java’s AbilityUtils.getDefinedPlayers().

get_defined_spell_abilities

Resolve a Defined$ parameter to spell abilities. Mirrors Java AbilityUtils.getDefinedSpellAbilities(Card, String, CardTraitBase) (AbilityUtils.java:1202).

get_s_var

Read an SVar from the SA’s host, applying in-flight text-change effects when the SA is intrinsic — mirrors Java AbilityUtils.getSVar(CardTraitBase, String).

get_spells_from_play_effect

Full variant of getBasicSpellsFromPlayEffect — when with_alt_cost is true, alternative-cost (flashback/overload/…) variants are included. Mirrors Java AbilityUtils.getSpellsFromPlayEffect(Card, Player, CardStateName, boolean).

handle_paid

Handle paid-list counting for X-count expressions. Mirrors Java’s AbilityUtils.handlePaid(Iterable<Card>, String, Card, CardTraitBase).

handle_remembering

Handle remembering targets/objects after a spell resolves. Mirrors Java’s AbilityUtils.handleRemembering(SpellAbility).

is_unlinked_from_cast_sa

Returns true when a trait can’t be linked to the cast-SA of card because the trait originates from a different physical host (transformed / melded / adventure-cast situations).

matches_change_type

Check if a card matches a ChangeType$ / ValidCards$ filter string.

matches_valid_cards

Full ValidCards$ filter matching with controller and keyword qualifier support.

matches_valid_cards_for_sa

matches_valid_cards_for_source

matches_valid_cards_selector_opt

object_x_count

Evaluate object-based X-count expressions. Mirrors Java’s AbilityUtils.objectXCount(List<?>, String, Card, CardTraitBase).

parse_counter_type

Parse a counter type string to CounterType enum (case-insensitive). Unknown types produce CounterType::Named(UPPER) instead of silently falling back to P1P1, so cards like Stocking the Pantry get the correct SUPPLY counters.

parse_num_dmg

Parse NumDmg$ value from an ability string.

parse_param

Parse a numeric parameter from an ability string (e.g. “NumAtt$ 3” → 3).

parse_zone_type

Parse a zone name string to ZoneType.

player_x_count

Evaluate player-based X-count expressions. Mirrors Java’s AbilityUtils.playerXCount(List<Player>, String, Card, CardTraitBase).

player_x_property

Get a numeric property for a single player. Mirrors Java’s AbilityUtils.playerXProperty(Player, String, Card, CardTraitBase).

resolve

Top-level ability resolution entry point. Mirrors Java’s AbilityUtils.resolve(SpellAbility).

resolve_defined_player

resolve_defined_player_with_sa

Resolve a Defined$ parameter to a player ID with spell/trigger context. Mirrors Java’s Triggered* player resolution for trigger SVar chains.

resolve_defined_players

Resolve a Defined$ parameter to a list of player IDs. Supports “You”, “Opponent”, “Each”/“All”/“Player” (all alive players). Mirrors Java’s AbilityUtils.getDefinedPlayers() for multi-player resolution.

resolve_defined_players_with_sa

Resolve a Defined$ parameter to a list of player IDs with spell/trigger context.

x_count

Evaluate an X-count expression on a card. Mirrors Java’s AbilityUtils.xCount(Card c, String s, CardTraitBase ctb).