wowlab_engine_sim/

engine.rs

use wowlab_engine_ports::{
    AuraEventRef, Event, SimContext, SimRunError, SimState, SpecAction, SpecHandler,
};
use wowlab_engine_telemetry::TelemetrySink;
use wowlab_types::{constants::MS_PER_SECOND, sim::SimTime};

use crate::{Result, queue::EventQueue, telemetry::TelemetryAccumulator};

const MAX_EVENTS: u32 = 500_000;
const LAST_ENDPOINT_PRIORITY: u8 = 3;

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum RunMode {
    Aggregate,
    CaptureRepresentative,
}

/// Mutable references shared across simulation iterations.
pub struct SimEngineRefs<'a> {
    pub telemetry: &'a mut TelemetryAccumulator,
    pub handler: &'a mut dyn SpecHandler,
    /// Reusable event queue, cleared by the caller before each iteration.
    pub queue: &'a mut EventQueue,
    /// Per-iteration telemetry sink, cleared by [`SimEngine::run`].
    pub sink: &'a mut TelemetrySink,
}

impl std::fmt::Debug for SimEngineRefs<'_> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("SimEngineRefs")
            .field("telemetry", &self.telemetry)
            .field("handler", &"<dyn SpecHandler>")
            .field("queue", &self.queue)
            .field("sink", &self.sink)
            .finish()
    }
}

/// Event loop for a single sim iteration; queue and handler are borrowed for reuse across iterations.
// docref:start des-sim-engine-struct
pub struct SimEngine<'a> {
    queue: &'a mut EventQueue,
    state: SimState,
    telemetry: &'a mut TelemetryAccumulator,
    handler: &'a mut dyn SpecHandler,
    sink: &'a mut TelemetrySink,
    encounter_end_ms: u32,
    // Readying guard: at most one PlayerReady is ever queued, else cooldown and Wait re-arms grow the queue without bound.
    pending_player_ready: Option<SimTime>,
}
// docref:end des-sim-engine-struct

impl std::fmt::Debug for SimEngine<'_> {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("SimEngine")
            .field("queue", &self.queue)
            .field("state", &self.state)
            .field("telemetry", &self.telemetry)
            .field("handler", &"<dyn SpecHandler>")
            .field("sink", &self.sink)
            .field("encounter_end_ms", &self.encounter_end_ms)
            .finish()
    }
}

impl<'a> SimEngine<'a> {
    /// Construct an iteration engine over caller-owned reusable state; the caller clears the queue and resets the handler first.
    #[must_use]
    pub fn new(state: SimState, refs: SimEngineRefs<'a>) -> Self {
        let encounter_end_ms = state.encounter_end.as_millis();
        let SimEngineRefs {
            telemetry,
            handler,
            queue,
            sink,
        } = refs;

        Self {
            queue,
            state,
            telemetry,
            handler,
            sink,
            encounter_end_ms,
            pending_player_ready: None,
        }
    }

    /// Execute one iteration to completion and record telemetry.
    ///
    /// # Errors
    ///
    /// Returns an error if the event budget is exceeded or the spec handler fails.
    pub fn run(&mut self) -> Result<()> {
        self.run_with_mode(RunMode::Aggregate)
    }

    /// Deterministically rerun one selected iteration and install only its representative trace, leaving aggregates unchanged.
    ///
    /// # Errors
    ///
    /// Returns an error if the event budget is exceeded or the spec handler fails.
    pub fn capture_representative(&mut self) -> Result<()> {
        self.run_with_mode(RunMode::CaptureRepresentative)
    }

    fn run_with_mode(&mut self, mode: RunMode) -> Result<()> {
        self.sink.clear();

        self.dispatch(|handler, c| handler.on_sim_start(c))?;
        self.push_player_ready(SimTime::ZERO);

        let mut event_count: u32 = 0;
        let mut completed_at = None;

        while let Some(event) = self.queue.pop() {
            event_count += 1;

            if event_count > MAX_EVENTS {
                return Err(SimRunError::event_budget_exceeded(event_count));
            }

            let t = event.timestamp();

            if t.as_millis() > self.encounter_end_ms
                || (t.as_millis() == self.encounter_end_ms
                    && event.priority() > LAST_ENDPOINT_PRIORITY)
            {
                break;
            }

            self.state.current_time = t;
            self.handle_event(event, t)?;

            if let Some(termination_time) = self.handler.encounter_termination_time() {
                completed_at = Some(termination_time);
                break;
            }
        }

        if completed_at.is_none() && self.queue.is_empty() {
            self.dispatch(|handler, c| handler.on_event_queue_empty(c))?;
            completed_at = self.handler.encounter_termination_time();
        }

        self.finalize(
            completed_at.unwrap_or_else(|| SimTime::from_millis(self.encounter_end_ms)),
            mode,
        );

        Ok(())
    }

