overlord_event_system/logic/

handler.rs

use crate::{
    BehaviorRegistry, attributes, event::OverlordEvent, game_config_helpers::GameConfigLookup,
    state::OverlordState,
};

use std::sync::Arc;

use configs::game_config::GameConfig;

use analytics::constants::METRICS_TARGET;

use essences::{
    ad_usage::{AdPlacement, AdUsageData},
    character_state::CharacterState,
    combat_origin::CombatEventOrigin,
    currency::{
        CurrencyConsumer, CurrencySource, CurrencyUnit, check_can_decrease_currencies,
        decrease_currencies, increase_currencies,
    },
    entity::EntityState,
    fighting::ActiveFight,
    mail::Mail,
    offers::OfferTemplate,
    quest::{QuestGroupType, QuestInstance},
    stones::StoneKind,
};

pub use event_system::{
    event::{EventPluginized, EventStruct},
    plugin::{cron::CronMark, delayed::DelayedMark},
    system::EventHandleResult,
};

/// A fight's own random stream: one seed per match, one fight-local draw
/// counter. Both drivers bump it on exactly the same events, so the fight the
/// player watches rolls identically to the fight that was persisted.
#[derive(Debug)]
struct FightRng {
    seed: event_system::random::Seed,
    draw: u64,
}

#[derive(Debug)]
pub struct OverlordLogic {
    pub(super) game_config: configs::SharedGameConfig,
    pub(super) behaviors: Arc<BehaviorRegistry>,
    pub(super) frontend: bool,
    pub(super) start_fight_tick: u64,
    /// Combat scheduler: delayed combat events + the FightProgress heartbeat.
    /// Drained via `collect_due_scheduled` by whichever loop drives this
    /// handler — the live `System` or the `FightEngine`.
    pub(crate) fight_clock: crate::fight::FightClock,
    /// Seed handed over for the PvP fight that is about to be prepared. A PvP
    /// outcome is decided by a precalculation and persisted before the player
    /// sees anything; the live fight must therefore replay that exact fight
    /// rather than roll a second one. One-shot: armed by the caller that ran
    /// the precalculation, consumed by the next `PrepareFight{PVPFight}`.
    ///
    /// Deliberately not in `OverlordState`: state is JSON-patched to the
    /// client, and a client holding the seed could precompute the outcome.
    pending_fight_seed: Option<event_system::random::Seed>,
    /// Provenance of the event being dispatched right now: `Core` for genuine
    /// combat, non-Core while a modifier's work is resolving. Armed by
    /// `pre_event`, consumed by `post_event`.
    dispatch_origin: CombatEventOrigin,
    /// The armed fight's stream, live for the duration of the fight.
    fight_rng: Option<FightRng>,
    /// Stream key drawn for the event currently being dispatched, assigned by
    /// `pre_event` and read by `event_rng`. `None` when the event is not part
    /// of a seeded fight, in which case the driver's own RNG is used.
    current_fight_draw: Option<u64>,
    /// Id of the last fight whose `EndFight` was processed. Producers can race
    /// two `EndFight` events for one fight (max-duration timeout + an
    /// in-flight projectile death); the end-of-fight pipeline (PvP rating,
    /// vassal, reward bundles, chapter advance) must run exactly once.
    pub(super) ended_fight_id: Option<uuid::Uuid>,
    /// Per-fight damage/heal accumulator, keyed by fight INSTANCE id.
    ///
    /// Deliberately not in `OverlordState`: `active_fight` is the dominant
    /// per-tick patch cost and this changes on every hit, while the summary is
    /// needed exactly once — at `EndFight`, where it is written to
    /// `OverlordState::last_fight_breakdown`. Because `OverlordLogic` drives
    /// both the live path and `FightEngine`, live fights, the PvP
    /// precalculation and the bot sim are all covered by this one field.
    pub(super) fight_breakdown_acc: Option<crate::fight::BreakdownAccumulator>,
    /// Game time of the last party-ally DB refresh (`RefreshPartyMemberState`
    /// emission). Gates the refresh to at most once per
    /// `PARTY_REFRESH_INTERVAL_SEC`. Game time, not `FightClock` ticks: the
    /// tick counter is driven by `std::time::Instant`, which the simulation's
    /// fake clock does not scale, so ticks and game seconds diverge there.
    pub(super) last_party_refresh_at: Option<chrono::DateTime<chrono::Utc>>,
    pub(super) compute_fields_duration: opentelemetry::metrics::Histogram<f64>,
    /// Tracks the source/consumer for currency change metrics logging.
    pub(super) last_currency_source: Option<String>,
}

impl OverlordLogic {
    // No analytics span here: the unified `OverlordEventHandler::handle_event`
    // already opens the per-event METRICS_TARGET span with these exact fields,
    // and a second nested one would double span volume on the 10Hz fight path.
    /// Per-event pre-amble: stamps the combat clock so relative `schedule`
    /// calls made anywhere in the dispatch resolve against the current tick,
    /// and records the currency source label for the next `compute_fields`
    /// diff. Called by `handle_event` and by the monolith's merged
    /// (logic + persistence) arms, which bypass this dispatch.
    pub fn pre_event(&mut self, event: &OverlordEvent, current_tick: u64) {
        self.fight_clock.set_now(current_tick);

        match event {
            // A PvP fight replays the precalculation that already decided it —
            // but only if a seed was armed for it. A `PrepareFight` with no
            // precalculation behind it (PvE, or a client-sent event) finds no
            // seed and keeps the driver's own stream, exactly as before.
            OverlordEvent::PrepareFight { prepare_fight_type } => {
                self.fight_rng = match prepare_fight_type {
                    crate::event::PrepareFightType::PVPFight { .. } => self
                        .pending_fight_seed
                        .take()
                        .map(|seed| FightRng { seed, draw: 0 }),
                    _ => None,
                };
            }
            OverlordEvent::EndFight { .. } => self.fight_rng = None,
            _ => {}
        }

        self.current_fight_draw = match &mut self.fight_rng {
            Some(fight) if Self::is_fight_scoped(event) => {
                let key = fight.seed.with_fight_draw(fight.draw);
                fight.draw += 1;
                Some(key)
            }
            _ => None,
        };

        self.last_currency_source = match event {
            OverlordEvent::CurrencyIncrease {
                currency_source, ..
            } => Some(format!("{currency_source:?}")),
            OverlordEvent::CurrencyDecrease {
                currency_consumer, ..
            } => Some(format!("{currency_consumer:?}")),
            other => Some(other.to_string()),
        };

        // Provenance pre-amble. Everything this dispatch produces inherits the
        // dispatching event's mark: the result events are restamped in
        // `post_event`, and the delayed ones — which handlers push straight
        // onto the clock instead of returning — are stamped by the clock while
        // it stays armed.
        self.dispatch_origin = event.carried_origin().unwrap_or(CombatEventOrigin::Core);
        self.fight_clock.set_dispatch_origin(self.dispatch_origin);
    }

    /// Provenance of the dispatch in progress. Anything this dispatch queues on
    /// an entity's action queue must be stamped with it, because the queue
    /// drains on a later tick, long after `post_event` disarmed the scope.
    ///
    /// Two kinds of queue entry deliberately do *not* take this mark and stay
    /// Core: an ability's cooldown re-arm and a charge-driven pet ult. Both are
    /// the entity's own cadence — the same metronome ticks with or without a
    /// modifier — so marking them would turn every later swing into a
    /// modifier's product and switch triggers off for the rest of the fight.
    /// See [`essences::entity::EntityActionsQueue::push_start_cast_replacing`].
    pub fn dispatch_origin(&self) -> CombatEventOrigin {
        self.dispatch_origin
    }

    /// Closing half of the provenance pre-amble: disarms the clock and
    /// restamps everything this dispatch is handing back.
    ///
    /// Must run at the end of every dispatch that called
    /// [`OverlordLogic::pre_event`] — this one included, plus the monolith's
    /// merged (logic + persistence) arms, which replicate the wrapper without
    /// going through `handle_event`.
    ///
    /// The restamp only ever *upgrades* to a non-Core mark, so an event a
    /// modifier already marked cannot be reset by a later Core dispatch. Events
    /// that carry no provenance (`SpawnEntity`, `FightProgress`, the flip) are
    /// left alone by `set_origin` — see
    /// [`crate::event::OverlordEvent::carried_origin`] for why those are
    /// boundaries rather than gaps, and
    /// [`OverlordLogic::dispatch_origin`] for the delayed hop through the
    /// entity action queue.
    pub fn post_event(&mut self, result: &mut EventHandleResult<OverlordEvent, OverlordState>) {
        let origin = std::mem::replace(&mut self.dispatch_origin, CombatEventOrigin::Core);
        self.fight_clock
            .set_dispatch_origin(CombatEventOrigin::Core);
        if origin.is_core() {
            return;
        }
        for out in result.events_mut() {
            out.event_mut().set_origin(origin);
        }
    }

