overlord_event_system/fight/

clock.rs

//! Combat scheduler owned by the fight logic itself.
//!
//! Replaces the `System` delayed/cron plugins for everything combat: delayed
//! combat events (cast wind-ups, projectile flight, `StartFight`/`EndFight`
//! grace periods, the next `PrepareFight`) live in a due-tick heap, and the
//! `FightProgress` cadence is the heartbeat. The clock is owned by
//! `OverlordLogic`, so the live `System` loop and the
//! `FightEngine` drain the exact same scheduling state — combat behaves
//! identically no matter which loop pumps it.
//!
//! Same-due-tick events fire in insertion order (deterministic refinement of
//! the old `DelayedPlugin`'s unspecified heap order); the heartbeat fires
//! after due delayed events, mirroring the old delayed-then-cron plugin
//! order. `clear` is called when a new fight is prepared, so stale events
//! from a previous fight can never leak into the next one.

use std::cmp::Reverse;
use std::collections::BinaryHeap;

use essences::combat_origin::CombatEventOrigin;

use crate::event::OverlordEvent;

#[derive(Debug, Clone)]
struct Scheduled {
    due_tick: u64,
    /// Insertion order — deterministic tie-break for equal `due_tick`.
    seq: u64,
    event: OverlordEvent,
}

impl PartialEq for Scheduled {
    fn eq(&self, other: &Self) -> bool {
        self.due_tick == other.due_tick && self.seq == other.seq
    }
}

impl Eq for Scheduled {}

impl PartialOrd for Scheduled {
    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
        Some(self.cmp(other))
    }
}

impl Ord for Scheduled {
    fn cmp(&self, other: &Self) -> std::cmp::Ordering {
        (self.due_tick, self.seq).cmp(&(other.due_tick, other.seq))
    }
}

#[derive(Debug, Clone)]
struct Heartbeat {
    event: OverlordEvent,
    rate_ticks: u64,
    last_emitted: Option<u64>,
}

#[derive(Debug, Clone)]
pub struct FightClock {
    /// Current logical tick, stamped by the handler on every event.
    now: u64,
    pending: BinaryHeap<Reverse<Scheduled>>,
    next_seq: u64,
    heartbeat: Option<Heartbeat>,
    /// Provenance of the event currently being dispatched, armed by
    /// `OverlordLogic::pre_event`. Handlers divert delayed work straight onto
    /// this clock instead of returning it, so without this the result-level
    /// restamp would miss every delayed child of a modifier's work.
    dispatch_origin: CombatEventOrigin,
}

impl Default for FightClock {
    fn default() -> Self {
        Self {
            now: 0,
            pending: BinaryHeap::new(),
            next_seq: 0,
            heartbeat: None,
            dispatch_origin: CombatEventOrigin::Core,
        }
    }
}

impl FightClock {
    /// Stamp the current tick. Called by the event handler before dispatch so
    /// `schedule` resolves relative delays against the right base.
    pub fn set_now(&mut self, tick: u64) {
        self.now = tick;
    }

    /// The tick the dispatch in progress is running at. `OverlordLogic::pre_event`
    /// stamps it in every dispatch path, so a hook that needs the current tick
    /// but does not take it as an argument (the stone triggers' per-slot
    /// cooldown) reads it from here rather than growing a parameter through
    /// `apply_success_hooks`.
    pub fn now(&self) -> u64 {
        self.now
    }

    /// Arm the provenance every subsequent `schedule` inherits. Called by
    /// `OverlordLogic::pre_event` with the dispatching event's provenance and
    /// reset to `Core` when the dispatch ends.
    pub fn set_dispatch_origin(&mut self, origin: CombatEventOrigin) {
        self.dispatch_origin = origin;
    }

