wowlab_engine_gamedata/game_data/

spell_access.rs

//! Spell, aura, power, and spell-relation access to resolved game data.

use wowlab_types::{
    constants::{HUNDRED, MS_PER_SECOND},
    data::SpellResources,
    sim::SpellIdx,
};

use super::{AuraProps, PowerTypeProps, ResolvedGameData, SpellProps};

fn missing_field(spell_id: SpellIdx, field: &'static str) -> crate::GameDataError {
    crate::GameDataError::missing_spell_field(spell_id, field)
}

macro_rules! spell_prop_accessor {
    (
        copy {
            $(
                $(#[$copy_meta:meta])*
                $copy_method:ident -> $copy_ty:ty => $copy_field:ident
            ),* $(,)?
        }
        flatten {
            $(
                $(#[$flatten_meta:meta])*
                $flatten_method:ident -> $flatten_ty:ty => $flatten_field:ident
            ),* $(,)?
        }
        slice {
            $(
                $(#[$slice_meta:meta])*
                $slice_method:ident -> $slice_ty:ty => $slice_field:ident
            ),* $(,)?
        }
    ) => {
        $(
            $(#[$copy_meta])*
            #[must_use]
            pub fn $copy_method(&self, spell_id: SpellIdx) -> Option<$copy_ty> {
                self.spell_props(spell_id).map(|props| props.$copy_field)
            }
        )*
        $(
            $(#[$flatten_meta])*
            #[must_use]
            pub fn $flatten_method(&self, spell_id: SpellIdx) -> Option<$flatten_ty> {
                self.spell_props(spell_id)
                    .and_then(|props| props.$flatten_field)
            }
        )*
        $(
            $(#[$slice_meta])*
            #[must_use]
            pub fn $slice_method(&self, spell_id: SpellIdx) -> Option<&[$slice_ty]> {
                self.spell_props(spell_id)
                    .map(|props| props.$slice_field.as_slice())
            }
        )*
    };
}

fn empower_stages_are_contiguous(stages: &[wowlab_types::data::EmpowerStage]) -> bool {
    stages
        .iter()
        .enumerate()
        .all(|(index, stage)| i32::try_from(index).is_ok_and(|expected| stage.stage == expected))
}

impl ResolvedGameData {
    /// Cumulative hold time needed to release a DBC empower spell at `rank`.
    ///
    /// One-based ranks cumulatively consume zero-based DBC duration segments.
    #[must_use]
    pub fn empower_cast_time_ms(&self, spell_id: SpellIdx, rank: u8) -> Option<u32> {
        if rank == 0 {
            return None;
        }

        if self.inner.spells.props.is_empty() {
            return Some(0);
        }

        let props = self.spell_props(spell_id)?;

        if !props.can_empower {
            return None;
        }

        let stages = &props.empower_stages;

        if !empower_stages_are_contiguous(stages) {
            return None;
        }

        let count = usize::from(rank);

        if count > stages.len() {
            return None;
        }

        stages.iter().take(count).try_fold(0_u32, |total, stage| {
            u32::try_from(stage.duration_ms)
                .ok()
                .and_then(|duration| total.checked_add(duration))
        })
    }

    /// Cumulative hold times for every one-based release rank of a DBC empower spell.
    #[must_use]
    pub fn empower_cast_times_ms(&self, spell_id: SpellIdx) -> Option<Vec<u32>> {
        if self.inner.spells.props.is_empty() {
            return Some(Vec::new());
        }

        let props = self.spell_props(spell_id)?;

        if !props.can_empower
            || props.empower_stages.is_empty()
            || !empower_stages_are_contiguous(&props.empower_stages)
        {
            return None;
        }

        let mut total = 0_u32;
        let mut cast_times = Vec::with_capacity(props.empower_stages.len());

        for stage in &props.empower_stages {
            let duration = u32::try_from(stage.duration_ms).ok()?;

            total = total.checked_add(duration)?;
            cast_times.push(total);
        }

        Some(cast_times)
    }

    /// Required cumulative hold times for every release rank of a DBC empower spell.
    /// # Errors
    /// Returns an error when the spell has no valid resolved empower stages.
    pub fn require_empower_cast_times_ms(
        &self,
        spell_id: SpellIdx,
    ) -> Result<Vec<u32>, crate::GameDataError> {
        self.empower_cast_times_ms(spell_id)
            .ok_or_else(|| crate::GameDataError::invalid_empower_timings(spell_id))
    }

    /// Whether the spell has a `SpellEmpower` row in structured game data.
    #[must_use]
    pub fn is_empower_spell(&self, spell_id: SpellIdx) -> bool {
        self.spell_props(spell_id)
            .is_some_and(|props| props.can_empower)
    }

    /// Required cumulative empower hold time for a one-based release rank.
    /// # Errors
    /// Returns an error when the spell has no such resolved empower rank.
    pub fn require_empower_cast_time_ms(
        &self,
        spell_id: SpellIdx,
        rank: u8,
    ) -> Result<u32, crate::GameDataError> {
        self.empower_cast_time_ms(spell_id, rank)
            .ok_or_else(|| crate::GameDataError::missing_empower_rank(spell_id, rank))
    }

    /// Number of release ranks defined by a spell's DBC empower stages.
    #[must_use]
    pub fn empower_max_rank(&self, spell_id: SpellIdx) -> Option<u8> {
        if self.inner.spells.props.is_empty() {
            return Some(0);
        }

        let props = self.spell_props(spell_id)?;

        if !props.can_empower
            || props.empower_stages.is_empty()
            || !empower_stages_are_contiguous(&props.empower_stages)
        {
            return None;
        }

        u8::try_from(props.empower_stages.len()).ok()
    }

    /// Required number of release ranks defined by a spell's DBC empower stages.
    /// # Errors
    /// Returns an error when the spell has no resolved empower stages or their count exceeds `u8`.
    pub fn require_empower_max_rank(&self, spell_id: SpellIdx) -> Result<u8, crate::GameDataError> {
        self.empower_max_rank(spell_id)
            .ok_or_else(|| crate::GameDataError::invalid_empower_rank_count(spell_id))
    }

    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.inner.effects.values.is_empty()
    }

    #[must_use]
    pub fn spell_resources(&self, spell_id: SpellIdx) -> Option<SpellResources> {
        self.spell_props(spell_id).map(|props| SpellResources {
            primary_cost: props.cost,
            primary_optional_cost: props.optional_cost,
            primary_cost_pct: props.cost_pct,
            primary_max_cost_pct: props.max_cost_pct,
            primary_optional_cost_pct: props.optional_cost_pct,
            primary_gain: props.gain,
            secondary_cost: props.secondary_cost,
            secondary_optional_cost: props.secondary_optional_cost,
            secondary_gain: props.secondary_gain,
            health_cost: props.health_cost,
            health_cost_pct: props.health_cost_pct,
            health_max_cost_pct: props.health_max_cost_pct,
            health_optional_cost: props.health_optional_cost,
            health_optional_cost_pct: props.health_optional_cost_pct,
            primary_cost_entry: props.primary_cost_entry,
            secondary_cost_entry: props.secondary_cost_entry,
        })
    }

    #[must_use]
    pub fn hit_chance_modifier(&self, spell_id: SpellIdx, initial: f64) -> f64 {
        self.spell_props(spell_id).map_or(initial, |props| {
            (initial + props.hit_chance_flat) * props.hit_chance_multiplier
        })
    }

    #[must_use]
    pub fn target_resistance_modifier(&self, spell_id: SpellIdx, initial: f64) -> f64 {
        self.spell_props(spell_id).map_or(initial, |props| {
            (initial + props.target_resistance_flat) * props.target_resistance_multiplier
        })
    }

    #[must_use]
    pub fn dispel_resistance_modifier(&self, spell_id: SpellIdx, initial: f64) -> f64 {
        self.spell_props(spell_id).map_or(initial, |props| {
            (initial + props.dispel_resistance_flat) * props.dispel_resistance_multiplier
        })
    }

    /// Raw DBC dispel family assigned to this spell.
    #[must_use]
    pub fn dispel_type(&self, spell_id: SpellIdx) -> i32 {
        self.spell_props(spell_id)
            .map_or(0, |props| props.dispel_type)
    }

    /// Raw DBC `SpellCategories.Mechanic` identity.
    #[must_use]
    pub fn spell_mechanic(&self, spell_id: SpellIdx) -> i32 {
        self.spell_props(spell_id).map_or(0, |props| props.mechanic)
    }

    #[must_use]
    pub fn cooldown_s(&self, spell_id: SpellIdx) -> Option<f64> {
        self.spell_props(spell_id)
            .map(|p| f64::from(p.cooldown_ms) / MS_PER_SECOND)
    }

    #[must_use]
    pub fn cast_time_ms(&self, spell_id: SpellIdx) -> Option<u32> {
        self.spell_props(spell_id)
            .and_then(|p| u32::try_from(p.cast_time_ms).ok())
    }

    #[must_use]
    pub fn breaks_stealth(&self, spell_id: SpellIdx) -> Option<bool> {
        self.spell_props(spell_id)
            .map(|p| !p.does_not_break_stealth)
    }

    /// `SpellAuraOptions.ProcChance` as a 0..=1 fraction; `None` when the spell is unresolved.
    #[must_use]
    pub fn proc_chance(&self, spell_id: SpellIdx) -> Option<f64> {
        self.proc_chance_with_flat_bonus(spell_id, 0.0)
    }

    /// `SpellAuraOptions.ProcCharges`; zero means unlimited.
    #[must_use]
    pub fn proc_charges(&self, spell_id: SpellIdx) -> Option<u8> {
        self.spell_props(spell_id)
            .and_then(|props| u8::try_from(props.proc_charges).ok())
    }

    /// Non-negative `SpellAuraOptions.ProcCategoryRecovery` in milliseconds.
    #[must_use]
    pub fn proc_category_recovery_ms(&self, spell_id: SpellIdx) -> Option<u32> {
        self.spell_props(spell_id)
            .map(|props| u32::try_from(props.proc_category_recovery_ms.max(0)).unwrap_or(0))
    }

    /// Base real-procs-per-minute rate and raw scaling flags.
    #[must_use]
    pub fn rppm(&self, spell_id: SpellIdx) -> Option<(f64, i32)> {
        self.spell_props(spell_id)
            .map(|props| (props.rppm_base_rate, props.rppm_flags))
    }

    /// Proc chance after adding a runtime flat fraction before passive percentage modifiers.
    #[must_use]
    pub fn proc_chance_with_flat_bonus(
        &self,
        spell_id: SpellIdx,
        runtime_flat: f64,
    ) -> Option<f64> {
        self.spell_props(spell_id).map(|props| {
            (f64::from(props.proc_chance_pct) / HUNDRED + runtime_flat)
                * (1.0 + props.proc_chance_multiplier_delta)
        })
    }

    #[must_use]
    pub fn charges(&self, spell_id: SpellIdx) -> Option<u8> {
        self.spell_props(spell_id)
            .and_then(|p| u8::try_from(p.max_charges).ok())
    }

    #[must_use]
    pub fn charge_cd_s(&self, spell_id: SpellIdx) -> Option<f64> {
        self.spell_props(spell_id)
            .map(|p| f64::from(p.charge_cd_ms) / MS_PER_SECOND)
    }

    #[must_use]
    pub fn category_cooldown_s(&self, spell_id: SpellIdx) -> Option<f64> {
        self.spell_props(spell_id)
            .map(|p| f64::from(p.category_cooldown_ms) / MS_PER_SECOND)
    }

    #[must_use]
    pub fn gcd_ms(&self, spell_id: SpellIdx) -> Option<u32> {
        self.spell_props(spell_id)
            .and_then(|p| u32::try_from(p.gcd_ms).ok())
    }

    #[must_use]
    pub fn aura_duration_ms(&self, spell_id: SpellIdx) -> Option<u32> {
        // Game-data `-1` (no fixed duration) collapses to the aura system's `0` permanent sentinel.
        let raw = self
            .aura_props(spell_id)
            .map(|props| props.duration_ms)
            .or_else(|| {
                self.spell_props(spell_id)
                    .map(|props| props.duration_ms)
                    .filter(|duration_ms| *duration_ms != 0)
            })?;

        Some(u32::try_from(raw).unwrap_or(0))
    }

    #[must_use]
    pub fn aura_max_stacks(&self, spell_id: SpellIdx) -> Option<u8> {
        let configured_stacks = self
            .aura_props(spell_id)
            .map(|props| props.max_stacks)
            .or_else(|| {
                self.spell_props(spell_id)
                    .map(|props| props.max_stacks)
                    .filter(|max_stacks| *max_stacks != 0)
            });

        configured_stacks.and_then(|max_stacks| u8::try_from(max_stacks).ok())
    }

    #[must_use]
    pub fn aura_doses(&self, spell_id: SpellIdx) -> Option<u8> {
        self.aura_props(spell_id)
            .and_then(|props| u8::try_from(props.doses).ok())
    }

    #[must_use]
    pub fn aura_tick_ms(&self, spell_id: SpellIdx) -> Option<u32> {
        self.aura_props(spell_id)
            .and_then(|p| u32::try_from(p.tick_period_ms).ok())
    }

    /// Tick count of a channel. `cast_time_ms` IS the channel duration.
    #[must_use]
    pub fn channel_tick_count(&self, spell_id: SpellIdx) -> Option<u8> {
        let dur = self.spell_props(spell_id)?.cast_time_ms;
        let aura_period = self
            .aura_props(spell_id)
            .map(|props| props.tick_period_ms)
            .filter(|period| *period > 0);
        let effect_period = self
            .inner
            .effects
            .values
            .iter()
            .filter_map(|(key, effect)| {
                (key.spell == spell_id && effect.period > 0.0).then_some(effect.period)
            })
            .min_by(f64::total_cmp)
            .and_then(|period| {
                (period <= f64::from(i32::MAX))
                    .then(|| wowlab_types::numeric::f64_to_i32_saturating_round(period))
            });
        let period = aura_period.or(effect_period).unwrap_or(0);

        if dur <= 0 || period <= 0 {
            return Some(0);
        }

        let n = dur / period;

        u8::try_from(n.min(i32::from(u8::MAX))).ok()
    }

    /// Max base power for a power type (`power_type_enum`); `None` when the type is absent.
    #[must_use]
    pub fn power_max(&self, type_id: i32) -> Option<f64> {
        self.power_props(type_id).map(|p| p.max_base_power)
    }

    /// Display divisor for raw DBC flat power amounts (runic power and rage store tenths); `1.0` when the type is absent.
    #[must_use]
    pub fn power_display_divisor(&self, type_id: i32) -> f64 {
        self.power_props(type_id)
            .map_or(1.0, |p| p.display_modifier.max(1.0))
    }

    /// 1-based DBC power-cost entry backing the spell's cost in the given pool; `0` = no such cost, and cost modifiers route to entries by this index.
    #[must_use]
    pub fn cost_entry(&self, spell_id: SpellIdx, secondary: bool) -> u8 {
        self.spell_props(spell_id).map_or(0, |p| {
            if secondary {
                p.secondary_cost_entry
            } else {
                p.primary_cost_entry
            }
        })
    }

    /// Combat regeneration when the DBC expresses regeneration as a percentage of maximum power (notably mana).
    #[must_use]
    pub fn power_regen_for_max(&self, type_id: i32, maximum: f64) -> Option<f64> {
        self.power_props(type_id)
            .map(|props| props.regen_combat + maximum * props.regen_percent_of_max / HUNDRED)
    }

    /// Multiplier for auto-attack gains of the named resource (aura 213 passives).
    #[must_use]
    pub fn power_auto_attack_gain_multiplier(&self, type_id: i32) -> f64 {
        self.power_props(type_id)
            .map_or(1.0, |props| 1.0 + props.auto_attack_gain_percent / HUNDRED)
    }

    /// Additive spell-cost percent for the named resource (aura 423 passives).
    #[must_use]
    pub fn power_cost_percent(&self, type_id: i32) -> f64 {
        self.power_props(type_id)
            .map_or(0.0, |props| props.cost_percent)
    }

    /// Default (starting) power for a power type; `None` when the type is absent.
    #[must_use]
    pub fn power_default(&self, type_id: i32) -> Option<f64> {
        self.power_props(type_id).map(|p| p.default_power)
    }

    /// Descale a raw DBC power amount for `type_id` using its display modifier.
    #[must_use]
    pub fn scaled_power_amount(&self, type_id: i32, raw: f64) -> f64 {
        raw / self
            .power_props(type_id)
            .map_or(1.0, |props| props.display_modifier.max(1.0))
    }

    /// Returns the replacement for an overridden spell.
    ///
    /// ```compile_fail
    /// use wowlab_engine_gamedata::ResolvedGameData;
    /// use wowlab_types::sim::AuraIdx;
    ///
    /// let data = ResolvedGameData::default();
    /// let aura = AuraIdx::from_raw(1);
    /// data.spell_override(aura);
    /// ```
    #[must_use]
    pub fn spell_override(&self, overridden_id: SpellIdx) -> Option<SpellIdx> {
        self.inner.spells.overrides.get(&overridden_id).copied()
    }

    /// Iterates learned spells for `teacher` in resolver insertion order (deduplicated, first-occurrence order retained); missing teachers yield an empty iterator.
    #[must_use]
    pub fn learned_spells(
        &self,
        teacher: SpellIdx,
    ) -> impl ExactSizeIterator<Item = SpellIdx> + '_ {
        self.inner
            .spells
            .learns
            .get(&teacher)
            .map(Vec::as_slice)
            .unwrap_or_default()
            .iter()
            .copied()
    }

    /// Whether `spell` carries the given `SpellLabel` id (affect-list gating).
    #[must_use]
    pub fn has_label(&self, spell: SpellIdx, label: i32) -> bool {
        self.inner
            .spells
            .labels
            .get(&spell)
            .is_some_and(|labels| labels.contains(&label))
    }

    pub(super) fn spell_props(&self, spell_id: SpellIdx) -> Option<&SpellProps> {
        self.inner.spells.props.get(&spell_id)
    }

    fn aura_props(&self, spell_id: SpellIdx) -> Option<&AuraProps> {
        self.inner.spells.aura_props.get(&spell_id)
    }

    fn power_props(&self, type_id: i32) -> Option<&PowerTypeProps> {
        self.inner.spells.power_types.get(&type_id)
    }

    require_accessor! {
        spell {
            /// Resource cost, required to be present on populated game data.
            /// # Errors
            /// Returns an error when the spell has no resolved cost.
            require_cost -> f64, "cost" => |data, spell| data.spell_resources(spell).map(|resources| resources.primary_cost),
            /// Cooldown in seconds, required on populated data.
            /// # Errors
            /// Returns an error when the spell has no resolved cooldown.
            require_cooldown_s -> f64, "cooldown_s" => |data, spell| data.cooldown_s(spell),
            /// Max aura stacks, required to be present on populated game data.
            /// # Errors
            /// Returns an error when the spell has no resolved aura stack limit.
            require_aura_max_stacks -> u8, "aura_max_stacks" => |data, spell| data.aura_max_stacks(spell),
            /// Aura duration in milliseconds, required on populated game data.
            /// # Errors
            /// Returns an error when the spell has no resolved aura duration.
            require_aura_duration_ms -> u32, "aura_duration_ms" => |data, spell| data.aura_duration_ms(spell),
            /// Cast time in milliseconds, required on populated game data.
            /// # Errors
            /// Returns an error when the spell has no resolved cast time.
            require_cast_time_ms -> u32, "cast_time_ms" => |data, spell| data.cast_time_ms(spell),
        }
    }

    require_accessor! {
        spell {
            /// Charge cooldown in seconds, required on populated game data.
            /// # Errors
            /// Returns an error when the spell has no resolved charge cooldown.
            require_charge_cd_s -> f64, "charge_cd_s" => |data, spell| data.charge_cd_s(spell),
            /// Proc-category internal cooldown in milliseconds, required on populated data.
            /// # Errors
            /// Returns an error when the driver spell is absent.
            require_proc_category_recovery_ms -> u32, "proc_category_recovery_ms" => |data, spell| data.proc_category_recovery_ms(spell),
            /// Combined DBC proc event mask, required on populated data.
            /// # Errors
            /// Returns an error when the driver spell is absent.
            require_proc_type_mask -> u64, "proc_type_mask" => |data, spell| data.proc_type_mask(spell),
            /// Channel tick count, required to be present on populated game data.
            /// # Errors
            /// Returns an error when the spell has no resolved channel tick count.
            require_channel_tick_count -> u8, "channel_tick_count" => |data, spell| data.channel_tick_count(spell),
        }
    }

    spell_prop_accessor! {
        copy {
            defense_type -> i32 => defense_type,
            shapeshift_required_mask -> u64 => shapeshift_required_mask,
            shapeshift_excluded_mask -> u64 => shapeshift_excluded_mask,
            gain -> f64 => gain,
            secondary_gain -> f64 => secondary_gain,
            cooldown_hasted -> bool => cooldown_hasted,
            gcd_haste_type -> wowlab_types::combat::GcdHasteType => gcd_haste_type,
            hasted_ticks -> bool => hasted_ticks,
            duration_hasted -> bool => duration_hasted,
            cannot_crit -> bool => cannot_crit,
            requires_stealth -> bool => requires_stealth,
            requires_behind_target -> bool => requires_behind_target,
            requires_unshifted -> bool => requires_unshifted,
            allow_while_unshifted -> bool => allow_while_unshifted,
            treat_as_periodic -> bool => treat_as_periodic,
            treat_as_area_effect -> bool => treat_as_area_effect,
            usable_while_casting -> bool => usable_while_casting,
            usable_while_moving -> bool => usable_while_moving,
            asynchronous_stacks -> bool => asynchronous_stacks,
            disable_player_damage_multiplier -> bool => disable_player_damage_multiplier,
            disable_target_damage_multiplier -> bool => disable_target_damage_multiplier,
            disable_positive_target_damage_multiplier -> bool => disable_positive_target_damage_multiplier,
            requires_off_hand -> bool => requires_off_hand,
            requires_main_hand -> bool => requires_main_hand,
            refresh_behavior -> wowlab_types::data::RefreshBehavior => refresh_behavior,
            caster_aura_state -> i32 => caster_aura_state,
            caster_aura_spell -> i32 => caster_aura_spell,
            exclude_caster_aura_state -> i32 => exclude_caster_aura_state,
            exclude_caster_aura_spell -> i32 => exclude_caster_aura_spell,
            target_aura_state -> i32 => target_aura_state,
            target_aura_spell -> i32 => target_aura_spell,
            exclude_target_aura_state -> i32 => exclude_target_aura_state,
            exclude_target_aura_spell -> i32 => exclude_target_aura_spell,
            aura_interrupt_flags -> u32 => aura_interrupt_flags,
            spell_interrupt_flags -> u32 => spell_interrupt_flags,
            channel_interrupt_flags -> u32 => channel_interrupt_flags,
            rolling_periodic -> bool => rolling_periodic,
            tick_may_crit -> bool => tick_may_crit,
            tick_on_application -> bool => tick_on_application,
            /// Raw `SpellProcEntry.AttributesMask`; zero means no proc attributes.
            proc_attributes -> u32 => proc_attributes,
            /// Combined `SpellAuraOptions.ProcTypeMask_0/1` event mask.
            proc_type_mask -> u64 => proc_type_mask,
            rppm_haste_scales -> bool => rppm_haste_scales,
            rppm_crit_scales -> bool => rppm_crit_scales,
        }
        flatten {
            equipped_item_requirement -> wowlab_types::data::EquippedItemRequirement => equipped_item_requirement,
            cooldown_category -> wowlab_types::data::CooldownCategoryId => cooldown_category,
            charge_category -> wowlab_types::data::CooldownCategoryId => charge_category,
            start_recovery_category -> wowlab_types::data::CooldownCategoryId => start_recovery_category,
        }
        slice {
            spell_attributes -> i32 => attributes,
        }
    }

    spell_prop_accessor! {
        copy {
            projectile_speed -> f64 => projectile_speed,
            launch_delay_s -> f64 => launch_delay_s,
            hostile_min_range -> f64 => hostile_min_range,
            hostile_max_range -> f64 => hostile_max_range,
            radius -> f64 => radius,
            chain_target_range -> f64 => chain_target_range,
            max_affected_targets -> u8 => max_affected_targets,
            cone_half_angle -> f64 => cone_half_angle,
            fixed_travel_time -> bool => fixed_travel_time,
            ignores_line_of_sight -> bool => ignores_line_of_sight,
            explicit_target_mask -> u32 => explicit_target_mask,
            required_explicit_target_mask -> u32 => required_explicit_target_mask,
        }
        flatten {
        }
        slice {
        }
    }
}