    // A strictly earlier wake replaces the marker; the superseded later event stays queued and pops as a harmless deduped one-shot.
    fn push_player_ready(&mut self, t: SimTime) {
        if let Some(pending) = self.pending_player_ready {
            if pending <= t {
                return;
            }
        }

        self.pending_player_ready = Some(t);
        self.queue.push(Event::PlayerReady { t });
    }

    // #t(fn: rust_cyclomatic_complexity) the typed event dispatcher is intentionally exhaustive
    // #t(fn: rust_max_fn_lines) keeping the exhaustive event-to-handler mapping together makes priority dispatch auditable
    fn handle_event(&mut self, event: Event, t: SimTime) -> Result<()> {
        match event {
            Event::PlayerReady { .. } => self.handle_player_ready_event(t),
            Event::OffGcdReady { .. } => self.handle_player_ready(t),

            Event::CastStart {
                t,
                spell_id,
                empower_rank,
                source,
                target,
            } => {
                // docref:start event-system-cast-start-arm
                let cast_ms = self.handler.cast_time_ms(spell_id, empower_rank);
                let complete_time = SimTime::from_millis(t.as_millis().saturating_add(cast_ms));
                self.queue.push(Event::CastComplete {
                    t: complete_time,
                    spell_id,
                    empower_rank,
                    source,
                    target,
                });
                // docref:end event-system-cast-start-arm

                Ok(())
            }

            event @ Event::CastComplete { .. } => {
                self.dispatch(|handler, c| handler.on_cast_complete(event, c))
            }

            Event::TriggeredSpell {
                spell_id,
                source,
                target,
                ..
            } => self.dispatch(|handler, c| {
                handler.on_triggered_spell(spell_id, source, target, c);
            }),

            Event::SpellLaunch { impact_id, .. } => {
                self.dispatch(|handler, c| handler.on_spell_launch(impact_id, c))
            }

            Event::SpellImpact { impact_id, .. } => {
                self.dispatch(|handler, c| handler.on_spell_impact(impact_id, c))
            }

            Event::GuardianAction {
                guardian_id,
                guardian_generation,
                ability_index,
                ..
            } => self.dispatch(|handler, c| {
                handler.on_guardian_action(guardian_id, guardian_generation, ability_index, c);
            }),

            Event::GuardianExpire {
                guardian_id,
                guardian_generation,
                ..
            } => self.dispatch(|handler, c| {
                handler.on_guardian_expire(guardian_id, guardian_generation, c);
            }),

            Event::PetAction {
                auto_attack_index, ..
            } => self.dispatch(|handler, c| handler.on_pet_action(auto_attack_index, c)),

            Event::AuraTick { key, target, .. } => {
                self.dispatch(|handler, c| handler.on_aura_tick(AuraEventRef { key, target }, c))
            }

            Event::ChannelTick {
                spell_id,
                source,
                target,
                generation,
                ..
            } => self.dispatch(|handler, c| {
                handler.on_channel_tick(spell_id, source, target, generation, c);
            }),

            Event::AutoAttack { source, target, .. } => {
                self.dispatch(|handler, c| handler.on_auto_attack(source, target, c))
            }

            Event::EnemyAutoAttack { source, target, .. } => {
                self.dispatch(|handler, c| handler.on_enemy_auto_attack(source, target, c))
            }

            Event::CooldownReady { cooldown_key, .. } => {
                self.dispatch(|handler, c| handler.on_cooldown_ready(cooldown_key, c))
            }

            Event::AuraExpire { key, target, .. } => {
                self.dispatch(|handler, c| handler.on_aura_expire(AuraEventRef { key, target }, c))
            }

            Event::ProcHeartbeat { .. } => self.dispatch(|handler, c| handler.on_proc_heartbeat(c)),

            Event::Death { target, scope, .. } => {
                self.dispatch(|handler, c| handler.on_death(target, scope, c))
            }

            Event::EncounterDespawn {
                scope,
                target,
                kind,
                ..
            } => self.dispatch(|handler, c| handler.on_encounter_despawn(scope, target, kind, c)),

            Event::GroupComplete { scope, group, .. } => {
                self.dispatch(|handler, c| handler.on_group_complete(scope, group, c))
            }

            Event::PullComplete {
                scope, finalize, ..
            } => self.dispatch(|handler, c| handler.on_pull_complete(scope, finalize, c)),

            Event::EncounterTerminate { reason, .. } => {
                self.dispatch(|handler, c| handler.on_encounter_terminate(reason, c))
            }

            Event::WaveActivate { scope, wave, .. } => {
                self.dispatch(|handler, c| handler.on_wave_activate(scope, wave, c))
            }

            Event::EnemyActivate { scope, target, .. } => {
                self.dispatch(|handler, c| handler.on_enemy_activate(scope, target, c))
            }

            Event::Retarget { scope, .. } => {
                self.dispatch(|handler, c| handler.on_retarget(scope, c))
            }

            Event::EncounterMove {
                scope,
                actor,
                transform,
                ..
            } => self.dispatch(|handler, c| handler.on_encounter_move(scope, actor, transform, c)),

            Event::ActorMovement {
                actor,
                moving,
                generation,
                ..
            } => self.dispatch(|handler, c| {
                handler.on_actor_movement(actor, moving, generation, c);
            }),

            Event::RaidEvent { index, .. } => {
                self.dispatch(|handler, c| handler.on_raid_event(index, c))
            }

            Event::RaidAddDespawn {
                target,
                activation_generation,
                encounter_generation,
                ..
            } => self.dispatch(|handler, c| {
                handler.on_raid_add_despawn(target, activation_generation, encounter_generation, c);
            }),

            Event::ExternalBuff { index, .. } => {
                self.dispatch(|handler, c| handler.on_external_buff(index, c))
            }

            Event::HookTimer {
                timer_id,
                source,
                target,
                ..
            } => self.dispatch(|handler, c| handler.on_hook_timer(timer_id, source, target, c)),
        }
    }