    /// Add one applied damage/heal amount to the fight's breakdown.
    ///
    /// Keyed on the fight INSTANCE: a new fight replaces the accumulator, and a
    /// delayed hit that outlives its fight cannot land in the next one. Pure
    /// bookkeeping — it reads nothing from state and writes nothing back, which
    /// is what keeps the PvP replay identical to its precalculation.
    #[allow(clippy::too_many_arguments)]
    pub(super) fn record_fight_breakdown(
        &mut self,
        fight_instance_id: uuid::Uuid,
        fight_id: essences::fighting::FightTemplateId,
        actor: crate::fight::BreakdownActor,
        source: essences::fight_breakdown::CombatSource,
        damage: u64,
        heal: u64,
        crit: bool,
    ) {
        let acc = match &mut self.fight_breakdown_acc {
            Some(acc) if acc.fight_instance_id() == fight_instance_id => acc,
            _ => self
                .fight_breakdown_acc
                .insert(crate::fight::BreakdownAccumulator::new(
                    fight_instance_id,
                    fight_id,
                )),
        };
        acc.record(actor, source, damage, heal, crit);
    }

    /// The breakdown accumulated for the fight in progress, as a summary.
    ///
    /// The live path does not need this — `handle_end_fight` drains the
    /// accumulator into `OverlordState::last_fight_breakdown`. It exists for
    /// [`crate::fight::FightEngine`], which deliberately does NOT process
    /// `EndFight` (progression side effects must not run inside a simulation)
    /// and so would otherwise have no way to read what its fight produced.
    pub fn fight_breakdown(
        &self,
        is_win: bool,
        duration_ticks: u64,
    ) -> Option<essences::fight_breakdown::FightBreakdown> {
        self.fight_breakdown_acc
            .as_ref()
            .map(|acc| acc.finish(is_win, duration_ticks))
    }

    /// Hand the next `PrepareFight{PVPFight}` the seed of the precalculation
    /// whose outcome was persisted, so the live fight reproduces it.
    pub fn arm_fight_seed(&mut self, seed: event_system::random::Seed) {
        self.pending_fight_seed = Some(seed);
    }

    /// RNG for the event `pre_event` was just called with: the fight's own
    /// stream for fight-scoped events of a seeded fight, otherwise the driver's.
    ///
    /// Must be called after `pre_event` and exactly once per dispatched event —
    /// `pre_event` is what advances the fight's draw counter.
    pub fn event_rng(&self, driver_rng: rand::rngs::StdRng) -> rand::rngs::StdRng {
        use rand::SeedableRng as _;

        match self.current_fight_draw {
            Some(key) => rand::rngs::StdRng::seed_from_u64(key),
            None => driver_rng,
        }
    }

    /// Whether an event belongs to the fight's own random stream.
    ///
    /// The membership rule is an invariant, not a taste call: an event belongs
    /// here **iff only fight machinery can produce it**. Admitting an event
    /// that a non-fight cascade can also emit desyncs the counter — the live
    /// loop would bump on an interleaved tap that the precalculation never saw,
    /// and every roll after it diverges. Omitting an event the fight does emit
    /// desyncs it the other way.
    ///
    /// `EndFight` is deliberately absent: `FightEngine` takes the outcome from
    /// it without dispatching it (`fight::FightEngine::try_finish`), so bumping
    /// on it would count in the live loop only.
    pub fn is_fight_scoped(event: &OverlordEvent) -> bool {
        matches!(
            event,
            OverlordEvent::PrepareFight { .. }
                | OverlordEvent::StartFight { .. }
                | OverlordEvent::FightProgress {}
                | OverlordEvent::WaveCleared { .. }
                | OverlordEvent::SpawnEntity { .. }
                | OverlordEvent::StartMove { .. }
                | OverlordEvent::EndMove { .. }
                | OverlordEvent::MoveProgress { .. }
                | OverlordEvent::StartCastAbility { .. }
                | OverlordEvent::StartedCastAbility { .. }
                | OverlordEvent::CastAbility { .. }
                | OverlordEvent::StartCastProjectile { .. }
                | OverlordEvent::StartedCastProjectile { .. }
                | OverlordEvent::DerivedAbilityStrike { .. }
                | OverlordEvent::EntityIncrAttributeDelayed { .. }
                | OverlordEvent::CastProjectile { .. }
                | OverlordEvent::Damage { .. }
                | OverlordEvent::GlobalFlip { .. }
                | OverlordEvent::StoneTriggerFired { .. }
                | OverlordEvent::Heal { .. }
                | OverlordEvent::CounterAttack { .. }
                | OverlordEvent::Multicast { .. }
                | OverlordEvent::Evasion { .. }
                | OverlordEvent::PlayerDeath {}
                | OverlordEvent::EntityDeath { .. }
                | OverlordEvent::EntityIncrAttribute { .. }
                | OverlordEvent::EntityAddAbilityCooldown { .. }
                | OverlordEvent::EntityCancelCastWithCooldown { .. }
                | OverlordEvent::EntityStun { .. }
                | OverlordEvent::EntityApplyEffect { .. }
                | OverlordEvent::CastEffect { .. }
                | OverlordEvent::CastEffectFromEvent { .. }
                | OverlordEvent::FightCustomEvent { .. }
                | OverlordEvent::FightVisualEvent { .. }
        )
    }

    /// Effect `events_subscribe` scan: when a fight is active, effects applied
    /// to entities can react to any event by casting. The returned events are
    /// appended to the handling result's events (after the success hooks).
    pub fn effect_subscription_events(
        &self,
        event: &OverlordEvent,
        state: &OverlordState,
    ) -> Vec<EventPluginized<OverlordEvent, OverlordState>> {
        // Effects react to combat and nothing else. `events_subscribe` is
        // GameConfig data, so without this gate a subscription to, say,
        // `OpenItemCase` would let a chest opened mid-fight cast into the
        // fight — in the live session only, since the precalculation never
        // sees the player's taps.
        if !Self::is_fight_scoped(event) {
            return Vec::new();
        }

        let game_config = self.game_config.get();
        let mut events: Vec<EventPluginized<OverlordEvent, OverlordState>> = Vec::new();
        if let Some(fight) = &state.active_fight {
            for entity in &fight.entities {
                for effect_id in &entity.effect_ids {
                    // Config drift: an effect can be removed from GameConfig
                    // while still applied to an entity in an active fight.
                    // Skip the stale effect instead of failing every event for
                    // the session before dispatch.
                    let Some(effect) = game_config.effect(*effect_id) else {
                        tracing::warn!(
                            "Skipping unknown effect with id = {effect_id} on fight entity {}",
                            entity.id
                        );
                        continue;
                    };
                    if let Some(events_subscribe) = &effect.events_subscribe
                        && events_subscribe.contains(&event.to_string())
                    {
                        events.push(EventPluginized::now(OverlordEvent::CastEffectFromEvent {
                            entity_id: entity.id,
                            effect_id: effect.id,
                            caller_event: Box::new(event.clone()),
                        }));
                    }
                }
            }
        }
        events
    }

    /// Cross-cutting success hooks: quest progress, offer triggers, Trigger
    /// Stone fires, law reactions and the artifact's flip/heartbeat Aspect
    /// rules. Runs for every successfully handled event, both here and in the
    /// monolith's merged arms.
    ///
    /// Stone triggers hang off this hook rather than off the combat arms on
    /// purpose: the surface they react to
    /// ([`crate::event::OverlordEvent::is_core_combat_event`]) is a property of
    /// the event, not of which arm handled it, and a merged arm added later for
    /// one of those events would otherwise silently switch the mechanic off.
    /// `&mut self` for the fight clock the timed effects schedule their expiry
    /// on.
    pub fn apply_success_hooks(
        &mut self,
        state: &mut OverlordState,
        events: &mut Vec<EventPluginized<OverlordEvent, OverlordState>>,
        event: &OverlordEvent,
    ) {
        self.update_quests_progress(state, events, event);
        self.try_give_new_offers(state, events, event);
        self.apply_stone_triggers(state, events, event);
        // Laws stay immediately after the stones: a stone fire moves the flip
        // gauge and switches the side synchronously, and the law hook is meant
        // to see that. Artifact Aspects run last so they observe the settled
        // side rather than the one that is about to change.
        self.apply_law_reactions(state, events, event);
        self.apply_artifact_aspects(state, events, event);
        // Pet Facets spend last: they are Derived payoffs that hang off the
        // same Core outcome the stones and laws just reacted to, and nothing
        // they emit is trigger surface, so running them after settles the order
        // without changing anyone's reading of the event.
        self.apply_pet_facets(state, events, event);
    }

