overlord_event_system/fight/

mod.rs

//! Deterministic, bounded fight simulation engine.
//!
//! Combat owns its scheduling: delayed combat events and the `FightProgress`
//! heartbeat live in the [`FightClock`] inside `OverlordLogic`,
//! not in the `System` delayed/cron plugins. The live game loop drains the
//! clock through `OverlordLogic::collect_due_scheduled`; this engine
//! drains the same clock directly. Both paths therefore run *identical*
//! combat machinery — the only difference is the driver.
//!
//! Engine properties:
//!
//! - `FightEngine::run` executes at most `max_game_ticks` steps and always
//!   returns — there is no wall-clock timeout and no way to loop forever.
//!   A fight that doesn't finish within the budget is `FightResult::Undecided`.
//! - No DB, no async, no `System`, no `PureEventHandler`: callers are
//!   PvP precalculation, balance simulations, and tests.
//! - `EndFight` is the fight boundary: the outcome is taken from the event
//!   and it is *not* processed, so progression side effects (rating,
//!   vassals, chapter advance) never run inside a simulation.

mod breakdown;
mod clock;
mod metrics;

pub use breakdown::{BreakdownAccumulator, BreakdownActor};
pub use clock::FightClock;
pub use metrics::{
    DISPERSION_IDLE_SHARE_THRESHOLD_PCT, EntityMetrics, FightMetrics, FightMetricsSummary,
    STUN_UNTIL_TICK_ATTR, TeamMetrics,
};

use std::sync::Arc;

use event_system::random::Seed;
use rand::SeedableRng;

use crate::{
    BehaviorRegistry,
    event::{OverlordEvent, PrepareFightType},
    logic::handler::OverlordLogic,
    state::OverlordState,
};

/// Ticker units per fight step. The system ticker counts milliseconds
/// (`TICKER_UNIT_DURATION_MS = 1`), and the live game loop advances the
/// ticker by 100 units per 100ms game tick — one step equals one game tick.
pub const GAME_TICK_TICKS: u64 = 100;

/// Default cap on events processed within a single step's cascade. The same
/// wall the live `System` applies per root event — shared so the engine can
/// never silently diverge from live combat on cascade depth.
pub const DEFAULT_CASCADE_MAX_DEPTH: u32 = event_system::system::EVENT_SUBGRAPH_MAX_DEPTH;

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum FightResult {
    Win,
    Loss,
    /// The tick budget was exhausted before the fight ended. Callers decide
    /// policy (PvP precalculation treats it as a loss).
    Undecided,
}

#[derive(Debug, Clone, Copy)]
pub struct FightOutcome {
    pub result: FightResult,
    /// Elapsed ticker units (1 unit = 1ms of game time).
    pub duration_ticks: u64,
}

#[derive(Debug, thiserror::Error)]
pub enum FightError {
    #[error("prepare fight produced no active fight")]
    NotPrepared,
    #[error("fight event cascade exceeded max depth {max_depth}")]
    CascadeDepthExceeded { max_depth: u32 },
}

/// A self-contained fight in progress. The scheduled work lives in the
/// engine handler's [`FightClock`]; the sim carries the simulated state and
/// logical time.
pub struct FightSim {
    state: OverlordState,
    tick: u64,
    ended: Option<FightResult>,
    /// Combat-feel metrics. A pure observer that lives outside `state`, so it
    /// never perturbs the simulation (see [`FightMetrics`]).
    metrics: FightMetrics,
}

impl FightSim {
    pub fn state(&self) -> &OverlordState {
        &self.state
    }

    pub fn tick(&self) -> u64 {
        self.tick
    }

    /// Mutable access to the simulated state, for installing a **frozen
    /// reference build** between [`FightEngine::start`] and the first step.
    ///
    /// The A2-BAL-001 calibration needs a player whose strength is the authored
    /// `S_ref` for the chapter rather than whatever gear a run happened to roll
    /// — otherwise `D_old / D_new_unscaled` measures the loot, not the change.
    /// Mutating a fight that has already been stepped is not supported: the
    /// engine's determinism guarantee covers `start` → `run`, not arbitrary
    /// edits in between.
    pub fn state_mut(&mut self) -> &mut OverlordState {
        &mut self.state
    }

    /// The raw combat-feel metrics collected so far.
    pub fn metrics(&self) -> &FightMetrics {
        &self.metrics
    }

