Utils: status

Status effect utilities.

Provides helper functions for managing status effects on entities, including adding/removing effects, checking for effect presence, and consuming effect usages.

add_status(status, effect_id)

Return new Status with effect ID added.

get_status_effect(effect_ids, effects, time_limit, usage_limit)

Select a valid effect from effect_ids matching any provided store.

Selection rules: 1. Filter to effect IDs present in at least one supplied effect map. 2. Drop expired effects (time or usage limit <= 0). 3. Prefer effects without usage limits; otherwise lowest EID yields tie.

has_effect(state, effect_id)

Return True if effect_id exists in any runtime effect store.

remove_status(status, effect_id)

Return new Status with effect ID removed.

use_status_effect(effect_id, usage_limit)

Consume one use from a usage-limited effect if present.

use_status_effect_if_present(effect_ids, effects, time_limit, usage_limit)

Select and consume an effect (if any) returning updated usage map.

valid_effect(state, effect_id)

Return True if effect has no expired time/usage limit.