    pub fn handle_event(
        &mut self,
        event: &OverlordEvent,
        state: OverlordState,
        rand_gen: rand::rngs::StdRng,
        current_tick: u64,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        self.pre_event(event, current_tick);
        let rand_gen = self.event_rng(rand_gen);
        let mut events = self.effect_subscription_events(event, &state);

        let mut result = match &event {
            // Items
            OverlordEvent::OpenItemCase { batch_size } => {
                self.handle_open_item_case(*batch_size, rand_gen, state)
            }
            OverlordEvent::AutoChestOpenItemCase { batch_size } => {
                self.handle_auto_chest_open_item_case(*batch_size, rand_gen, state)
            }
            OverlordEvent::PlinkoBallDropped { item_id, path } => {
                self.handle_plinko_ball_dropped(*item_id, path, state)
            }
            OverlordEvent::PlayerEquipItem { item_id } => {
                self.handle_player_equip_item(*item_id, state)
            }
            OverlordEvent::SellItem { item_id } => self.handle_sell_item(*item_id, state),
            OverlordEvent::ItemSold { .. } => self.handle_noop(state),
            OverlordEvent::ItemsExpired { .. } => self.handle_noop(state),
            OverlordEvent::PlayerNewItems { items } => self.handle_player_new_items(items, state),
            OverlordEvent::UpgradeItemCase {} => self.handle_noop(state),
            OverlordEvent::ItemCaseUpgraded {} => self.handle_noop(state),
            OverlordEvent::SpeedupUpgradeItemCase {} => self.handle_noop(state),
            OverlordEvent::SkipUpgradeItemCase {} => self.handle_noop(state),
            OverlordEvent::ClaimUpgradeItemCase {} => self.handle_noop(state),

            OverlordEvent::EnableAutoSell {} => self.handle_enable_auto_sell(state),
            OverlordEvent::DisableAutoSell {} => self.handle_disable_auto_sell(state),

            OverlordEvent::SetGearOverrideEnabled { item_type, enabled } => {
                self.handle_set_gear_override_enabled(*item_type, *enabled, state)
            }

            OverlordEvent::EnableCaseUpgradePopUp {} => {
                self.handle_enable_case_upgrade_pop_up(state)
            }
            OverlordEvent::DisableCaseUpgradePopUp {} => {
                self.handle_disable_case_upgrade_pop_up(state)
            }

            // Abilities
            OverlordEvent::OpenAbilityCase { .. } => self.handle_noop(state),
            OverlordEvent::SetAbilityGachaWishlist { .. } => self.handle_noop(state),
            OverlordEvent::UpgradeAbilitySlot { .. } => self.handle_noop(state),
            OverlordEvent::AbilityCaseOpened { .. } => self.handle_noop(state),
            OverlordEvent::NewAbilities { .. } => self.handle_noop(state),
            OverlordEvent::UpgradeAbilityCase {} => self.handle_noop(state),

            // Ability stones: validation, state mutation and persistence all
            // live in the monolith handler (it needs the DB), so the pure logic
            // layer has nothing to do here.
            OverlordEvent::SocketAbilityStone { .. } => self.handle_noop(state),
            OverlordEvent::UnsocketAbilityStone { .. } => self.handle_noop(state),
            OverlordEvent::UpgradeAbilityStone { .. } => self.handle_noop(state),
            OverlordEvent::QuickEquipAbilityStones { .. } => self.handle_noop(state),
            OverlordEvent::UpgradeAllAbilityStones {} => self.handle_noop(state),
            OverlordEvent::UpgradedAbilityStones { .. } => self.handle_noop(state),
            OverlordEvent::NewAbilityStones { .. } => self.handle_noop(state),
            OverlordEvent::FastEquipAbilities {} => self.handle_noop(state),
            OverlordEvent::EquipAbility {
                slot_id,
                ability_id,
            } => self.handle_equip_ability(*slot_id, *ability_id, current_tick, state),
            OverlordEvent::UnequipAbility { slot_id } => {
                self.handle_unequip_ability(*slot_id, state)
            }
            OverlordEvent::EquipAbilities { equipped_abilities } => {
                self.handle_equip_abilities(equipped_abilities.clone(), current_tick, state)
            }
            OverlordEvent::UpgradeAbility { .. } => self.handle_noop(state),
            OverlordEvent::UpgradeAllAbilities {} => self.handle_noop(state),
            OverlordEvent::UpgradedAbilities { .. } => self.handle_noop(state),
            // Report-only, exactly like UpgradedAbilities: the levels are
            // already applied by UpgradeAllStones, this only carries the result
            // out to the client and the quest board.
            OverlordEvent::UpgradedStones { .. } => self.handle_noop(state),

            // Fight management
            OverlordEvent::StartGame {} => self.handle_noop(state),
            OverlordEvent::PrepareFight { prepare_fight_type } => {
                self.handle_prepare_fight(prepare_fight_type.clone(), rand_gen, state)
            }
            OverlordEvent::StartFight { fight_id } => {
                self.handle_start_fight(event.clone(), *fight_id, rand_gen, current_tick, state)
            }
            OverlordEvent::EndFight {
                fight_id,
                is_win,
                pvp_state,
            } => self.handle_end_fight(*fight_id, *is_win, pvp_state.as_deref(), rand_gen, state),
            OverlordEvent::StageCleared {} => self.handle_noop(state),
            OverlordEvent::RaidDungeon { .. } => self.handle_noop(state),

            // Moving
            OverlordEvent::StartMove {
                entity_id,
                to,
                duration_ticks,
            } => self.handle_start_move(*entity_id, to.clone(), *duration_ticks, state),
            OverlordEvent::EndMove { entity_id } => self.handle_end_move(*entity_id, state),
            OverlordEvent::MoveProgress { entity_id, to } => {
                self.handle_move_progress(*entity_id, to.clone(), state)
            }

            // Fighting
            OverlordEvent::SpawnEntity {
                id,
                entity_template_id,
                position,
                entity_team,
                has_big_hp_bar,
                entity_attributes,
            } => self.handle_spawn_entity(
                *id,
                *entity_template_id,
                position.clone(),
                entity_team.clone(),
                *has_big_hp_bar,
                entity_attributes.clone(),
                current_tick,
                state,
            ),
            OverlordEvent::FightProgress {} => self.handle_fight_progress(current_tick, state),
            OverlordEvent::StartCastAbility {
                by_entity_id,
                ability_id,
                ..
            } => self.handle_start_cast_ability(
                event.clone(),
                *by_entity_id,
                *ability_id,
                rand_gen,
                current_tick,
                state,
            ),
            OverlordEvent::StartedCastAbility { .. } => self.handle_noop(state),
            OverlordEvent::CastAbility {
                by_entity_id,
                to_entity_id,
                ability_id,
                ..
            } => self.handle_cast_ability(
                event.clone(),
                *by_entity_id,
                *to_entity_id,
                *ability_id,
                rand_gen,
                state,
            ),
            OverlordEvent::StartCastProjectile {
                by_entity_id,
                to_entity_id,
                projectile_id,
                level,
                delay: _,
                // Carried, not consumed: `pre_event` already armed the dispatch
                // with this event's provenance.
                origin: _,
                source,
            } => self.handle_start_cast_projectile(
                event.clone(),
                *by_entity_id,
                *to_entity_id,
                *projectile_id,
                *level,
                *source,
                current_tick,
                state,
            ),
            OverlordEvent::StartedCastProjectile { .. } => self.handle_noop(state),
            OverlordEvent::DerivedAbilityStrike {
                by_entity_id,
                to_entity_id,
                ability_id,
                level,
                payload_permille,
                source_paid_mana_x100,
                ..
            } => self.handle_derived_ability_strike(
                *by_entity_id,
                *to_entity_id,
                *ability_id,
                *level,
                *payload_permille,
                *source_paid_mana_x100,
                rand_gen,
                state,
            ),
            // Only ever produced with a delay and routed onto the fight clock,
            // which re-emits it as a plain `EntityIncrAttribute`.
            OverlordEvent::EntityIncrAttributeDelayed {
                entity_id,
                attribute,
                delta,
                ..
            } => self.handle_entity_incr_attribute(
                *entity_id,
                attribute,
                *delta,
                current_tick,
                state,
            ),
            OverlordEvent::CastProjectile {
                by_entity_id,
                to_entity_id,
                projectile_id,
                level,
                projectile_data,
                origin: _,
                source,
            } => self.handle_cast_projectile(
                event.clone(),
                *by_entity_id,
                *to_entity_id,
                *projectile_id,
                *level,
                projectile_data,
                *source,
                rand_gen,
                current_tick,
                state,
            ),
            OverlordEvent::Damage {
                by_entity_id,
                entity_id,
                damage,
                damage_data,
                // Provenance is carried, not consumed: no trigger system reads
                // it yet, and `handle_damage` behaves identically either way.
                origin: _,
                source,
            } => self.handle_damage(
                *by_entity_id,
                *entity_id,
                *damage,
                damage_data,
                *source,
                rand_gen,
                state,
            ),
            // The Team Die rolls INSIDE this arm, before the law layer runs —
            // see `logic::pet_facets` for why that ordering is the acceptance
            // criterion rather than a preference.
            OverlordEvent::GlobalFlip {
                entity_id,
                from_side,
                to_side,
                revision,
                ..
            } => {
                let mut rng = rand_gen;
                self.handle_global_flip(
                    *entity_id, *from_side, *to_side, *revision, &mut rng, state,
                )
            }
            OverlordEvent::Heal {
                by_entity_id,
                entity_id,
                heal,
                source,
                ..
            } => self.handle_heal(*by_entity_id, *entity_id, *heal, *source, state),
            OverlordEvent::CounterAttack { .. } => self.handle_noop(state),
            OverlordEvent::WaveCleared {} => self.handle_noop(state),
            OverlordEvent::Multicast { .. } => self.handle_noop(state),
            // Pure client-facing marker — see the variant's doc.
            OverlordEvent::StoneTriggerFired { .. } => self.handle_noop(state),
            OverlordEvent::Evasion { .. } => self.handle_noop(state),
            OverlordEvent::PlayerDeath {} => self.handle_player_death(state),
            OverlordEvent::EntityDeath {
                entity_id, reward, ..
            } => self.handle_entity_death(*entity_id, reward.clone(), rand_gen, state),
            OverlordEvent::EntityIncrAttribute {
                entity_id,
                attribute,
                delta,
            } => self.handle_entity_incr_attribute(
                *entity_id,
                attribute,
                *delta,
                current_tick,
                state,
            ),
            OverlordEvent::EntityAddAbilityCooldown {
                entity_id,
                ability_id,
                delta_ticks,
            } => self.handle_entity_add_ability_cooldown(
                *entity_id,
                *ability_id,
                *delta_ticks,
                current_tick,
                state,
            ),
            OverlordEvent::EntityCancelCastWithCooldown {
                entity_id,
                ability_id,
            } => self.handle_entity_cancel_cast_with_cooldown(
                *entity_id,
                *ability_id,
                current_tick,
                state,
            ),
            OverlordEvent::EntityStun {
                entity_id,
                duration_ticks,
            } => self.handle_entity_stun(*entity_id, *duration_ticks, current_tick, state),
            OverlordEvent::EntityApplyEffect {
                entity_id,
                effect_id,
                ..
            } => self.handle_entity_apply_effect(*entity_id, *effect_id, current_tick, state),
            OverlordEvent::CastEffect {
                entity_id,
                effect_id,
                ..
            } => {
                self.handle_cast_effect(*entity_id, *effect_id, None, rand_gen, current_tick, state)
            }
            OverlordEvent::CastEffectFromEvent {
                entity_id,
                effect_id,
                caller_event,
            } => self.handle_cast_effect(
                *entity_id,
                *effect_id,
                Some(caller_event.to_owned()),
                rand_gen,
                current_tick,
                state,
            ),
            OverlordEvent::FightCustomEvent { .. } => self.handle_noop(state),
            OverlordEvent::FightVisualEvent { .. } => self.handle_noop(state),
            OverlordEvent::NewCharacterLevel { level } => {
                self.handle_new_character_level(*level, state)
            }

            // Vassal links
            OverlordEvent::ClaimSuzerainReward {} => self.handle_noop(state),
            OverlordEvent::ClaimVassalReward { .. } => self.handle_noop(state),
            OverlordEvent::NewSuzerain { new_suzerain } => {
                self.handle_new_suzerain(new_suzerain.as_deref().cloned(), state)
            }
            OverlordEvent::RemoveVassal { vassal_id } => {
                self.handle_remove_vassal(*vassal_id, state)
            }

            // Quests
            OverlordEvent::ClaimQuest { quest_id } => {
                self.handle_claim_quest(*quest_id, rand_gen, state)
            }
            OverlordEvent::NewQuests { quest_ids } => {
                self.handle_new_quests(quest_ids.clone(), state)
            }
            OverlordEvent::UpdateActiveLoopTaskId { quest_id } => {
                self.handle_update_active_loop_task_id(*quest_id, state)
            }

            OverlordEvent::ClaimQuestProgressionReward { quest_group_type } => {
                self.handle_claim_quest_progression_reward(quest_group_type.to_owned(), state)
            }

            OverlordEvent::ResetRepeatingQuests { quest_ids } => {
                self.handle_reset_repeating_quests(quest_ids.clone(), state)
            }

            // Vassal Tasks
            OverlordEvent::GiveTask { .. } => self.handle_noop(state),
            OverlordEvent::NewTask { new_task } => {
                self.handle_new_task((**new_task).clone(), state)
            }
            OverlordEvent::AcceptTask { task_id, is_good } => {
                self.handle_accept_task(*task_id, *is_good, state)
            }
            OverlordEvent::TaskAccepted {
                task_id,
                started_good,
                started_at,
                finish_at,
            } => self.handle_task_accepted(*task_id, *started_good, *started_at, *finish_at, state),
            OverlordEvent::HitHands { task_id } => self.handle_hit_hands(*task_id, state),
            OverlordEvent::HandsHitted { task_id } => self.handle_hands_hitted(*task_id, state),
            OverlordEvent::ClaimTaskReward { task_id } => {
                self.handle_claim_task_reward(*task_id, state)
            }
            OverlordEvent::TaskFinished { task_id } => self.handle_finish_task(*task_id, state),

            // Resist Task
            OverlordEvent::GiveResistTask { new_resist_task } => {
                self.handle_give_resist_task((**new_resist_task).clone(), state)
            }
            OverlordEvent::AcceptResistTask {} => self.handle_noop(state),
            OverlordEvent::ResistTaskAccepted { new_resist_task } => {
                self.handle_resist_task_accepted((**new_resist_task).clone(), state)
            }
            OverlordEvent::CatchResistTask { task_id } => {
                self.handle_catch_resist_task(*task_id, state)
            }
            OverlordEvent::ResistTaskCatched { task_id } => {
                self.handle_resist_task_catched(*task_id, state)
            }
            OverlordEvent::ResistTaskFinished { task_id } => {
                self.handle_resist_task_finished(*task_id, state)
            }
            OverlordEvent::ClaimResistTaskReward { task_id } => {
                self.handle_claim_resist_task_reward(*task_id, state)
            }

            // Gifts
            OverlordEvent::SendGift {
                receiver_id,
                config_gift_id,
            } => self.handle_send_gift(*receiver_id, *config_gift_id, state),
            OverlordEvent::NewGift { new_gift } => {
                self.handle_new_gift((**new_gift).clone(), state)
            }
            OverlordEvent::AcceptGift { gift_id } => self.handle_accept_gift(*gift_id, state),

            // PVP
            OverlordEvent::StartVassalPVPSync { .. } => self.handle_noop(state),
            OverlordEvent::StartArenaPVPSync { .. } => self.handle_noop(state),
            OverlordEvent::StartArenaRematchSync { .. } => self.handle_noop(state),
            OverlordEvent::RefreshArenaMatchmaking {} => self.handle_noop(state),
            OverlordEvent::BuyArenaTicket {} => self.handle_noop(state),
            OverlordEvent::SetArenaWorldSide { side } => {
                self.handle_set_arena_world_side(*side, state)
            }

            // Referral Rewards
            OverlordEvent::ClaimReferralLvlUpReward { level } => {
                self.handle_claim_referral_lvlup_reward(*level, state)
            }
            OverlordEvent::ClaimReferralDailyReward {} => {
                self.handle_claim_referral_daily_reward(state)
            }
            OverlordEvent::PatronQuestCompleted { quest_id } => {
                self.handle_patron_quest_completed(*quest_id, state)
            }
            OverlordEvent::HiddenQuestCompleted { quest_id } => {
                self.handle_hidden_quest_completed(*quest_id, rand_gen, state)
            }
            OverlordEvent::QuestCompleted { .. } => self.handle_noop(state),
            OverlordEvent::ReferralDailyRewardStatusUpdate {
                referral_daily_reward_status,
            } => self
                .handle_referral_daily_reward_status_update(*referral_daily_reward_status, state),

            // AutoChest
            OverlordEvent::EnableAutoChest {} => self.handle_enable_auto_chest(state),
            OverlordEvent::DisableAutoChest {} => self.handle_disable_auto_chest(state),

            OverlordEvent::EnableAutoChestFilter { filter_id } => {
                self.handle_enable_auto_chest_filter(*filter_id, state)
            }
            OverlordEvent::DisableAutoChestFilter {} => {
                self.handle_disable_auto_chest_filter(state)
            }

            OverlordEvent::EnableAutoChestPowerCompare {} => {
                self.handle_enable_auto_chest_power_compare(state)
            }
            OverlordEvent::DisableAutoChestPowerCompare {} => {
                self.handle_disable_auto_chest_power_compare(state)
            }

            OverlordEvent::UpdateAutoChestBatchSize { batch_size } => {
                self.handle_update_auto_chest_batch_size(*batch_size, state)
            }

            OverlordEvent::NewAutoChestFilter { filter } => {
                self.handle_new_auto_chest_filter((**filter).clone(), state)
            }

            OverlordEvent::UpdateAutoChestFilter { updated_filter } => {
                self.handle_update_auto_chest_filter((**updated_filter).clone(), state)
            }

            OverlordEvent::RemoveAutoChestFilter { filter_id } => {
                self.handle_remove_auto_chest_filter(*filter_id, state)
            }

            // Technical
            OverlordEvent::SetCustomValue { key, value } => {
                self.handle_set_custom_value(key.clone(), *value, state)
            }
            OverlordEvent::SetConnectionStore { key, value } => {
                self.handle_set_connection_store(key.clone(), *value, state)
            }

            // Ability Presets
            OverlordEvent::CreateAbilityPreset { .. } => self.handle_noop(state),
            OverlordEvent::EditAbilityPreset { .. } => self.handle_noop(state),

            // AfkReward
            OverlordEvent::ClaimAfkReward {} => self.handle_noop(state),
            OverlordEvent::AfkRewardClaimed {} => self.handle_noop(state),
            OverlordEvent::AfkRewardsGatingUnlocked {} => {
                self.handle_afk_rewards_gating_unlocked(state)
            }
            OverlordEvent::ClaimAfkInstantRewardGems {} => self.handle_noop(state),

            // Bundles
            OverlordEvent::ClaimBundleStepGeneric { .. } => self.handle_noop(state),
            OverlordEvent::AddBundleGroup { bundle_ids, source } => {
                self.handle_add_bundle_group(bundle_ids, *source, state)
            }

            // Classes
            OverlordEvent::LevelUpClass { .. } => self.handle_noop(state),
            OverlordEvent::Respec { .. } => self.handle_noop(state),

            // User Account
            OverlordEvent::LinkGuestAccount { .. } => self.handle_noop(state),
            OverlordEvent::SetUsername { .. } => self.handle_noop(state),
            OverlordEvent::SetCharacterBlocked { .. } => self.handle_noop(state),

            // Cheat
            OverlordEvent::SetMaxHp {
                entity_id,
                new_max_hp,
                new_hp,
            } => self.handle_set_max_hp(*entity_id, *new_max_hp, *new_hp, state),

            OverlordEvent::RunCheat { cheat } => {
                self.handle_run_cheat(cheat, current_tick, rand_gen, state)
            }

            OverlordEvent::Error { .. } => self.handle_noop(state),
            OverlordEvent::CustomEvent { .. } => self.handle_noop(state),

            // Currencies — the event itself performs the state mutation
            OverlordEvent::CurrencyIncrease { currencies, .. } => {
                self.handle_currency_increase(currencies, state)
            }
            OverlordEvent::CurrencyDecrease { currencies, .. } => {
                self.handle_currency_decrease(currencies, state)
            }
            // Skins
            OverlordEvent::BuySkins { .. } => self.handle_noop(state),
            OverlordEvent::EquipAndUnequipSkins { .. } => self.handle_noop(state),

            // Mails
            OverlordEvent::ClaimMail { .. } => self.handle_noop(state),
            OverlordEvent::ClaimAllMails {} => self.handle_noop(state),
            OverlordEvent::ClaimAllQuests { .. } => self.handle_noop(state),
            OverlordEvent::MakeRead { .. } => self.handle_noop(state),
            OverlordEvent::MakeAllRead {} => self.handle_noop(state),
            OverlordEvent::DeleteMail { .. } => self.handle_noop(state),
            OverlordEvent::DeleteAllMails {} => self.handle_noop(state),
            OverlordEvent::NewMail { new_mail } => {
                self.handle_new_mail((**new_mail).clone(), state)
            }
            // Offers
            OverlordEvent::NewOffer { .. } => self.handle_noop(state),
            OverlordEvent::BuyOffer { .. } => self.handle_noop(state),
            OverlordEvent::ResetOffers { new_offers } => {
                self.handle_reset_offers(new_offers, state)
            }
            OverlordEvent::OfferPurchaseCompleted { .. } => self.handle_noop(state),
            OverlordEvent::OfferPurchaseFailed { .. } => self.handle_noop(state),
            OverlordEvent::PurchasesBanned {} => self.handle_purchases_banned(state),

            // Pets
            OverlordEvent::EquipPet { slot_id, pet_id } => {
                self.handle_equip_pet(*slot_id, *pet_id, current_tick, state)
            }
            OverlordEvent::UnequipPet { slot_id } => {
                self.handle_unequip_pet(*slot_id, current_tick, state)
            }
            OverlordEvent::FastEquipPets {} => self.handle_noop(state),
            OverlordEvent::EquipPets { equipped_pets } => {
                self.handle_equip_pets(equipped_pets.clone(), current_tick, state)
            }
            OverlordEvent::UpgradePet { .. } => self.handle_noop(state),
            OverlordEvent::UpgradeAllPets {} => self.handle_noop(state),
            OverlordEvent::UpgradedPets { .. } => self.handle_noop(state),
            OverlordEvent::UpgradePetSlot { .. } => self.handle_noop(state),
            OverlordEvent::SetPetFacetLaw {
                role,
                law_template_id,
            } => self.handle_set_pet_facet_law(*role, *law_template_id, state),

            // Pet Gacha
            OverlordEvent::OpenPetCase { .. } => self.handle_noop(state),
            OverlordEvent::SetPetGachaWishlist { .. } => self.handle_noop(state),
            OverlordEvent::PetCaseOpened { .. } => self.handle_noop(state),
            OverlordEvent::NewPets { .. } => self.handle_noop(state),
            OverlordEvent::UpgradePetCase {} => self.handle_noop(state),

            // Tutorial
            OverlordEvent::TutorialShown { .. } => self.handle_noop(state),
            OverlordEvent::TutorialStepCompleted { step_number } => {
                self.handle_tutorial_step_completed(*step_number, state)
            }
            OverlordEvent::ClientLifecycle { .. } => self.handle_noop(state),
            OverlordEvent::SetFightContentLoading { fight_id, loading } => {
                self.handle_set_fight_content_loading(*fight_id, *loading, state)
            }

            // Party
            OverlordEvent::AddCharacterToParty { .. } => self.handle_noop(state),
            OverlordEvent::RemoveCharacterFromParty {} => self.handle_noop(state),
            OverlordEvent::RefreshPartyPlayers {} => self.handle_noop(state),
            OverlordEvent::RefreshPartyMemberState {} => self.handle_noop(state),

            // Talent Tree
            OverlordEvent::StartTalentResearch { .. } => self.handle_noop(state),
            OverlordEvent::TalentResearchStarted { .. } => self.handle_noop(state),
            OverlordEvent::SpeedupTalentResearch {} => self.handle_noop(state),
            OverlordEvent::SkipTalentResearch {} => self.handle_noop(state),
            OverlordEvent::ClaimTalentResearch {} => self.handle_claim_talent_research(state),

            // Statue
            OverlordEvent::StatueRoll { .. } => self.handle_noop(state),
            OverlordEvent::StatueActivateSet { .. } => self.handle_noop(state),
            OverlordEvent::StatueAddSet {} => self.handle_noop(state),
            OverlordEvent::StatueRenameSet { .. } => self.handle_noop(state),
            OverlordEvent::StatueLockSlot { .. } => self.handle_noop(state),
            OverlordEvent::StatueRollNewSlot { .. } => self.handle_noop(state),
            // Cores / laws / bridges — all validated and persisted in the
            // monolith ws handler; the shared logic layer only carries state.
            OverlordEvent::UpgradeCore { .. } => self.handle_noop(state),
            OverlordEvent::ResetCores {} => self.handle_noop(state),
            OverlordEvent::UpgradeLaw { .. } => self.handle_noop(state),
            OverlordEvent::SlotLaw { .. } => self.handle_noop(state),
            OverlordEvent::UnslotLaw { .. } => self.handle_noop(state),
            OverlordEvent::CreateLawBridge { .. } => self.handle_noop(state),
            OverlordEvent::RemoveLawBridge { .. } => self.handle_noop(state),
            OverlordEvent::NewLawCopies { .. } => self.handle_noop(state),
            // Progress Pass
            OverlordEvent::ClaimProgressPassFreeReward { .. } => self.handle_noop(state),
            OverlordEvent::ClaimProgressPassPaidReward { .. } => self.handle_noop(state),
            OverlordEvent::ClaimAllProgressPassRewards { .. } => self.handle_noop(state),
            OverlordEvent::ClaimRatingRewards { .. } => self.handle_noop(state),
            OverlordEvent::SetRatingRewardAvailability { availability } => {
                self.handle_set_rating_reward_availability(availability.clone(), state)
            }
            OverlordEvent::UserRating { .. } => self.handle_noop(state),
            OverlordEvent::ShowRateUs {} => self.handle_noop(state),
            OverlordEvent::RateUsShown {} => self.handle_rate_us_shown(state),
            OverlordEvent::RateUs { .. } => self.handle_noop(state),
            OverlordEvent::WatchAd { .. } => self.handle_noop(state),
            OverlordEvent::ShowBird { .. } => self.handle_show_bird(state),
            OverlordEvent::BirdShown {} => self.handle_bird_shown(state),
            OverlordEvent::ResetAdUsage { placements } => {
                self.handle_reset_ad_usage(placements, state)
            }
            OverlordEvent::ResetInstantRewardGemsPressCount {} => {
                self.handle_reset_instant_reward_gems_press_count(state)
            }
            // Trigger/Effect Stones
            OverlordEvent::InsertStone {
                template_id,
                item_type,
                socket,
            } => self.handle_insert_stone(*template_id, *item_type, *socket, state),
            OverlordEvent::RemoveStone { template_id } => {
                self.handle_remove_stone(*template_id, state)
            }
            OverlordEvent::UpgradeStone { template_id } => {
                self.handle_upgrade_stone(*template_id, state)
            }
            // Unlike `FastEquipAbilities` / `UpgradeAllAbilities`, which are
            // `handle_noop` here because their data lives in monolith-only
            // tables, a stone inventory IS part of `character_state` — so both
            // bulk stone actions are ordinary pure transitions and run
            // identically in both dispatch paths.
            OverlordEvent::QuickEquipStones { item_type } => {
                self.handle_quick_equip_stones(*item_type, state)
            }
            OverlordEvent::UpgradeAllTriggerStones {} => {
                self.handle_upgrade_all_stones(StoneKind::Trigger, state)
            }
            OverlordEvent::UpgradeAllEffectStones {} => {
                self.handle_upgrade_all_stones(StoneKind::Effect, state)
            }
            OverlordEvent::PlayerNewStones {
                trigger_stones,
                effect_stones,
            } => self.handle_player_new_stones(trigger_stones, effect_stones, state),

            // Artifacts
            OverlordEvent::EquipArtifact { template_id } => {
                self.handle_equip_artifact(*template_id, state)
            }
            OverlordEvent::InsertArtifactStone {
                template_id,
                socket,
            } => self.handle_insert_artifact_stone(*template_id, *socket, state),
            OverlordEvent::RemoveArtifactStone { template_id } => {
                self.handle_remove_artifact_stone(*template_id, state)
            }
            OverlordEvent::UpgradeArtifactStone { template_id } => {
                self.handle_upgrade_artifact_stone(*template_id, state)
            }
            OverlordEvent::UpgradeArtifact { template_id } => {
                self.handle_upgrade_artifact(*template_id, state)
            }
            OverlordEvent::SetArtifactStoneLawTarget {
                template_id,
                law_template_id,
            } => self.handle_set_artifact_stone_law_target(*template_id, *law_template_id, state),
            OverlordEvent::PlayerNewArtifacts {
                artifacts,
                artifact_stones,
            } => self.handle_player_new_artifacts(artifacts, artifact_stones, state),
            OverlordEvent::FireArtifactEffect {
                owner_id,
                effect_template_id,
                effect_level,
                share_permyriad,
                artifact_stone_id,
            } => self.handle_fire_artifact_effect(
                *owner_id,
                *effect_template_id,
                *effect_level,
                *share_permyriad,
                *artifact_stone_id,
                state,
            ),
        };

        if result.success() {
            let (state, events) = result.state_and_events_mut();
            self.apply_success_hooks(state, events, event);
        }

        result.events_mut().append(&mut events);
        self.post_event(&mut result);
        result
    }

