wowlab_engine_domain/dbc/game_data/

trigger_program.rs

//! Interpretation policy over resolved game data.

use wowlab_engine_gamedata::{ResolvedDamageDef, ResolvedGameData};
use wowlab_types::{
    combat::ResourceType,
    sim::{EffectRef, SpellIdx},
};

use super::{super::EffectLookup, damage_def::damage_def_at, error::TriggerResolveError};

pub(super) const MAX_TRIGGER_DEPTH: usize = 8;

pub(super) struct TriggerPath {
    source_spell_id: u32,
    ancestors: [u32; MAX_TRIGGER_DEPTH + 1],
}

impl TriggerPath {
    pub(super) fn new(source: SpellIdx) -> Self {
        let mut ancestors = [0; MAX_TRIGGER_DEPTH + 1];

        ancestors[0] = source.as_u32();

        Self {
            source_spell_id: source.as_u32(),
            ancestors,
        }
    }

    pub(super) fn enter(
        &mut self,
        spell_id: SpellIdx,
        depth: usize,
    ) -> Result<(), TriggerResolveError> {
        if depth > MAX_TRIGGER_DEPTH {
            return Err(TriggerResolveError::depth_exceeded(self.source_spell_id));
        }

        let raw_spell_id = spell_id.as_u32();

        let Some(ancestors) = self.ancestors.get(..depth) else {
            return Err(TriggerResolveError::depth_exceeded(self.source_spell_id));
        };

        if ancestors.contains(&raw_spell_id) {
            return Err(TriggerResolveError::cycle(raw_spell_id));
        }

        let Some(slot) = self.ancestors.get_mut(depth) else {
            return Err(TriggerResolveError::depth_exceeded(self.source_spell_id));
        };

        *slot = raw_spell_id;

        Ok(())
    }
}

/// One typed combat operation resolved from a DBC trigger child.
#[derive(Clone, Debug)]
#[non_exhaustive]
pub enum TriggerOperation {
    Damage(TriggeredDamage),
    Delayed {
        delay_ms: u32,
        profile_spell_id: SpellIdx,
        operations: Vec<TriggerOperation>,
    },
    ApplyAura {
        aura_id: SpellIdx,
    },
    RemoveAura {
        aura_id: SpellIdx,
    },
    EnergizePrimary {
        amount: f64,
    },
    EnergizeSecondary {
        amount: f64,
    },
    EnergizePercent {
        resource_type: ResourceType,
        percent: f64,
        effect_index: u8,
    },
    MutateCooldown {
        target: TriggerCooldownTarget,
        operation: CooldownMutation,
    },
}

/// Cooldown coordinate selected by a DBC effect-program operation.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
// #t(rust_non_exhaustive_on_public) the lowered effect-program algebra is intentionally exhaustive
pub enum TriggerCooldownTarget {
    Spell(SpellIdx),
    ChargeCategory(wowlab_types::data::CooldownCategoryId),
}

/// Typed cooldown mutation shared by direct and triggered effect programs.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
// #t(rust_non_exhaustive_on_public) the lowered effect-program algebra is intentionally exhaustive
pub enum CooldownMutation {
    ReduceRemaining { amount_ms: u32 },
    Recharge { charges: u8 },
}

/// Ordered, bounded child operations reached through one DBC trigger edge.
#[derive(Clone, Debug)]
pub struct TriggerProgram {
    pub child_spell_id: SpellIdx,
    pub operations: Vec<TriggerOperation>,
}

/// Terminal damage payload reached by following one DBC trigger edge.
#[derive(Clone, Copy, Debug)]
#[non_exhaustive]
pub struct TriggeredDamage {
    pub spell_id: SpellIdx,
    pub damage: ResolvedDamageDef,
    pub requires_main_hand: bool,
    pub requires_off_hand: bool,
    pub equipped_item_requirement: Option<wowlab_types::data::EquippedItemRequirement>,
}

