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 clock;

pub use clock::FightClock;

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>,
}

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

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

/// Bounded, deterministic driver for fight simulations.
pub struct FightEngine {
    handler: OverlordLogic,
    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, true),
            seed,
            ts: 0,
            cascade_max_depth: DEFAULT_CASCADE_MAX_DEPTH,
        }
    }

    /// 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,
        };

        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));
            }
        }

        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)?;

        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(&mut 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,
                });
            }

            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(())
    }
}