    /// Where the fight clock currently stands. The loop that drives a fight
    /// owns the clock; this is the read a caller needs to ask
    /// [`Self::collect_due_scheduled`] for a point in the future.
    pub fn fight_clock_now(&self) -> u64 {
        self.fight_clock.now()
    }

    pub fn collect_due_scheduled(&mut self, current_tick: u64) -> Vec<OverlordEvent> {
        self.fight_clock.collect_due(current_tick)
    }

    pub fn compute_fields(
        &self,
        state: &mut OverlordState,
        prev_state: &OverlordState,
    ) -> Vec<OverlordEvent> {
        let _span = tracing::info_span!("compute_fields").entered();
        let start = std::time::Instant::now();
        let game_config = self.game_config.get();
        let mut events = Vec::new();
        self.log_currency_change_metrics(state, prev_state);

        if state.character_state.character.character_experience
            != prev_state.character_state.character.character_experience
        {
            events.append(&mut self.compute_character_level(state));
        }

        if state.character_state != prev_state.character_state {
            match attributes::calculate_player_entity_stats_with_zeroes(
                &EntityState::Character(&state.character_state),
                &game_config,
            ) {
                Ok(attributes) => {
                    state.character_state.player_attributes = attributes.attributes.clone();
                    state.character_state.player_attributes.remove_zeroes();

                    // A PvP fight was decided by a precalculation on a frozen
                    // snapshot and its outcome is already persisted. Anything
                    // that happens to the character while the player watches it
                    // — an equip, a level-up, an auto-chest — must not reach the
                    // entity in the ring, or the fight on screen stops being the
                    // fight that was booked.
                    if state.pvp_state.is_none()
                        && let Some(fight) = &mut state.active_fight
                        && let Some(entity) = fight
                            .entities
                            .iter_mut()
                            .find(|ent| ent.id == fight.player_id)
                    {
                        // Laws (OVT-2517) are side-dependent, so they live on
                        // the fight entity and NOT in the character-derived
                        // aggregation below. The overwrite is keyed by attribute
                        // code and replaces only the codes the character itself
                        // carries a non-zero value for — so it wipes some law
                        // deltas and leaves others untouched. Strip the whole
                        // law contribution first and fold it back after, which
                        // is exact either way; a blind re-add would double-count
                        // every law that moves a stat no other source touches.
                        //
                        // The snapshot comes off the ENTITY's own cores, so what
                        // is stripped is exactly what was folded in, whatever
                        // has happened to `character_state` since the fight
                        // started.
                        let law_snapshot = entity
                            .flip_state
                            .map(|flip| flip.active_side)
                            .map(|active_side| {
                                crate::entities::law_attribute_snapshot(
                                    entity,
                                    active_side,
                                    &game_config,
                                )
                            })
                            .unwrap_or_default();

                        // The strip below momentarily takes the entity down to
                        // its LAWLESS max HP, and the law-delta helper clamps
                        // current HP to max (correct on a flip, where losing the
                        // law really should cost the margin). Here the law is
                        // not going away — it is being taken off and put back
                        // within one recompute — so the clamp must not fire on
                        // that intermediate state, or every mob kill would shave
                        // an HP law's whole margin off a full-HP player.
                        let hp_before = entity.hp;

                        if !law_snapshot.is_empty() {
                            crate::entities::apply_law_attribute_change(
                                entity,
                                &law_snapshot,
                                &Default::default(),
                                &game_config,
                            );
                        }

                        entity.max_hp = attributes.max_hp;
                        entity
                            .attributes
                            .0
                            .extend(attributes.attributes.0.iter().map(|(k, v)| (k.clone(), *v)));
                        entity.attributes.remove_zeroes();

                        if !law_snapshot.is_empty() {
                            crate::entities::apply_law_attribute_change(
                                entity,
                                &Default::default(),
                                &law_snapshot,
                                &game_config,
                            );
                            // Round-trip is HP-neutral: same law contribution in
                            // and out, so effective HP must be exactly what it
                            // was, bounded by the final max.
                            entity.hp = hp_before.min(entity.max_hp);
                        }
                    }
                }
                Err(err) => {
                    tracing::error!("Failed to fill player entity attributes: {:?}", err);
                }
            }

            match crate::behaviors::power::character_power(
                &crate::behaviors::power::CharacterPowerCtx {
                    character: &state.character_state,
                    config: &game_config,
                    lookups: self.behaviors.lookups(),
                },
            ) {
                Ok(power) => state.character_state.character.power = power,
                Err(err) => tracing::error!("Couldn't calculate player power: {err:?}"),
            }
        }

        self.compute_fields_duration
            .record(start.elapsed().as_secs_f64(), &[]);

        events
    }
}