    fn handle_player_ready_event(&mut self, t: SimTime) -> Result<()> {
        // Ignore superseded wakes: earlier wakes replace only the marker, not the already-queued event.
        if self.pending_player_ready != Some(t) {
            return Ok(());
        }

        self.pending_player_ready = None;

        self.handle_player_ready(t)
    }

    fn handle_player_ready(&mut self, t: SimTime) -> Result<()> {
        let action = {
            let mut c = sim_context(&self.state, self.sink);

            self.handler.on_player_ready(&mut c)
        };

        self.check_handler_error()?;

        match action {
            Some(SpecAction::Cast {
                spell_id,
                empower_rank,
                source,
                target,
            }) => {
                self.queue.push(Event::CastStart {
                    t,
                    spell_id,
                    empower_rank,
                    source,
                    target,
                });
            }
            Some(SpecAction::Wait { until_ms }) => {
                // Floor at now+1ms: a Wait that does not advance time would re-evaluate identical state forever.
                let min_next = t.saturating_add(SimTime::from_millis(1));
                let clamped = SimTime::from_millis(
                    until_ms
                        .max(min_next)
                        .as_millis()
                        .min(self.encounter_end_ms),
                );

                self.push_player_ready(clamped);
            }
            None => {}
        }

        flush_handler_events(
            &mut *self.handler,
            &mut *self.queue,
            &mut self.pending_player_ready,
        );

        Ok(())
    }

    fn dispatch(&mut self, f: impl FnOnce(&mut dyn SpecHandler, &mut SimContext)) -> Result<()> {
        {
            let mut c = sim_context(&self.state, self.sink);

            f(self.handler, &mut c);
        };
        self.check_handler_error()?;
        flush_handler_events(
            &mut *self.handler,
            &mut *self.queue,
            &mut self.pending_player_ready,
        );

        Ok(())
    }

    fn check_handler_error(&mut self) -> Result<()> {
        self.handler
            .take_runtime_error()
            .map_or(Ok(()), |source| Err(SimRunError::handler(source)))
    }

    fn finalize(&mut self, completed_at: SimTime, mode: RunMode) {
        let total_damage = self.handler.total_damage();

        #[cfg(debug_assertions)]
        self.debug_assert_damage_telemetry_reconciled(total_damage, completed_at, mode);

        let duration_secs = f64::from(completed_at.as_millis()) / MS_PER_SECOND;
        let dps = if duration_secs > 0.0 {
            total_damage / duration_secs
        } else {
            0.0
        };

        match mode {
            RunMode::Aggregate => {
                self.telemetry.record_sink_events(self.sink, duration_secs);
                self.telemetry.record_iteration_for(
                    self.state.seed_prefix,
                    self.state.iteration,
                    dps,
                );
            }
            RunMode::CaptureRepresentative => {
                self.telemetry
                    .install_representative(dps, self.sink, duration_secs);
            }
        }
    }

