wowlab_engine_rng/stochastic/

rppm.rs

const MAX_INTERVAL_S: f64 = 3.5;

// #t(rust_reinvented_constant) Domain-specific BLP safety cap in this zero-dependency leaf crate.
const MAX_BAD_LUCK_PROT_S: f64 = 1000.0;

const SAME_TIME_TOLERANCE_S: f64 = 0.001;

const BLP_THRESHOLD: f64 = 1.5;
const BLP_SLOPE: f64 = 3.0;
// #t(rust_reinvented_constant) Keep this zero-dependency leaf independent of wowlab-types.
const PERCENT: f64 = 100.0;

#[inline]
fn blp_factor(accumulated: f64, expected_interval: f64) -> f64 {
    (1.0 + ((accumulated / expected_interval) - BLP_THRESHOLD) * BLP_SLOPE).max(1.0)
}

/// RPPM (real procs per minute) state for one proc source.
// docref:start procs-rppm-tracker
#[derive(Clone, Copy, Debug)]
#[expect(
    clippy::struct_excessive_bools,
    reason = "three independent DBC scaling flags and the independent SimC bad-luck-protection switch form the tracker policy"
)]
pub struct RppmTracker {
    pub rppm: f64,
    pub last_attempt_time: f64,
    pub last_proc_time: f64,
    pub accumulated_blp: f64,
    pub haste_scales: bool,
    pub crit_scales: bool,
    pub auto_attack_speed_scales: bool,
    pub blp_enabled: bool,
}
// docref:end procs-rppm-tracker

/// Current multiplicative inputs for RPPM scaling.
#[derive(Clone, Copy, Debug)]
pub struct RppmScaling {
    pub haste_pct: f64,
    pub crit_pct: f64,
    pub auto_attack_speed_multiplier: f64,
}

impl Default for RppmScaling {
    fn default() -> Self {
        Self {
            haste_pct: 0.0,
            crit_pct: 0.0,
            auto_attack_speed_multiplier: 1.0,
        }
    }
}