impl OverlordLogic {
    pub fn new(
        game_config: configs::SharedGameConfig,
        behaviors: Arc<BehaviorRegistry>,
        frontend: bool,
    ) -> Self {
        let meter = opentelemetry::global::meter("compute_fields");
        Self {
            game_config,
            behaviors,
            frontend,
            start_fight_tick: 0,
            fight_breakdown_acc: None,
            fight_clock: crate::fight::FightClock::default(),
            pending_fight_seed: None,
            dispatch_origin: CombatEventOrigin::Core,
            fight_rng: None,
            current_fight_draw: None,
            ended_fight_id: None,
            last_party_refresh_at: None,
            last_currency_source: None,
            compute_fields_duration: meter
                .f64_histogram("compute_fields_duration_seconds")
                .with_boundaries(vec![
                    0.0001, 0.0005, 0.001, 0.002, 0.005, 0.01, 0.02, 0.05, 0.1,
                ])
                .build(),
        }
    }

    /// Sets the source label used by `log_currency_change_metrics` for the next
    /// `compute_fields` diff. Use when state mutations happen outside the normal
    /// `CurrencyIncrease` / `CurrencyDecrease` event flow (e.g., starter bundle
    /// seeding on character creation).
    pub fn set_last_currency_source(&mut self, source: Option<CurrencySource>) {
        self.last_currency_source = source.map(|s| format!("{s:?}"));
    }