    /// Structured, serde-serializable combat-feel summary (per-entity, per-team,
    /// hero breakout, dispersion). The hero is the fight's `player_id`.
    pub fn metrics_summary(&self) -> FightMetricsSummary {
        let player_id = self.state.active_fight.as_ref().map(|f| f.player_id);
        self.metrics.summary(player_id)
    }
}

/// Bounded, deterministic driver for fight simulations.
pub struct FightEngine {
    handler: OverlordLogic,
    /// Shared with `handler`; kept here so the metrics collector can reach the
    /// content lookups (ability range/target-type) when sampling. Read-only.
    behaviors: Arc<BehaviorRegistry>,
    seed: Seed,
    ts: u64,
    cascade_max_depth: u32,
}

impl FightEngine {
    pub fn new(
        game_config: configs::SharedGameConfig,
        behaviors: Arc<BehaviorRegistry>,
        seed: Seed,
    ) -> Self {
        Self {
            // `frontend=true` turns case-opening events into no-op successes
            // so simulations never mint items.
            handler: OverlordLogic::new(game_config, behaviors.clone(), true),
            behaviors,
            seed,
            ts: 0,
            cascade_max_depth: DEFAULT_CASCADE_MAX_DEPTH,
        }
    }

    /// Per-source damage/heal breakdown of the fight this engine last ran.
    ///
    /// The engine stops at `EndFight` without processing it, so the summary
    /// never reaches `OverlordState` here — this is how a simulation, a PvP
    /// precalculation or a test reads it.
    pub fn breakdown(
        &self,
        outcome: FightOutcome,
    ) -> Option<essences::fight_breakdown::FightBreakdown> {
        self.handler.fight_breakdown(
            matches!(outcome.result, FightResult::Win),
            outcome.duration_ticks,
        )
    }

    /// Prepare a fight on a copy of the player's state. Any pre-existing
    /// `active_fight` is discarded — the sim owns the whole fight lifecycle.
    pub fn start(
        &mut self,
        mut state: OverlordState,
        prepare_fight_type: PrepareFightType,
    ) -> Result<FightSim, FightError> {
        state.active_fight = None;
        let mut sim = FightSim {
            state,
            tick: 0,
            ended: None,
            metrics: FightMetrics::default(),
        };

        // Draw from the fight's own RNG stream — the very stream the live fight
        // replays. `OverlordLogic::event_rng` only switches onto it once a seed
        // is armed and `pre_event` consumes it on the PvP `PrepareFight`;
        // without arming here the engine silently falls back to the driver's
        // `with_ts` stream, so the precalculated outcome the player has already
        // been booked diverges from the fight they then watch. Gated to PvP to
        // mirror `pre_event`'s own gating — a PvE sim keeps the driver stream,
        // exactly as before.
        if matches!(prepare_fight_type, PrepareFightType::PVPFight { .. }) {
            self.handler.arm_fight_seed(self.seed.clone());
        }

        self.run_cascade(&mut sim, OverlordEvent::PrepareFight { prepare_fight_type })?;

        if sim.state.active_fight.is_none() {
            return Err(FightError::NotPrepared);
        }

        Ok(sim)
    }

    /// Advance the fight by exactly one game tick (100 ticker units).
    /// Returns `Some(result)` once the fight has ended.
    pub fn step(&mut self, sim: &mut FightSim) -> Result<Option<FightResult>, FightError> {
        if let Some(result) = sim.ended {
            return Ok(Some(result));
        }

        // Mirrors the live ticker pause: while the fight is paused the clock
        // does not advance and nothing fires. The caller's step budget still
        // shrinks, so a paused fight runs out of ticks instead of spinning.
        if event_system::state::State::is_ticker_paused(&sim.state) {
            return Ok(None);
        }

        sim.tick += GAME_TICK_TICKS;

        // Same drain the live System does via run_plugins: due delayed
        // combat events in (due_tick, seq) order, then the heartbeat.
        let due = self.handler.collect_due_scheduled(sim.tick);

        for event in due {
            if let Some(result) = Self::try_finish(sim, &event) {
                return Ok(Some(result));
            }

            self.run_cascade(sim, event)?;
            if let Some(result) = sim.ended {
                return Ok(Some(result));
            }
        }

        // Once per game tick, after the tick's events have settled and while the
        // fight is still ongoing: sample body-occupancy / idle-in-contact. Pure
        // read of the just-computed state (see `FightMetrics`).
        sim.metrics
            .sample(&sim.state, self.behaviors.lookups(), sim.tick);

        Ok(None)
    }