fn immediate_operation_at(
    lookup: EffectLookup<'_>,
    forwarded_value: Option<f64>,
) -> Result<Option<TriggerOperation>, TriggerResolveError> {
    let data = lookup.data;
    let EffectRef {
        spell: spell_id,
        effect_index,
    } = lookup.effect;
    let raw_spell_id = spell_id.as_u32();

    match super::super::spell_effect_kind(lookup.effect_type()) {
        Some(super::super::SpellEffectKind::ApplyAura) => {
            Ok(Some(TriggerOperation::ApplyAura { aura_id: spell_id }))
        }
        Some(
            super::super::SpellEffectKind::CancelAura | super::super::SpellEffectKind::RemoveAura,
        ) => {
            let aura_id = lookup.trigger_spell().ok_or_else(|| {
                TriggerResolveError::missing_removed_aura(raw_spell_id, effect_index)
            })?;

            Ok(Some(TriggerOperation::RemoveAura { aura_id }))
        }
        Some(super::super::SpellEffectKind::ReduceRemainingCooldown) => {
            let target = data
                .trigger_spell(spell_id, effect_index)
                .ok_or_else(|| TriggerResolveError::missing_edge(raw_spell_id, effect_index))?;
            let amount = forwarded_value
                .unwrap_or_else(|| lookup.base_points())
                .abs()
                .round();

            if !amount.is_finite() || amount <= 0.0 || amount > f64::from(u32::MAX) {
                return Err(TriggerResolveError::invalid_cooldown_amount(
                    raw_spell_id,
                    effect_index,
                    wowlab_types::numeric::f64_to_i64_saturating_trunc(amount),
                ));
            }

            let amount_ms = wowlab_types::numeric::f64_to_u32_saturating_trunc(amount);

            Ok(Some(TriggerOperation::MutateCooldown {
                target: TriggerCooldownTarget::Spell(target),
                operation: CooldownMutation::ReduceRemaining { amount_ms },
            }))
        }
        Some(super::super::SpellEffectKind::ImmediateCooldownRechargeCategory) => {
            let category = lookup.effect_misc_value_0();
            let category =
                wowlab_types::data::CooldownCategoryId::from_raw(category).ok_or_else(|| {
                    TriggerResolveError::invalid_cooldown_category(
                        raw_spell_id,
                        effect_index,
                        category,
                    )
                })?;
            let charges = forwarded_value
                .unwrap_or_else(|| lookup.base_points())
                .round()
                .clamp(1.0, f64::from(u8::MAX));
            let charges = wowlab_types::numeric::f64_to_u8_saturating_trunc(charges);

            Ok(Some(TriggerOperation::MutateCooldown {
                target: TriggerCooldownTarget::ChargeCategory(category),
                operation: CooldownMutation::Recharge { charges },
            }))
        }
        Some(super::super::SpellEffectKind::EnergizePowerPercent) => {
            let resource_type = lookup.effect_misc_value_0();
            let resource_type = u8::try_from(resource_type)
                .ok()
                .and_then(|value| ResourceType::try_from(value).ok())
                .ok_or_else(|| {
                    TriggerResolveError::invalid_resource_type(
                        raw_spell_id,
                        effect_index,
                        resource_type,
                    )
                })?;

            Ok(Some(TriggerOperation::EnergizePercent {
                resource_type,
                percent: forwarded_value.unwrap_or_else(|| lookup.base_points()),
                effect_index,
            }))
        }
        _ => Ok(None),
    }
}

/// Resolves one immediate DBC effect into the shared typed effect program.
///
/// # Errors
///
/// Returns an error when an encoded operation references invalid or missing game data.
pub fn resolve_effect_program(
    lookup: EffectLookup<'_>,
    forwarded_value: Option<f64>,
) -> Result<Option<TriggerProgram>, TriggerResolveError> {
    let source = lookup.effect.spell;
    let Some(operation) = immediate_operation_at(lookup, forwarded_value)? else {
        return Ok(None);
    };
    let child_spell_id = match &operation {
        TriggerOperation::MutateCooldown {
            target: TriggerCooldownTarget::Spell(target),
            ..
        } => *target,
        TriggerOperation::RemoveAura { aura_id } => *aura_id,
        _ => source,
    };

    Ok(Some(TriggerProgram {
        child_spell_id,
        operations: vec![operation],
    }))
}

/// Resolve one trigger edge into an ordered program of supported child operations.
///
/// # Errors
///
/// Returns an error when the trigger graph is missing, cyclic, too deep, or unsupported.
pub fn resolve_trigger_program(
    lookup: EffectLookup<'_>,
    forwarded_value: Option<f64>,
) -> Result<TriggerProgram, TriggerResolveError> {
    let data = lookup.data;
    let EffectRef {
        spell: source,
        effect_index,
    } = lookup.effect;
    let child = lookup
        .trigger_spell()
        .ok_or_else(|| TriggerResolveError::missing_edge(source.as_u32(), effect_index))?;
    let mut path = TriggerPath::new(source);
    let mut operations = Vec::new();

    resolve_trigger_spell(
        data,
        source.as_u32(),
        child,
        forwarded_value,
        1,
        &mut path,
        &mut operations,
    )?;

    Ok(TriggerProgram {
        child_spell_id: child,
        operations,
    })
}