    /// Swaps the config this logic reads from. Locale-translated configs only
    /// differ in localized strings, so swapping mid-session is safe — used by
    /// the backend to switch a connection to the user's localized GameConfig
    /// once their language is known after auth.
    pub fn set_game_config(&mut self, game_config: configs::SharedGameConfig) {
        self.game_config = game_config;
    }

    pub fn handle_set_custom_value(
        &self,
        key: String,
        value: i64,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        state
            .character_state
            .character
            .custom_values
            .insert(&key, value);
        EventHandleResult::ok(state)
    }

    fn handle_set_connection_store(
        &self,
        key: String,
        value: i64,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        state.connection_store.insert(key, value);
        EventHandleResult::ok(state)
    }

    pub fn handle_new_character_level(
        &self,
        level: i64,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        state.character_state.character.character_level = level;

        EventHandleResult::ok(state)
    }

    fn handle_purchases_banned(
        &self,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        state.character_state.character.purchases_banned = true;
        EventHandleResult::ok(state)
    }

    fn handle_new_mail(
        &self,
        new_mail: Mail,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        if !state.incoming_mails.contains(&new_mail) {
            state.incoming_mails.push(new_mail);
        }

        EventHandleResult::ok(state)
    }

    pub fn handle_noop(
        &self,
        state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        EventHandleResult::ok(state)
    }