/// Rolls an RPPM check with DBC-selected scaling and bad-luck protection.
pub fn roll_rppm(
    tracker: &mut RppmTracker,
    now: f64,
    scaling: RppmScaling,
    rng: &mut dyn FnMut() -> f64,
) -> bool {
    if (now - tracker.last_attempt_time).abs() < SAME_TIME_TOLERANCE_S {
        return false;
    }

    let raw_elapsed = (now - tracker.last_attempt_time).max(0.0);
    let elapsed = raw_elapsed.min(MAX_INTERVAL_S);

    let haste_factor = if tracker.haste_scales {
        1.0 + scaling.haste_pct / PERCENT
    } else {
        1.0
    };
    let crit_factor = if tracker.crit_scales {
        1.0 + scaling.crit_pct / PERCENT
    } else {
        1.0
    };
    let auto_attack_speed_factor = if tracker.auto_attack_speed_scales {
        scaling.auto_attack_speed_multiplier.max(0.0)
    } else {
        1.0
    };

    let real_ppm = tracker.rppm * haste_factor * crit_factor * auto_attack_speed_factor;
    // #t(rust_magic_numbers) 60.0 is seconds-per-minute, fundamental to RPPM formula
    let base_chance = real_ppm * (elapsed / 60.0);

    tracker.accumulated_blp += elapsed;

    let chance = if tracker.blp_enabled && real_ppm > 0.0 {
        let accumulated = tracker.accumulated_blp.min(MAX_BAD_LUCK_PROT_S);
        // #t(rust_magic_numbers) 60.0 is seconds-per-minute, fundamental to RPPM formula
        let expected_interval = 60.0 / real_ppm;
        let factor = blp_factor(accumulated, expected_interval);

        (base_chance * factor).clamp(0.0, 1.0)
    } else {
        base_chance.clamp(0.0, 1.0)
    };

    let success = rng() < chance;

    tracker.last_attempt_time = now;

    if success {
        tracker.last_proc_time = now;
        tracker.accumulated_blp = 0.0;

        true
    } else {
        false
    }
}

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

    use super::*;

    fn make_tracker(rppm: f64, haste_scales: bool) -> RppmTracker {
        RppmTracker {
            rppm,
            last_attempt_time: 0.0,
            last_proc_time: 0.0,
            accumulated_blp: 0.0,
            haste_scales,
            crit_scales: false,
            auto_attack_speed_scales: false,
            blp_enabled: true,
        }
    }

    #[gtest]
    fn zero_elapsed_never_procs_or_draws() -> Result<()> {
        let mut tracker = make_tracker(1.0, false);

        tracker.last_attempt_time = 10.0;
        let mut draws = 0;
        let mut rng = || {
            draws += 1;

            0.0
        };

        verify_that!(
            roll_rppm(&mut tracker, 10.0, RppmScaling::default(), &mut rng),
            eq(false)
        )?;

        verify_that!(draws, eq(0))
    }

    #[gtest]
    fn large_elapsed_always_procs() -> Result<()> {
        let mut tracker = make_tracker(1000.0, false);
        let mut rng = || 0.99;

        verify_that!(
            roll_rppm(&mut tracker, 120.0, RppmScaling::default(), &mut rng),
            eq(true)
        )
    }

    #[gtest]
    fn haste_scaling_doubles_chance() -> Result<()> {
        let mut tracker_no_haste = make_tracker(1.0, true);

        tracker_no_haste.blp_enabled = false;
        let mut rng = || 0.09;

        verify_that!(
            roll_rppm(&mut tracker_no_haste, 6.0, RppmScaling::default(), &mut rng),
            eq(false)
        )?;

        let mut tracker_haste = make_tracker(1.0, true);

        tracker_haste.blp_enabled = false;
        let mut rng = || 0.09;

        verify_that!(
            roll_rppm(
                &mut tracker_haste,
                6.0,
                RppmScaling {
                    haste_pct: 100.0,
                    ..RppmScaling::default()
                },
                &mut rng
            ),
            eq(true)
        )
    }

    #[gtest]
    fn last_attempt_time_updates_each_call() -> Result<()> {
        let mut tracker = make_tracker(1.0, false);
        let mut rng = || 1.0;

        roll_rppm(&mut tracker, 5.0, RppmScaling::default(), &mut rng);
        verify_that!(tracker.last_attempt_time, near(5.0, f64::EPSILON))?;

        roll_rppm(&mut tracker, 10.0, RppmScaling::default(), &mut rng);

        verify_that!(tracker.last_attempt_time, near(10.0, f64::EPSILON))
    }

    #[gtest]
    fn last_proc_time_updates_only_on_success() -> Result<()> {
        let mut miss_tracker = make_tracker(1.0, false);
        let mut miss_rng = || 1.0;

        roll_rppm(
            &mut miss_tracker,
            60.0,
            RppmScaling::default(),
            &mut miss_rng,
        );
        verify_that!(miss_tracker.last_proc_time, near(0.0, f64::EPSILON))?;

        let mut proc_tracker = make_tracker(1.0, false);
        let mut proc_rng = || 0.0;

        roll_rppm(
            &mut proc_tracker,
            60.0,
            RppmScaling::default(),
            &mut proc_rng,
        );

        verify_that!(proc_tracker.last_proc_time, near(60.0, f64::EPSILON))
    }

    #[gtest]
    fn blp_is_neutral_within_expected_interval() -> Result<()> {
        let mut tracker = make_tracker(1.0, false);
        let mut rng = || 1.0;
        let mut time = MAX_INTERVAL_S;

        while time <= 60.0 {
            roll_rppm(&mut tracker, time, RppmScaling::default(), &mut rng);
            time += MAX_INTERVAL_S;
        }

        let accumulated = tracker.accumulated_blp.min(MAX_BAD_LUCK_PROT_S);
        let expected_interval = 60.0 / tracker.rppm;

        verify_that!(
            blp_factor(accumulated, expected_interval),
            near(1.0, f64::EPSILON)
        )
    }

    #[gtest]
    fn blp_scales_chance_above_threshold() -> Result<()> {
        let mut tracker = make_tracker(1.0, false);
        let mut rng = || 1.0;
        let mut time = MAX_INTERVAL_S;

        while time <= 120.0 {
            roll_rppm(&mut tracker, time, RppmScaling::default(), &mut rng);
            time += MAX_INTERVAL_S;
        }

        let accumulated = tracker.accumulated_blp.min(MAX_BAD_LUCK_PROT_S);
        let expected_interval = 60.0 / tracker.rppm;

        verify_that!(blp_factor(accumulated, expected_interval), gt(1.0))
    }

    #[gtest]
    fn successful_proc_resets_blp() -> Result<()> {
        let mut tracker = make_tracker(1.0, false);
        let mut miss_rng = || 1.0;

        roll_rppm(&mut tracker, 3.5, RppmScaling::default(), &mut miss_rng);
        roll_rppm(&mut tracker, 7.0, RppmScaling::default(), &mut miss_rng);
        roll_rppm(&mut tracker, 10.5, RppmScaling::default(), &mut miss_rng);
        verify_that!(tracker.accumulated_blp, gt(0.0))?;

        let mut proc_rng = || 0.0;

        verify_that!(
            roll_rppm(&mut tracker, 14.0, RppmScaling::default(), &mut proc_rng),
            eq(true)
        )?;

        verify_that!(tracker.accumulated_blp, near(0.0, f64::EPSILON))
    }

    #[gtest]
    fn elapsed_per_call_is_capped_at_maximum_interval() -> Result<()> {
        let mut tracker = make_tracker(1.0, false);
        let mut rng = || 1.0;

        roll_rppm(&mut tracker, 100.0, RppmScaling::default(), &mut rng);

        verify_that!(tracker.accumulated_blp, near(MAX_INTERVAL_S, f64::EPSILON))
    }
}