    /// Run the fight to completion, executing at most `max_game_ticks` steps.
    /// Total by construction: always returns, with `FightResult::Undecided`
    /// when the budget is exhausted.
    pub fn run(
        &mut self,
        state: OverlordState,
        prepare_fight_type: PrepareFightType,
        max_game_ticks: u64,
    ) -> Result<FightOutcome, FightError> {
        let mut sim = self.start(state, prepare_fight_type)?;
        self.run_prepared(&mut sim, max_game_ticks)
    }

    /// Drive an already-[`start`](Self::start)ed fight to completion.
    ///
    /// Split out of [`run`](Self::run) so a caller that must touch the prepared
    /// state before the first step — the A2-BAL-001 calibration installing a
    /// frozen reference build, see [`FightSim::state_mut`] — still goes through
    /// the same bounded, deterministic loop rather than reimplementing it.
    pub fn run_prepared(
        &mut self,
        sim: &mut FightSim,
        max_game_ticks: u64,
    ) -> Result<FightOutcome, FightError> {
        if let Some(result) = sim.ended {
            return Ok(FightOutcome {
                result,
                duration_ticks: sim.tick,
            });
        }

        for _ in 0..max_game_ticks {
            if let Some(result) = self.step(sim)? {
                return Ok(FightOutcome {
                    result,
                    duration_ticks: sim.tick,
                });
            }
        }

        Ok(FightOutcome {
            result: FightResult::Undecided,
            duration_ticks: sim.tick,
        })
    }

    /// The fight boundary: take the outcome from `EndFight` and mark the sim
    /// ended without processing the event — progression side effects (rating,
    /// vassals, chapter advance) belong to the live pipeline only. Single
    /// policy point for both the clock-drain (`step`) and cascade paths.
    fn try_finish(sim: &mut FightSim, event: &OverlordEvent) -> Option<FightResult> {
        let OverlordEvent::EndFight { is_win, .. } = event else {
            return None;
        };
        let result = if *is_win {
            FightResult::Win
        } else {
            FightResult::Loss
        };
        sim.ended = Some(result);
        Some(result)
    }

    /// Process one event and everything it spawns, depth-first — the
    /// `EventSubgraph` semantics. Combat scheduling happens inside the
    /// handlers via the fight clock; any delayed/cron marks still emitted by
    /// non-combat handlers during a sim are routed onto the same clock
    /// (delays) or dropped with a warning (crons — none exist in fight
    /// scope, and a simulation has no business running unrelated crons).
    fn run_cascade(&mut self, sim: &mut FightSim, root: OverlordEvent) -> Result<(), FightError> {
        let mut stack = vec![root];
        let mut processed: u32 = 0;

        while let Some(event) = stack.pop() {
            if Self::try_finish(sim, &event).is_some() {
                return Ok(());
            }

            processed += 1;
            if processed > self.cascade_max_depth {
                return Err(FightError::CascadeDepthExceeded {
                    max_depth: self.cascade_max_depth,
                });
            }

            // Observe this event against the pre-handler state (whiffs,
            // hits-while-casting). Read-only — does not touch the RNG stream,
            // emit events, or mutate `sim.state`.
            sim.metrics.observe_event(&event, &sim.state);

            let rng = rand::rngs::StdRng::seed_from_u64(self.seed.with_ts(self.ts));
            let result = self
                .handler
                .handle_event(&event, sim.state.clone(), rng, sim.tick);
            self.ts += 1;

            let (_success, mut new_state, out_events) = result.into_state_and_events();

            // Mirror System::set_state: recompute derived fields on change
            // (player power/attributes feed back into the fight entity).
            let mut next_events: Vec<OverlordEvent> = Vec::new();
            if new_state != sim.state {
                next_events = self.handler.compute_fields(&mut new_state, &sim.state);
            }
            sim.state = new_state;

            for pluginized in out_events {
                let (event, delayed, cron) = pluginized.into_parts();
                if let Some(delayed) = delayed {
                    self.handler.fight_clock.schedule(event, delayed.ticks);
                } else if cron.is_some() {
                    tracing::warn!("Ignoring cron mark for {event} inside fight simulation");
                } else {
                    next_events.push(event);
                }
            }

            // LIFO stack: push reversed so events run in emission order,
            // children before siblings (EventSubgraph::add_events).
            stack.extend(next_events.into_iter().rev());
        }

        Ok(())
    }
}