    pub fn handle_set_fight_content_loading(
        &self,
        fight_id: uuid::Uuid,
        loading: bool,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        let Some(fight) = state.active_fight.as_mut() else {
            tracing::warn!(
                %fight_id,
                loading,
                "Ignoring fight content loading state without an active fight"
            );
            return if loading {
                EventHandleResult::fail(state)
            } else {
                EventHandleResult::ok(state)
            };
        };

        if fight.id != fight_id {
            tracing::warn!(
                %fight_id,
                active_fight_id = %fight.id,
                loading,
                "Ignoring stale fight content loading state"
            );
            return if loading {
                EventHandleResult::fail(state)
            } else {
                EventHandleResult::ok(state)
            };
        }

        fight.paused = loading;
        tracing::info!(
            %fight_id,
            loading,
            "Updated fight content loading state"
        );

        EventHandleResult::ok(state)
    }

    pub fn handle_tutorial_step_completed(
        &self,
        step_number: i16,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        if !state
            .character_state
            .character
            .completed_tutorials
            .contains(&step_number)
        {
            state
                .character_state
                .character
                .completed_tutorials
                .push(step_number);
        } else {
            tracing::error!("Provided step {step_number} is already in state");
        }
        EventHandleResult::ok(state)
    }
}

impl OverlordLogic {
    fn log_currency_change_metrics(&self, state: &OverlordState, prev_state: &OverlordState) {
        let character_id = state.character_state.character.id;
        // Chapter the player is in as this currency change lands, so a per-run
        // report can attribute faucet/sink per chapter (the glut detector).
        let chapter_level = state.character_state.character.current_chapter_level;
        let current_currencies = &state.character_state.currencies;
        let prev_currencies = &prev_state.character_state.currencies;
        let source = self.last_currency_source.as_deref().unwrap_or("unknown");

        // These currency events are emitted inline (not through the monolith's
        // deferred-metrics span), so they need their own run-id tagging for the
        // per-run balance report to isolate them. Enter a parent span carrying
        // the sim run id ONLY when set — in production it is empty, so no span
        // is entered and these events are byte-identical to before.
        let run_id = analytics::run_id::run_id();
        let _run_span = (!run_id.is_empty())
            .then(|| tracing::info_span!(target: METRICS_TARGET, "sim_run", run_id = %run_id));
        let _run_guard = _run_span.as_ref().map(|s| s.enter());

        for current_currency in current_currencies {
            let amount_before = prev_currencies
                .iter()
                .find(|unit| unit.currency_id == current_currency.currency_id)
                .map_or(0, |unit| unit.amount);
            let delta = current_currency.amount - amount_before;
            let amount_after = current_currency.amount;
            if delta > 0 {
                tracing::info!(
                    target: METRICS_TARGET,
                    character_id = %character_id,
                    event_type = "increase_currency",
                    currency_id = %current_currency.currency_id,
                    amount = delta,
                    amount_before,
                    amount_after,
                    chapter_level,
                    source = %source,
                    "Add currency",
                );
            } else if delta < 0 {
                tracing::info!(
                    target: METRICS_TARGET,
                    character_id = %character_id,
                    event_type = "decrease_currency",
                    currency_id = %current_currency.currency_id,
                    amount = -delta,
                    amount_before,
                    amount_after,
                    chapter_level,
                    source = %source,
                    "Decrease currency",
                );
            }
        }

        for prev_currency in prev_currencies {
            if current_currencies
                .iter()
                .any(|unit| unit.currency_id == prev_currency.currency_id)
            {
                continue;
            }

            // Currency disappeared from state: emit a decrease whose
            // post-balance is 0 (entry removed). Pre-balance is the value the
            // prev state still carried.
            let delta = -prev_currency.amount;
            if delta > 0 {
                tracing::info!(
                    target: METRICS_TARGET,
                    character_id = %character_id,
                    event_type = "increase_currency",
                    currency_id = %prev_currency.currency_id,
                    amount = delta,
                    amount_before = prev_currency.amount,
                    amount_after = prev_currency.amount + delta,
                    chapter_level,
                    source = %source,
                    "Add currency",
                );
            } else if delta < 0 {
                tracing::info!(
                    target: METRICS_TARGET,
                    character_id = %character_id,
                    event_type = "decrease_currency",
                    currency_id = %prev_currency.currency_id,
                    amount = -delta,
                    amount_before = prev_currency.amount,
                    amount_after = 0_i64,
                    chapter_level,
                    source = %source,
                    "Decrease currency",
                );
            }
        }
    }

    pub fn compute_character_level(&self, state: &mut OverlordState) -> Vec<OverlordEvent> {
        let game_config = self.game_config.get();
        let stored_level = state.character_state.character.character_level;
        let experience = state.character_state.character.character_experience;

        // Highest level the current experience unlocks — unbounded via the level
        // formula above the authored table. `.max(stored_level)` keeps leveling
        // monotonic (never drops the persisted level, e.g. after a config
        // rollback that lowered the authored max).
        let new_level = game_config
            .level_for_experience(experience)
            .max(stored_level);

        if new_level != stored_level {
            vec![OverlordEvent::NewCharacterLevel { level: new_level }]
        } else {
            Vec::new()
        }
    }

    fn try_give_new_offers(
        &self,
        state: &mut OverlordState,
        events: &mut Vec<EventPluginized<OverlordEvent, OverlordState>>,
        trigger_event: &OverlordEvent,
    ) {
        for offer in &self.game_config.get().offers_templates {
            if !offer.enabled {
                continue;
            }

            if offer.limit_of_buys.is_some_and(|limit| {
                state
                    .offers_info
                    .offer_buy_counts
                    .get(&offer.id)
                    .copied()
                    .unwrap_or(0)
                    >= limit as u32
            }) {
                continue;
            }

            if state
                .offers_info
                .active_offers
                .iter()
                .any(|x| x.template_id == offer.id)
            {
                continue;
            }

            if !offer.events_subscribe.contains(&trigger_event.to_string()) {
                continue;
            }

            let should_give =
                match self.should_give_new_offer(&state.character_state, offer, trigger_event) {
                    Ok(progress) => progress,
                    Err(e) => {
                        tracing::error!(
                            "Failed determining for offer id: {}\n Error: {e:?}",
                            offer.id
                        );
                        continue;
                    }
                };

            if should_give {
                events.push(EventPluginized::now(OverlordEvent::NewOffer {
                    offer_template_id: offer.id,
                }));
            }
        }
    }

    fn should_give_new_offer(
        &self,
        character_state: &CharacterState,
        offer: &OfferTemplate,
        trigger_event: &OverlordEvent,
    ) -> anyhow::Result<bool> {
        // By the time we get here the candidate offer is already `enabled` and
        // the firing event is in its `events_subscribe` list (see
        // `try_give_new_offers`), so a subscribing offer is auto-given when its
        // event fires. No deployed offer subscribes to any event, so this path
        // only drives the test fixture's triggered offers.
        crate::behaviors::quests::triggers::always_trigger(
            &crate::behaviors::quests::triggers::TriggerCtx {
                trigger_event,
                character: character_state,
                offer,
                config: &self.game_config.get(),
            },
        )
    }