    #[cfg(debug_assertions)]
    fn debug_assert_damage_telemetry_reconciled(
        &self,
        combat_total: f64,
        completed_at: SimTime,
        mode: RunMode,
    ) {
        let Some(reconciliation) = damage_reconciliation(combat_total, self.sink) else {
            return;
        };

        debug_assert!(
            reconciliation.is_within_error_bound(),
            "damage telemetry diverged from the authoritative combat total: combat_total={:.17e}, telemetry_total={:.17e}, direct={:.17e}, periodic={:.17e}, pet={:.17e}, absolute_delta={:.17e}, relative_delta={:.17e}, error_bound={:.17e}, event_count={}, absolute_event_sum={:.17e}, iteration={}, seed_prefix={}, completed_at_ms={}, mode={mode:?}",
            reconciliation.combat_total,
            reconciliation.telemetry_total,
            reconciliation.direct,
            reconciliation.periodic,
            reconciliation.pet,
            reconciliation.absolute_delta,
            reconciliation.relative_delta,
            reconciliation.error_bound,
            reconciliation.event_count,
            reconciliation.absolute_event_sum,
            self.state.iteration,
            self.state.seed_prefix,
            completed_at.as_millis(),
        );
    }
}

#[derive(Clone, Copy, Debug)]
#[cfg(debug_assertions)]
struct DamageReconciliation {
    combat_total: f64,
    telemetry_total: f64,
    direct: f64,
    periodic: f64,
    pet: f64,
    absolute_delta: f64,
    relative_delta: f64,
    error_bound: f64,
    event_count: usize,
    absolute_event_sum: f64,
}

#[cfg(debug_assertions)]
const TELEMETRY_CATEGORY_COMBINE_ADDITIONS: usize = 2;

#[cfg(debug_assertions)]
impl DamageReconciliation {
    fn is_within_error_bound(self) -> bool {
        self.absolute_delta <= self.error_bound
    }
}

#[cfg(debug_assertions)]
fn summation_error_coefficient(additions: usize) -> f64 {
    let Ok(additions) = u32::try_from(additions) else {
        return f64::INFINITY;
    };
    let scaled_epsilon = f64::from(additions) * f64::EPSILON;

    if scaled_epsilon >= 1.0 {
        f64::INFINITY
    } else {
        scaled_epsilon / (1.0 - scaled_epsilon)
    }
}

#[cfg(debug_assertions)]
fn damage_reconciliation(combat_total: f64, sink: &TelemetrySink) -> Option<DamageReconciliation> {
    // Synthetic SpecHandler implementations may supply scalar damage for DPS-focused tests without
    // emitting event telemetry. With no event ledger there is no second representation to reconcile.
    if sink.damage.is_empty() {
        return None;
    }

    let (direct, periodic, pet, absolute_event_sum) =
        sink.damage
            .iter()
            .fold((0.0, 0.0, 0.0, 0.0), |mut totals, event| {
                if event.is_pet {
                    totals.2 += event.amount;
                } else if event.is_periodic {
                    totals.1 += event.amount;
                } else {
                    totals.0 += event.amount;
                }

                totals.3 += event.amount.abs();

                totals
            });
    let telemetry_total = direct + periodic + pet;
    let absolute_delta = (combat_total - telemetry_total).abs();
    let scale = combat_total.abs().max(telemetry_total.abs());
    let relative_delta = if scale > 0.0 {
        absolute_delta / scale
    } else {
        0.0
    };
    let event_count = sink.damage.len();
    let combat_error = summation_error_coefficient(event_count);
    let telemetry_error = summation_error_coefficient(
        event_count.saturating_add(TELEMETRY_CATEGORY_COMBINE_ADDITIONS),
    );
    let error_bound = (combat_error + telemetry_error) * absolute_event_sum;

    Some(DamageReconciliation {
        combat_total,
        telemetry_total,
        direct,
        periodic,
        pet,
        absolute_delta,
        relative_delta,
        error_bound,
        event_count,
        absolute_event_sum,
    })
}

fn sim_context<'a>(state: &'a SimState, sink: &'a mut TelemetrySink) -> SimContext<'a> {
    SimContext {
        state,
        telemetry: sink,
    }
}

fn flush_handler_events(
    handler: &mut dyn SpecHandler,
    queue: &mut EventQueue,
    pending_player_ready: &mut Option<SimTime>,
) {
    handler.flush_scheduled(&mut |event| {
        // Route handler-scheduled PlayerReady wakes through the readying guard too, else same-time cooldown wakes flood the queue.
        if let Event::PlayerReady { t } = event {
            if pending_player_ready.is_some_and(|pending| pending <= t) {
                return;
            }

            *pending_player_ready = Some(t);
        }

        queue.push(event);
    });
}

#[cfg(test)]
#[path = "engine/tests.rs"]
mod tests;