wowlab_engine_combat/builder/

mod.rs

//! Fluent builder API for constructing a combat system.

pub(crate) mod aura_builder;
pub(crate) mod auto_attack_builder;
pub(crate) mod buffer_init;
pub(crate) mod built;
pub(crate) mod combat_builder;
mod compile;
mod def;
pub(crate) mod impact_effect_proc_builder;
mod lower;
pub(crate) mod spell_builder;

pub(crate) use aura_builder::AuraDefinitionDraft;
pub(crate) use auto_attack_builder::AutoAttackDefinitionDraft;
pub(crate) use built::BuiltCombatSystem;
pub(crate) use combat_builder::CombatSystemBuilder;
pub(crate) use impact_effect_proc_builder::ImpactEffectProcDefinition;
pub(crate) use lower::{InfoCtx, lower_resolved_damage};
pub(crate) use spell_builder::SpellDefinitionDraft;

/// Convert a manifest/game-data scalar to an integral millisecond duration.
///
/// # Errors
///
/// Returns [`BuilderError`] when `value` is non-finite, negative, fractional, or exceeds `u32`.
pub fn validated_milliseconds(
    value: f64,
    spell_id: u32,
    field: &'static str,
) -> Result<u32, BuilderError> {
    if !value.is_finite()
        || value < 0.0
        || value > f64::from(u32::MAX)
        || value.fract().abs() > f64::EPSILON
    {
        return Err(BuilderErrorKind::InvalidMilliseconds {
            spell_id,
            field,
            value,
        }
        .into());
    }

    Ok(wowlab_types::numeric::f64_to_u32_saturating_trunc(value))
}

/// Validate a finite non-negative scalar override.
///
/// # Errors
///
/// Returns [`BuilderError`] when `value` is negative or non-finite.
pub fn validated_nonnegative(
    value: f64,
    spell_id: u32,
    field: &'static str,
) -> Result<f64, BuilderError> {
    if !value.is_finite() || value < 0.0 {
        return Err(BuilderErrorKind::InvalidScalar {
            spell_id,
            field,
            value,
        }
        .into());
    }

    Ok(value)
}

fn validated_positive_u8(
    value: f64,
    spell_id: u32,
    field: &'static str,
) -> Result<u8, BuilderError> {
    if !value.is_finite()
        || value < 1.0
        || value > f64::from(u8::MAX)
        || value.fract().abs() > f64::EPSILON
    {
        return Err(BuilderErrorKind::InvalidPositiveU8 {
            spell_id,
            field,
            value,
        }
        .into());
    }

    Ok(wowlab_types::numeric::f64_to_u8_saturating_trunc(value))
}

/// Validate an aura stack cap.
///
/// # Errors
///
/// Returns [`BuilderError`] unless `value` is an integral value in `1..=u8::MAX`.
pub fn validated_max_stacks(
    value: f64,
    aura_id: u32,
    field: &'static str,
) -> Result<u8, BuilderError> {
    validated_positive_u8(value, aura_id, field)
}

/// Validate a channel's tick count, accepting the empty introspection map's neutral zero.
///
/// # Errors
///
/// Returns [`BuilderError`] unless `value` is an integral value in `0..=u8::MAX`.
pub fn validated_channel_tick_count(
    value: f64,
    spell_id: u32,
    field: &'static str,
) -> Result<u8, BuilderError> {
    if !value.is_finite()
        || value < 0.0
        || value > f64::from(u8::MAX)
        || value.fract().abs() > f64::EPSILON
    {
        return Err(BuilderErrorKind::InvalidChannelTickCount {
            spell_id,
            field,
            value,
        }
        .into());
    }

    Ok(wowlab_types::numeric::f64_to_u8_saturating_trunc(value))
}

/// Validate a spell charge count.
///
/// # Errors
///
/// Returns [`BuilderError`] unless `value` is an integral value in `1..=u8::MAX`.
#[cfg(test)]
pub(crate) fn validated_charges(
    value: f64,
    spell_id: u32,
    field: &'static str,
) -> Result<u8, BuilderError> {
    validated_positive_u8(value, spell_id, field)
}