    /// Schedule `event` to fire `delay_ticks` after the current tick.
    ///
    /// Inside a non-Core dispatch the event is stamped with that provenance —
    /// the delayed half of the inheritance rule. Stamping only ever *upgrades*
    /// (Core is the ambient default), so an event that was already marked by
    /// its emitter, or by the result-level restamp, is never downgraded here.
    pub fn schedule(&mut self, mut event: OverlordEvent, delay_ticks: u64) {
        if !self.dispatch_origin.is_core() {
            event.set_origin(self.dispatch_origin);
        }
        self.pending.push(Reverse(Scheduled {
            due_tick: self.now + delay_ticks,
            seq: self.next_seq,
            event,
        }));
        self.next_seq += 1;
    }

    /// Install (or replace) the recurring combat heartbeat. Fires immediately
    /// on the next collection, then every `rate_ticks`.
    pub fn set_heartbeat(&mut self, event: OverlordEvent, rate_ticks: u64) {
        self.heartbeat = Some(Heartbeat {
            event,
            rate_ticks,
            last_emitted: None,
        });
    }

    /// Drop all pending events and the heartbeat. Called when a new fight is
    /// prepared so nothing from the previous fight leaks into it.
    pub fn clear(&mut self) {
        self.pending.clear();
        self.heartbeat = None;
    }

    /// Drain everything due at `tick`: pending events in `(due_tick, seq)`
    /// order, then the heartbeat if its interval elapsed.
    pub fn collect_due(&mut self, tick: u64) -> Vec<OverlordEvent> {
        self.now = tick;

        let mut due = Vec::new();
        while self
            .pending
            .peek()
            .is_some_and(|Reverse(s)| s.due_tick <= tick)
        {
            due.push(self.pending.pop().unwrap().0.event);
        }

        if let Some(heartbeat) = &mut self.heartbeat
            && heartbeat
                .last_emitted
                .is_none_or(|last| tick.saturating_sub(last) >= heartbeat.rate_ticks)
        {
            due.push(heartbeat.event.clone());
            heartbeat.last_emitted = Some(tick);
        }

        due
    }
}

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

    fn damage(origin: CombatEventOrigin) -> OverlordEvent {
        OverlordEvent::Damage {
            by_entity_id: None,
            entity_id: uuid::Uuid::from_u128(1),
            damage: 1,
            damage_data: Default::default(),
            origin,
            source: essences::fight_breakdown::CombatSource::Other,
        }
    }

    /// The delayed half of the inheritance rule: handlers divert work straight
    /// onto the clock instead of returning it, so the clock is what stamps it.
    #[test]
    fn scheduling_inside_a_non_core_dispatch_marks_the_event() {
        let mut clock = FightClock::default();
        clock.set_dispatch_origin(CombatEventOrigin::Proc);
        clock.schedule(damage(CombatEventOrigin::Core), 100);
        clock.set_dispatch_origin(CombatEventOrigin::Core);

        let due = clock.collect_due(100);
        assert_eq!(due.len(), 1);
        assert_eq!(due[0].combat_origin(), Some(CombatEventOrigin::Proc));
    }

    /// Stamping only ever upgrades. An event already marked by its emitter must
    /// survive a Core dispatch scheduling it — the engine drains the clock and
    /// re-schedules after `post_event` has already disarmed it.
    #[test]
    fn a_core_dispatch_never_downgrades_an_already_marked_event() {
        let mut clock = FightClock::default();
        clock.set_dispatch_origin(CombatEventOrigin::Core);
        clock.schedule(damage(CombatEventOrigin::Proc), 100);

        let due = clock.collect_due(100);
        assert_eq!(due[0].combat_origin(), Some(CombatEventOrigin::Proc));
    }

    /// A Core dispatch is the ambient case: nothing is restamped.
    #[test]
    fn a_core_dispatch_leaves_core_events_alone() {
        let mut clock = FightClock::default();
        clock.schedule(damage(CombatEventOrigin::Core), 100);

        let due = clock.collect_due(100);
        assert_eq!(due[0].combat_origin(), Some(CombatEventOrigin::Core));
    }
}