    fn update_quests_progress(
        &self,
        state: &mut OverlordState,
        events: &mut Vec<EventPluginized<OverlordEvent, OverlordState>>,
        trigger_event: &OverlordEvent,
    ) {
        let game_config = self.game_config.get();
        let mut progress_pass_tier_completed = false;
        let all_active_quests = state.quest_groups.get_not_claimed_quests_mut();
        let active_fight = &state.active_fight;

        for active_quest in all_active_quests {
            let Some(quest_template) = game_config.quest(active_quest.id) else {
                continue;
            };

            if state.patron.is_none()
                && (quest_template.quest_group_type == QuestGroupType::PatronLifetime
                    || quest_template.quest_group_type == QuestGroupType::PatronDaily)
            {
                continue;
            }

            if !quest_template
                .events_subscribe
                .contains(&trigger_event.to_string())
            {
                continue;
            }

            if quest_template.quest_group_type == QuestGroupType::LoopTask
                && !quest_template.progress_if_inactive
                && let Some(active_loop_task_id) =
                    state.character_state.character.active_loop_task_id
                && active_loop_task_id != quest_template.id
            {
                continue;
            }

            let was_completed = active_quest.is_completed(quest_template.progress_target);

            if !active_quest.is_completed(quest_template.progress_target) {
                let progress = match self.get_quest_progress(
                    &state.character_state,
                    active_fight,
                    active_quest,
                    quest_template.progress_behavior.as_deref(),
                    trigger_event,
                    &game_config,
                ) {
                    Ok(progress) => progress,
                    Err(e) => {
                        tracing::error!(
                            "Failed updating quest progress for quest id: {}\n Error: {e:?}",
                            active_quest.id
                        );
                        continue;
                    }
                };
                active_quest.current = progress;
            }

            if !was_completed {
                if (quest_template.quest_group_type == QuestGroupType::PatronLifetime
                    || quest_template.quest_group_type == QuestGroupType::PatronDaily)
                    && active_quest.is_completed(quest_template.progress_target)
                {
                    events.push(EventPluginized::now(OverlordEvent::PatronQuestCompleted {
                        quest_id: active_quest.id,
                    }));
                }

                if (quest_template.quest_group_type != QuestGroupType::Hidden)
                    && active_quest.is_completed(quest_template.progress_target)
                {
                    events.push(EventPluginized::now(OverlordEvent::QuestCompleted {
                        quest_id: active_quest.id,
                    }));
                }

                if quest_template.quest_group_type == QuestGroupType::ProgressPass
                    && active_quest.is_completed(quest_template.progress_target)
                {
                    progress_pass_tier_completed = true;
                }
            }

            if (quest_template.quest_group_type == QuestGroupType::Hidden)
                && active_quest.is_completed(quest_template.progress_target)
            {
                events.push(EventPluginized::now(OverlordEvent::HiddenQuestCompleted {
                    quest_id: active_quest.id,
                }));
            }
        }

        if progress_pass_tier_completed {
            for tier_state in &mut state.progress_pass.tiers {
                let Some(tier_template) = game_config
                    .progress_pass
                    .tiers
                    .iter()
                    .find(|t| t.tier == tier_state.tier)
                else {
                    continue;
                };
                tier_state.is_unlocked = essences::progress_pass::is_progress_pass_tier_unlocked(
                    tier_template,
                    &state.quest_groups.progress_pass,
                    &game_config.quests,
                );
            }
        }
    }

    pub fn get_quest_progress(
        &self,
        character_state: &CharacterState,
        active_fight: &Option<ActiveFight>,
        quest: &QuestInstance,
        progress_script_native: Option<&str>,
        trigger_event: &OverlordEvent,
        game_config: &GameConfig,
    ) -> anyhow::Result<i64> {
        // Native `conditional_progress` port (named by the quest's
        // `progress_script_native` ref). `quest` is the pre-update instance,
        // mirroring the `Quest` const the script saw. Missing / unregistered ref
        // leaves the progress unchanged.
        let Some(name) = progress_script_native else {
            return Ok(quest.current);
        };
        let Some(f) = self.behaviors.conditional_progress_fn(name) else {
            return Ok(quest.current);
        };
        f(
            &crate::behaviors::quests::progress::ConditionalProgressCtx {
                event: trigger_event,
                character_state,
                active_fight,
                quest,
                config: game_config,
                lookups: self.behaviors.lookups(),
            },
        )
    }

    pub fn handle_currency_increase(
        &self,
        currencies: &[CurrencyUnit],
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        let banked = self.drop_pre_gate_pet_currency(currencies, &state);
        increase_currencies(&mut state.character_state.currencies, &banked);
        EventHandleResult::ok(state)
    }

    /// A2-BAL-003 §3.6: Beast Tokens do not bank before the ch35 pet gate.
    ///
    /// Opening a pet case is already server-denied before the gate, but that
    /// only stops the SPEND. Tokens kept accumulating from rating rewards,
    /// quests and Progress Pass tiers, so a player arrived at ch35 with a stock
    /// built up over thirty-four chapters and burned it instantly — which is
    /// exactly the pre-gate bank the card forbids, and it invalidates the pet
    /// acquisition horizons BAL-032 signs.
    ///
    /// Dropping them at the single banking chokepoint covers every source at
    /// once, including ones added later, rather than editing each bundle and
    /// hoping none reappears. The ch35 welcome grant is what seeds the first
    /// tokens instead.
    fn drop_pre_gate_pet_currency(
        &self,
        currencies: &[CurrencyUnit],
        state: &OverlordState,
    ) -> Vec<CurrencyUnit> {
        let game_config = self.game_config.get();
        let chapter = state.character_state.character.current_chapter_level;
        if game_config.pet_slots_for_chapter_level(chapter).is_some() {
            return currencies.to_vec();
        }
        let pet_currency = game_config.game_settings.pet_gacha.currency_id;
        currencies
            .iter()
            .filter(|unit| {
                if unit.currency_id == pet_currency {
                    tracing::debug!(
                        amount = unit.amount,
                        chapter,
                        "dropped pre-gate pet currency"
                    );
                    return false;
                }
                true
            })
            .cloned()
            .collect()
    }

    pub fn handle_currency_decrease(
        &self,
        currencies: &[CurrencyUnit],
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        let non_zero: Vec<_> = currencies
            .iter()
            .filter(|c| c.amount > 0)
            .cloned()
            .collect();
        if let Err(e) = decrease_currencies(&mut state.character_state.currencies, &non_zero) {
            tracing::error!("CurrencyDecrease failed: {e}");
            return EventHandleResult::fail(state);
        }
        EventHandleResult::ok(state)
    }

    /// Creates a `CurrencyIncrease` event. The actual state mutation happens when the
    /// event is processed by the handler — callers don't need to mutate state manually.
    pub fn currency_increase(
        currencies: &[CurrencyUnit],
        currency_source: CurrencySource,
    ) -> EventPluginized<OverlordEvent, OverlordState> {
        EventPluginized::now(OverlordEvent::CurrencyIncrease {
            currencies: currencies.to_owned(),
            currency_source,
        })
    }

    /// Creates a `CurrencyDecrease` event after validating sufficient balance.
    /// Returns `None` if the player doesn't have enough currency.
    /// The actual state mutation happens when the event is processed by the handler.
    pub fn currency_decrease(
        state: &OverlordState,
        currencies: &[CurrencyUnit],
        currency_consumer: CurrencyConsumer,
    ) -> Option<EventPluginized<OverlordEvent, OverlordState>> {
        if !check_can_decrease_currencies(&state.character_state.currencies, currencies) {
            tracing::error!(
                "currency_decrease({currency_consumer:?}): not enough currency, \
                 required={currencies:?}, available={:?}",
                state.character_state.currencies
            );
            return None;
        }
        Some(EventPluginized::now(OverlordEvent::CurrencyDecrease {
            currencies: currencies.to_owned(),
            currency_consumer,
        }))
    }

    fn handle_reset_ad_usage(
        &mut self,
        placements: &[AdPlacement],
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        let now = ::time::utc_now();
        for placement in placements {
            state.character_state.ad_usage.insert(
                *placement,
                AdUsageData {
                    daily_count: 0,
                    last_reset_at: now,
                },
            );
        }

        EventHandleResult::ok(state)
    }

    fn handle_reset_instant_reward_gems_press_count(
        &mut self,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        state
            .character_state
            .character
            .instant_reward_gems_press_count = 0;
        EventHandleResult::ok(state)
    }

    pub fn handle_show_bird(
        &mut self,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        let bird_config = &self.game_config.get().ads_settings.bird_ad;
        let cooldown_until = ::time::utc_now()
            + chrono::TimeDelta::seconds(bird_config.post_show_cooldown_sec as i64);
        state.character_state.character.bird_cooldown_until = Some(cooldown_until);
        EventHandleResult::ok(state)
    }

    pub fn handle_bird_shown(
        &mut self,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        let bird_config = &self.game_config.get().ads_settings.bird_ad;
        let cooldown_until =
            ::time::utc_now() + chrono::TimeDelta::seconds(bird_config.cooldown_sec as i64);
        state.character_state.character.bird_cooldown_until = Some(cooldown_until);
        EventHandleResult::ok(state)
    }

    pub fn handle_rate_us_shown(
        &mut self,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        state.character_state.character.rate_us_shown = true;
        EventHandleResult::ok(state)
    }
}