wowlab_engine_macros::define_error! {
/// Error raised by the fluent builder API at construction time.
#[derive(Debug)]
#[non_exhaustive]
pub struct BuilderError {
    #[source]
    kind: BuilderErrorKind,
}

#[derive(Debug, thiserror::Error)]
enum BuilderErrorKind {
    #[error(
        "aura {aura_name:?} (id {aura_id}) already has {slot_count} buff effects; \
         split the aura or raise MAX_AURA_BUFF_EFFECTS"
    )]
    AuraEffectsFull {
        aura_name: String,
        aura_id: u32,
        slot_count: usize,
    },

    #[error("unsupported ResolvedDamageKind variant in damage_auto")]
    UnsupportedDamageKind,

    #[error("missing game data for spell {spell_id} (field: {field})")]
    MissingSpellData { spell_id: u32, field: &'static str },

    #[error("missing RPPM game data for equipped item {item_id} (driver spell {driver_spell_id})")]
    MissingItemRppmData { item_id: u32, driver_spell_id: u32 },

    #[error("missing RPPM game data for system driver spell {driver_spell_id}")]
    MissingSystemRppmData { driver_spell_id: u32 },

    #[error("invalid RPPM rate for system driver spell {driver_spell_id}: {rppm}")]
    InvalidSystemRppmData { driver_spell_id: u32, rppm: f64 },

    #[error(
        "system RPPM tracker registry exceeds local-index capacity while registering driver spell \
         {driver_spell_id} ({tracker_count} trackers)"
    )]
    SystemRppmRegistryFull {
        driver_spell_id: u32,
        tracker_count: usize,
        #[source]
        source: std::num::TryFromIntError,
    },

    #[error(
        "missing item-scaling game data for spell {spell_id} effect {effect_index} at item level {item_level}"
    )]
    MissingItemScalingData {
        spell_id: u32,
        effect_index: u8,
        item_level: i32,
    },

    #[error("invalid millisecond value for spell {spell_id} (field: {field}): {value}")]
    InvalidMilliseconds {
        spell_id: u32,
        field: &'static str,
        value: f64,
    },

    #[error("invalid non-negative scalar for spell {spell_id} (field: {field}): {value}")]
    InvalidScalar {
        spell_id: u32,
        field: &'static str,
        value: f64,
    },

    #[error("invalid positive u8 for spell {spell_id} (field: {field}): {value}")]
    InvalidPositiveU8 {
        spell_id: u32,
        field: &'static str,
        value: f64,
    },

    #[error("invalid channel tick count for spell {spell_id} (field: {field}): {value}")]
    InvalidChannelTickCount {
        spell_id: u32,
        field: &'static str,
        value: f64,
    },

    #[error("spell {spell_id} has {rank_count} empower ranks; at most 255 are supported")]
    InvalidEmpowerRankCount {
        spell_id: u32,
        rank_count: usize,
        #[source]
        source: std::num::TryFromIntError,
    },

    #[error(transparent)]
    GameData(#[from] wowlab_engine_ports::EngineError),

    #[error(transparent)]
    TriggeredDamage(#[from] wowlab_engine_domain::dbc::TriggerResolveError),

    #[error(transparent)]
    TargetPlan(#[from] wowlab_engine_domain::targeting::TargetPlanError),
}
}

impl BuilderError {
    #[must_use]
    pub fn missing_spell_data(spell_id: u32, field: &'static str) -> Self {
        BuilderErrorKind::MissingSpellData { spell_id, field }.into()
    }

    #[must_use]
    pub fn missing_item_rppm_data(item_id: u32, driver_spell_id: u32) -> Self {
        BuilderErrorKind::MissingItemRppmData {
            item_id,
            driver_spell_id,
        }
        .into()
    }

    #[must_use]
    pub fn missing_system_rppm_data(driver_spell_id: u32) -> Self {
        BuilderErrorKind::MissingSystemRppmData { driver_spell_id }.into()
    }

    #[must_use]
    pub fn invalid_system_rppm_data(driver_spell_id: u32, rppm: f64) -> Self {
        BuilderErrorKind::InvalidSystemRppmData {
            driver_spell_id,
            rppm,
        }
        .into()
    }

    #[must_use]
    pub fn system_rppm_registry_full(
        driver_spell_id: u32,
        tracker_count: usize,
        source: std::num::TryFromIntError,
    ) -> Self {
        BuilderErrorKind::SystemRppmRegistryFull {
            driver_spell_id,
            tracker_count,
            source,
        }
        .into()
    }

    #[must_use]
    pub fn missing_item_scaling_data(spell_id: u32, effect_index: u8, item_level: i32) -> Self {
        BuilderErrorKind::MissingItemScalingData {
            spell_id,
            effect_index,
            item_level,
        }
        .into()
    }

    #[cfg(test)]
    pub(crate) fn is_missing_spell_data(&self, spell_id: u32, field: &str) -> bool {
        matches!(
            &self.kind,
            BuilderErrorKind::MissingSpellData {
                spell_id: actual_spell_id,
                field: actual_field,
            } if *actual_spell_id == spell_id && *actual_field == field
        )
    }

    #[cfg(test)]
    pub(crate) const fn is_invalid_milliseconds(&self) -> bool {
        matches!(self.kind, BuilderErrorKind::InvalidMilliseconds { .. })
    }

    #[cfg(test)]
    pub(crate) const fn is_invalid_scalar(&self) -> bool {
        matches!(self.kind, BuilderErrorKind::InvalidScalar { .. })
    }

    #[cfg(test)]
    pub(crate) const fn is_invalid_positive_u8(&self) -> bool {
        matches!(self.kind, BuilderErrorKind::InvalidPositiveU8 { .. })
    }
}

impl From<BuilderErrorKind> for BuilderError {
    fn from(kind: BuilderErrorKind) -> Self {
        Self { kind }
    }
}

impl From<wowlab_engine_ports::EngineError> for BuilderError {
    fn from(source: wowlab_engine_ports::EngineError) -> Self {
        BuilderErrorKind::GameData(source).into()
    }
}

impl From<wowlab_engine_gamedata::GameDataError> for BuilderError {
    fn from(source: wowlab_engine_gamedata::GameDataError) -> Self {
        wowlab_engine_ports::EngineError::from(source).into()
    }
}

impl From<wowlab_engine_domain::dbc::TriggerResolveError> for BuilderError {
    fn from(source: wowlab_engine_domain::dbc::TriggerResolveError) -> Self {
        BuilderErrorKind::TriggeredDamage(source).into()
    }
}

impl From<wowlab_engine_domain::targeting::TargetPlanError> for BuilderError {
    fn from(source: wowlab_engine_domain::targeting::TargetPlanError) -> Self {
        BuilderErrorKind::TargetPlan(source).into()
    }
}

wowlab_engine_macros::define_error! {
/// Typed failure while compiling and assembling a combat system.
#[derive(Debug)]
#[non_exhaustive]
pub struct CombatBuildError {
    #[source]
    kind: CombatBuildErrorKind,
}

#[derive(Debug, thiserror::Error)]
enum CombatBuildErrorKind {
    #[error("rotation compile error: {0}")]
    Rotation(#[from] wowlab_engine_domain::rotation::Error),
    #[error("spec construction error: {0}")]
    Builder(#[from] BuilderError),
    #[error("{0}")]
    Engine(#[source] wowlab_engine_ports::EngineError),
}
}

impl From<wowlab_engine_domain::rotation::Error> for CombatBuildError {
    fn from(source: wowlab_engine_domain::rotation::Error) -> Self {
        Self {
            kind: CombatBuildErrorKind::Rotation(source),
        }
    }
}

impl From<BuilderError> for CombatBuildError {
    fn from(source: BuilderError) -> Self {
        Self {
            kind: CombatBuildErrorKind::Builder(source),
        }
    }
}

impl From<wowlab_engine_ports::EngineError> for CombatBuildError {
    fn from(source: wowlab_engine_ports::EngineError) -> Self {
        Self {
            kind: CombatBuildErrorKind::Engine(source),
        }
    }
}

#[cfg(test)]
mod error_tests {
    use googletest::prelude::*;

    use super::BuilderError;

    fn builder() -> super::CombatSystemBuilder {
        super::BuiltCombatSystem::builder(wowlab_engine_ports::CombatStats::default())
            .encounter(crate::test_support::default_encounter())
    }

    fn has_source<T>(error: &(dyn std::error::Error + 'static)) -> bool
    where
        T: std::error::Error + 'static,
    {
        let mut source = error.source();

        while let Some(current) = source {
            if current.is::<T>() {
                return true;
            }

            source = current.source();
        }

        false
    }

    #[gtest]
    fn wrapped_resolver_failure_retains_every_typed_source() -> Result<()> {
        let io = std::io::Error::new(std::io::ErrorKind::InvalidData, "fixture decode failed");
        let resolver = wowlab_engine_ports::ResolverError::decode("loading fixture", io);
        let error = BuilderError::from(wowlab_engine_ports::EngineError::from(resolver));

        verify_true!(has_source::<wowlab_engine_ports::ResolverError>(&error))?;
        verify_true!(has_source::<std::io::Error>(&error))?;

        Ok(())
    }

    #[gtest]
    fn invalid_rotation_retains_domain_source_with_redacted_debug() -> Result<()> {
        let rotation = wowlab_types::sim::Rotation {
            version: 2,
            ..wowlab_types::sim::Rotation::empty()
        };
        let error = builder()
            .build(rotation)
            .expect_err("invalid rotation must fail construction");

        verify_that!(
            error.to_string(),
            eq(
                "rotation compile error: validation failed: unsupported rotation format version 2 (this build understands version 1)"
            )
        )?;
        verify_true!(has_source::<wowlab_engine_domain::rotation::Error>(&error))?;
        let debug = format!("{error:?}");

        verify_true!(debug.contains("Rotation"))?;

        Ok(())
    }

    #[gtest]
    fn builder_failure_retains_builder_source_and_exact_outer_message() -> Result<()> {
        let error = builder()
            .spell("broken", 42, |_| {
                Err(BuilderError::missing_spell_data(42, "fixture"))
            })
            .build(wowlab_types::sim::Rotation::empty())
            .expect_err("pending builder failure must stop construction");

        verify_that!(
            error.to_string(),
            eq("spec construction error: missing game data for spell 42 (field: fixture)")
        )?;
        verify_true!(has_source::<BuilderError>(&error))?;
        let debug = format!("{error:?}");

        verify_true!(debug.contains("Builder"))?;

        Ok(())
    }

    #[gtest]
    fn populated_game_data_without_item_driver_rppm_fails_construction() -> Result<()> {
        const DRIVER_SPELL_ID: u32 = 123;
        const ITEM_ID: u32 = 42;

        let mut data = wowlab_engine_gamedata::ResolvedGameData::builder();

        data.insert_coefficient(
            wowlab_types::sim::SpellIdx::from_raw(DRIVER_SPELL_ID),
            1,
            1.0,
        );
        let error = builder()
            .game_data(data.build())
            .register_item_rppm_from_data(ITEM_ID, DRIVER_SPELL_ID)
            .build(wowlab_types::sim::Rotation::empty())
            .expect_err("missing required item RPPM must stop construction");

        verify_that!(
            error.to_string(),
            eq(
                "spec construction error: missing RPPM game data for equipped item 42 \
                 (driver spell 123)"
            )
        )?;

        verify_true!(has_source::<BuilderError>(&error))
    }

    #[gtest]
    fn empty_introspection_data_allows_unresolved_item_driver_rppm() -> Result<()> {
        let result = builder()
            .register_item_rppm_from_data(42, 123)
            .build(wowlab_types::sim::Rotation::empty());

        verify_true!(result.is_ok())
    }
}