// #t(fn: rust_cyclomatic_complexity) the branches are the canonical child-operation classifier.
// #t(fn: rust_large_fn_params) bounded recursion carries one explicit path and output arena.
// #t(fn: rust_recursive_fn) recursion is hard-bounded by MAX_TRIGGER_DEPTH before every descent.
fn resolve_trigger_spell(
    data: &ResolvedGameData,
    source_spell_id: u32,
    spell_id: SpellIdx,
    forwarded_value: Option<f64>,
    depth: usize,
    path: &mut TriggerPath,
    operations: &mut Vec<TriggerOperation>,
) -> Result<(), TriggerResolveError> {
    let raw_spell_id = spell_id.as_u32();

    path.enter(spell_id, depth)?;
    let max_effect = data.max_effect_index(spell_id);

    if max_effect == 0 {
        return Err(TriggerResolveError::invalid_child_id(
            source_spell_id,
            raw_spell_id,
        ));
    }

    let mut applied_aura = false;
    let mut emitted_primary_gain = false;
    let mut emitted_secondary_gain = false;
    let operation_start = operations.len();
    let mut first_inert_dummy = None;

    for child_effect_index in 1..=max_effect {
        let effect_type = data.effect_type(spell_id, child_effect_index);
        let aura_subtype = data.effect_aura(spell_id, child_effect_index);

        if let Some(damage) = damage_def_at(
            EffectLookup::new(data, EffectRef::new(spell_id, child_effect_index)),
            forwarded_value,
        ) {
            operations.push(TriggerOperation::Damage(TriggeredDamage {
                spell_id,
                damage,
                requires_main_hand: data.requires_main_hand(spell_id).unwrap_or(false),
                requires_off_hand: data.requires_off_hand(spell_id).unwrap_or(false),
                equipped_item_requirement: data.equipped_item_requirement(spell_id),
            }));
            continue;
        }

        if let Some(operation) = immediate_operation_at(
            EffectLookup::new(data, EffectRef::new(spell_id, child_effect_index)),
            forwarded_value,
        )? {
            if matches!(operation, TriggerOperation::ApplyAura { .. }) {
                if applied_aura {
                    continue;
                }

                applied_aura = true;
            }

            operations.push(operation);
            continue;
        }

        match super::super::spell_effect_kind(effect_type) {
            Some(super::super::SpellEffectKind::None) => {}
            Some(super::super::SpellEffectKind::Dummy) if aura_subtype == 0 => {
                first_inert_dummy.get_or_insert((child_effect_index, effect_type, aura_subtype));
            }
            Some(super::super::SpellEffectKind::Energize) => {
                if !emitted_primary_gain {
                    // #t(rust_floating_point_eq) resolved resource zero is the DBC absent sentinel.
                    if let Some(amount) = data.gain(spell_id).filter(|amount| *amount != 0.0) {
                        operations.push(TriggerOperation::EnergizePrimary {
                            amount: forwarded_value.unwrap_or(amount),
                        });
                        emitted_primary_gain = true;
                    }
                }

                if !emitted_secondary_gain {
                    if let Some(amount) = data
                        .secondary_gain(spell_id)
                        // #t(rust_floating_point_eq) resolved resource zero is the DBC absent sentinel.
                        .filter(|amount| *amount != 0.0)
                    {
                        operations.push(TriggerOperation::EnergizeSecondary {
                            amount: forwarded_value.unwrap_or(amount),
                        });
                        emitted_secondary_gain = true;
                    }
                }
            }
            Some(
                super::super::SpellEffectKind::TriggerMissile
                | super::super::SpellEffectKind::TriggerSpell
                | super::super::SpellEffectKind::TriggerSpellWithValue
                | super::super::SpellEffectKind::TriggerSpell2,
            ) => {
                let next = data
                    .trigger_spell(spell_id, child_effect_index)
                    .ok_or_else(|| {
                        TriggerResolveError::missing_edge(raw_spell_id, child_effect_index)
                    })?;
                let next_forwarded = nested_forwarded_value(
                    EffectLookup::new(data, EffectRef::new(spell_id, child_effect_index)),
                    effect_type,
                    forwarded_value,
                );

                let mut nested_operations = Vec::new();

                resolve_trigger_spell(
                    data,
                    source_spell_id,
                    next,
                    next_forwarded,
                    depth + 1,
                    path,
                    &mut nested_operations,
                )?;

                if !nested_operations.is_empty() {
                    let delay_ms =
                        u32::try_from(data.effect_misc_value_0(spell_id, child_effect_index))
                            .unwrap_or(0);

                    operations.push(TriggerOperation::Delayed {
                        delay_ms,
                        profile_spell_id: next,
                        operations: nested_operations,
                    });
                }
            }
            _ => {
                return Err(TriggerResolveError::unsupported_child_effect(
                    raw_spell_id,
                    child_effect_index,
                    effect_type,
                    aura_subtype,
                ));
            }
        }
    }

    if operations.len() == operation_start
        && let Some((effect_index, effect_type, aura_subtype)) = first_inert_dummy
    {
        return Err(TriggerResolveError::unsupported_child_effect(
            raw_spell_id,
            effect_index,
            effect_type,
            aura_subtype,
        ));
    }

    Ok(())
}

fn nested_forwarded_value(
    lookup: EffectLookup<'_>,
    effect_type: i32,
    inherited: Option<f64>,
) -> Option<f64> {
    if matches!(
        super::super::spell_effect_kind(effect_type),
        Some(super::super::SpellEffectKind::TriggerSpellWithValue)
    ) {
        Some(lookup.base_points())
    } else {
        inherited
    }
}