overlord_event_system/logic/

pet_facets.rs

//! Pet Facets / Team Die v0 — the combat runtime.
//!
//! # The resolution boundary
//!
//! ```text
//! Global Flip begins
//! → the incoming side is determined
//! → the Team Die picks one of THAT side's three facets
//! → the outcome applies one instant payoff or one short window
//! → the remaining incoming Flip payoffs execute
//! ```
//!
//! That order is the whole reason [`OverlordLogic::handle_global_flip`] exists:
//! the die is rolled and its outcome applied BEFORE
//! [`OverlordLogic::apply_flip_to_laws`] delivers the bridge charge and fires
//! the phase-start laws, and long before the artifact Flip Aspects run out of
//! `apply_success_hooks`. The same function is the single dispatch arm for
//! `GlobalFlip` in both paths — the pure dispatch and the monolith's merged arm
//! — so neither can drift into rolling a different number of times.
//!
//! # Provenance
//!
//! A facet outcome is **Derived**: everything it lands as a combat outcome is
//! emitted [`CombatEventOrigin::Proc`], so it can never ignite a Trigger Stone
//! and never re-enter a law condition. It creates no Resonance, no Mastery, no
//! Bridge charge and no Gauge — the two Clock Crow facets
//! ([`PetFacet::AdvanceNotice`], [`PetFacet::RisingGate`]) are the design doc's
//! one stated exception, and they are the Flip-Gauge pair whose entire content
//! is handing out Gauge. Where a facet touches Resonance
//! ([`PetFacet::LeadReading`]) or the Gauge of an existing proc
//! ([`PetFacet::RisingGate`]) it MODIFIES the flow that was already going to
//! run; it never opens a second one.
//!
//! A facet-generated repeat cannot repeat itself: [`mech::APPLYING`] is raised
//! for the whole of an outcome, and [`OverlordLogic::apply_pet_facets`] — the
//! hook that spends armed facet state — leaves immediately while it is up.
//!
//! # State
//!
//! Per-fight facet state lives in the player entity's `attributes` under
//! `pet.*` ([`crate::mechanics::pet_facets`]), so it resets with the fight by
//! construction. The three "one chosen Law" facets read a DURABLE selection
//! ([`essences::pet_facets::PetFacetLawChoices`], set out of combat) and keep
//! only the charge in the entity.

use essences::combat_origin::CombatEventOrigin;
use essences::cores::LawTemplateId;
use essences::entity::EntityId;
use essences::fight_breakdown::CombatSource;
use essences::flip::WorldSide;
use essences::pet_facets::{PetFacet, PetFacetLawRole};

use crate::logic::combat_facts::{self, CombatFact};
use crate::mechanics::{balance, fight::get_entity_stat, pet_facets as mech, stones as stone_mech};
use crate::{
    EventHandleResult,
    event::OverlordEvent,
    logic::{EventPluginized, handler::OverlordLogic},
    state::OverlordState,
};

/// Everything a facet outcome may need, read once before any mutation.
struct FacetCtx {
    player_id: EntityId,
    player_attack: f64,
    player_max_hp: u64,
    player_speed: i64,
    target_id: Option<EntityId>,
    /// The player's original Skills that are on cooldown right now — `Head
    /// Start`'s surface. Class Basic Attacks are excluded: the facet says
    /// "Skill cooldowns", and the auto-attack metronome is not one.
    skill_ability_ids: Vec<essences::abilities::AbilityId>,
    now: u64,
}

impl OverlordLogic {
    // ---- Entry points -------------------------------------------------------

    /// Dispatch arm for `GlobalFlip`, in BOTH paths.
    ///
    /// Order is the acceptance criterion, not a preference: roll and resolve the
    /// Team Die of the incoming side, then hand the flip to the law layer, which
    /// delivers bridge charge and fires the phase-start laws.
    pub fn handle_global_flip(
        &mut self,
        entity_id: EntityId,
        from_side: WorldSide,
        to_side: WorldSide,
        revision: u64,
        rng: &mut rand::rngs::StdRng,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        let mut events = self.roll_team_die(&mut state, entity_id, to_side, Some(revision), rng);
        events.extend(self.apply_flip_to_laws(&mut state, entity_id, from_side, to_side));
        EventHandleResult::ok_events(state, events)
    }

    /// The entry roll: stepping into the starting world of a fight is the same
    /// moment as arriving on a side through a flip, so it rolls the same die.
    ///
    /// `revision` is `None` here — a fight start is not a flip and carries no
    /// revision, and the per-flip latch it feeds exists to stop ONE flip rolling
    /// twice, which a fight start cannot do (the fight has exactly one).
    pub fn roll_team_die_on_fight_start(
        &mut self,
        state: &mut OverlordState,
        rng: &mut rand::rngs::StdRng,
    ) -> Vec<EventPluginized<OverlordEvent, OverlordState>> {
        let Some(fight) = state.active_fight.as_ref() else {
            return Vec::new();
        };
        // Every character combatant enters their own world and rolls their own
        // die: the local hero, the party ally, and a human PvP opponent.
        let mut combatants = vec![fight.player_id];
        combatants.extend(fight.party_player_id);
        if let Some(pvp) = &state.pvp_state {
            let opponent_id = pvp.opponent_state.id();
            if fight.entities.iter().any(|e| e.id == opponent_id) {
                combatants.push(opponent_id);
            }
        }
        let mut events = Vec::new();
        for combatant_id in combatants {
            let Some(side) = state
                .active_fight
                .as_ref()
                .and_then(|fight| fight.entities.iter().find(|e| e.id == combatant_id))
                .and_then(|entity| entity.flip_state)
                .map(|flip| flip.active_side)
            else {
                // No flip state means the flip is still locked for this
                // combatant: there is no "world" to enter yet, so there is no
                // die to roll.
                continue;
            };
            events.extend(self.roll_team_die(state, combatant_id, side, None, rng));
        }
        events
    }

    /// Rolls the die for `side` and applies the single facet it lands on.
    ///
    /// Uniform `1/3` over the incoming side's three faces (one per equipped
    /// pet), drawn from the fight's own `StdRng` — so the roll is
    /// server-authoritative and reproducible for a seed. No manual roll, no
    /// hold, no reroll, no weights.
    fn roll_team_die(
        &mut self,
        state: &mut OverlordState,
        entity_id: EntityId,
        side: WorldSide,
        revision: Option<u64>,
        rng: &mut rand::rngs::StdRng,
    ) -> Vec<EventPluginized<OverlordEvent, OverlordState>> {
        let mut events = Vec::new();
        let Some(fight) = state.active_fight.as_ref() else {
            return events;
        };
        if fight.fight_ended || fight.fight_stopped {
            return events;
        }
        // The flipping combatant rolls their OWN pets — resolvable for the
        // hero, the party ally, and a human PvP opponent. A mob's flip (no
        // CharacterState) rolls nothing.
        let Some(build) = crate::entities::combatant_character_state(
            &state.character_state,
            &state.party,
            &state.pvp_state,
            fight,
            entity_id,
        ) else {
            return events;
        };
        let equipped_pets = build.equipped_pets.clone();

        // One roll per flip, however many times `GlobalFlip` reaches this arm.
        // `revision + 1` so an untouched attribute reads as "not rolled yet"
        // even at revision 0.
        if let Some(revision) = revision {
            let this_flip = revision as i64 + 1;
            let Some(player) = state
                .active_fight
                .as_mut()
                .and_then(|fight| fight.entities.iter_mut().find(|e| e.id == entity_id))
            else {
                return events;
            };
            if mech::attr(player, mech::ROLL_REVISION) == this_flip {
                return events;
            }
            player.attributes.set(mech::ROLL_REVISION, this_flip);
            // A phase's own facet state dies with the phase, before the
            // incoming phase's facet arms anything.
            mech::clear_phase_state(player);
        }

        let game_config = self.game_config.get();
        let faces = mech::eligible_facets(&game_config, &equipped_pets, side);
        let Some(rolled) = mech::roll_team_die(rng, &faces) else {
            return events;
        };

        let Some(ctx) = self.read_fight(state, entity_id) else {
            return events;
        };
        {
            let Some(player) = state
                .active_fight
                .as_mut()
                .and_then(|fight| fight.entities.iter_mut().find(|e| e.id == entity_id))
            else {
                return events;
            };
            player
                .attributes
                .set(mech::LAST_ROLL, facet_marker(rolled.facet));
            // The recursion guard is raised BEFORE the outcome runs and lowered
            // after, so anything the outcome dispatches that comes back through
            // `apply_pet_facets` finds the door shut.
            player.attributes.set(mech::APPLYING, 1);
        }

        self.apply_facet(state, &mut events, &ctx, rolled.facet, rolled.pet_level);

        if let Some(player) = state
            .active_fight
            .as_mut()
            .and_then(|fight| fight.entities.iter_mut().find(|e| e.id == entity_id))
        {
            player.attributes.set(mech::APPLYING, 0);
        }
        events
    }

    /// Reads everything a facet outcome needs, once, before any mutation.
    fn read_fight(&self, state: &OverlordState, player_id: EntityId) -> Option<FacetCtx> {
        let game_config = self.game_config.get();
        let fight = state.active_fight.as_ref()?;
        let player = fight.entities.iter().find(|e| e.id == player_id)?;
        let skill_ability_ids = player
            .actions_queue
            .start_cast_entries()
            .into_iter()
            .map(|(ability_id, _)| ability_id)
            .filter(|ability_id| {
                combat_facts::cast_kind(&game_config, player, *ability_id)
                    != combat_facts::CastKind::Basic
            })
            .collect();
        Some(FacetCtx {
            player_id,
            player_attack: get_entity_stat(self.behaviors.lookups(), player, "attack"),
            player_max_hp: player.max_hp,
            player_speed: player
                .attributes
                .speed_or_baseline(game_config.game_settings.baseline_speed),
            target_id: crate::logic::stones::nearest_enemy(&fight.entities, player),
            skill_ability_ids,
            now: self.fight_clock.now(),
        })
    }

    // ---- The twenty outcomes ------------------------------------------------

    /// Applies exactly one facet: one instant payoff or one short window.
    fn apply_facet(
        &mut self,
        state: &mut OverlordState,
        events: &mut Vec<EventPluginized<OverlordEvent, OverlordState>>,
        ctx: &FacetCtx,
        facet: PetFacet,
        pet_level: i64,
    ) {
        let game_config = self.game_config.get();
        let settings = &game_config.pet_facet_settings;
        let player_id = ctx.player_id;
        let permyriad = |percent: f64| mech::permyriad(settings, percent, pet_level);
        // A permyriad share of Attack, through the same damage constant every
        // other derived hit in the game uses.
        let derived = |share_permyriad: i64| {
            (ctx.player_attack * (share_permyriad as f64 / 10_000.0) * balance::DMG_K)
                .floor()
                .max(0.0) as u64
        };

        match facet {
            // ---- PET-01 Zip ----
            PetFacet::HeadStart => {
                let by_ticks = mech::ticks(settings, settings.head_start_ticks, pet_level);
                let ability_ids = ctx.skill_ability_ids.clone();
                let now = ctx.now;
                Self::with_player(state, player_id, |player| {
                    player
                        .actions_queue
                        .shorten_cooldowns_of(now, &ability_ids, by_ticks);
                });
            }
            PetFacet::SecondSpark => Self::arm_pet_facet(
                state,
                player_id,
                &[
                    (
                        mech::NEXT_SKILL_ECHO,
                        permyriad(settings.second_spark_percent),
                    ),
                    (mech::NEXT_SKILL_ECHO_CHARGES, 1),
                ],
            ),

            // ---- PET-02 Ledger Mimic ----
            PetFacet::BudgetPlan => {
                // A DISCOUNT is a smaller multiplier, so rank must not scale it
                // the way it scales a bonus: `rank_multiplier` is applied to the
                // discount depth (1 - multiplier), which is the number the
                // facet is actually about.
                let depth = (1.0 - settings.budget_plan_cost_multiplier).max(0.0)
                    * settings.rank_multiplier(pet_level);
                let multiplier = ((1.0 - depth).max(0.0) * 10_000.0).round() as i64;
                Self::arm_pet_facet(
                    state,
                    player_id,
                    &[
                        (mech::BUDGET_MULT, multiplier),
                        (mech::BUDGET_CASTS, settings.budget_plan_casts.max(1)),
                    ],
                )
            }
            PetFacet::OpenTab => Self::arm_pet_facet(
                state,
                player_id,
                &[
                    (
                        mech::OPEN_TAB_SURCHARGE,
                        permyriad(settings.open_tab_surcharge_percent),
                    ),
                    (
                        mech::OPEN_TAB_PAYLOAD_SHARE,
                        permyriad(settings.open_tab_payload_share_percent),
                    ),
                    (mech::OPEN_TAB_CHARGES, 1),
                ],
            ),

            // ---- PET-03 Springpaw ----
            PetFacet::Overtime => {
                let delta = (ctx.player_speed as f64
                    * (permyriad(settings.overtime_attack_speed_percent) as f64 / 10_000.0))
                    .round() as i64;
                self.apply_timed_attribute(
                    events,
                    player_id,
                    "speed",
                    delta,
                    settings.overtime_duration_ticks,
                );
            }
            PetFacet::MagicVolley => {
                let damage = derived(permyriad(settings.magic_volley_percent));
                for _ in 0..settings.magic_volley_bolts.max(0) {
                    let Some(target_id) = ctx.target_id else {
                        break;
                    };
                    push_derived_damage(
                        events,
                        player_id,
                        target_id,
                        damage,
                        PetFacet::MagicVolley,
                    );
                }
            }

            // ---- PET-04 Bulwark Slime ----
            PetFacet::SafetyNet => {
                // The stone runtime's own reduction key: one place reads
                // "incoming damage is reduced" (`mechanics::fight::damage`), and
                // a second key would silently not compose with the first.
                self.apply_timed_attribute(
                    events,
                    player_id,
                    stone_mech::INCOMING_REDUCTION,
                    permyriad(settings.safety_net_reduction_percent).clamp(0, 10_000),
                    settings.safety_net_duration_ticks,
                );
            }
            PetFacet::Retaliation => Self::arm_pet_facet(
                state,
                player_id,
                &[
                    (mech::RETALIATION, permyriad(settings.retaliation_percent)),
                    (mech::RETALIATION_CHARGES, 1),
                ],
            ),

            // ---- PET-05 Lucky Bat ----
            PetFacet::Calibration => {
                // Again the stone key, for the same reason: the crit roll in
                // `mechanics::fight::attack` reads exactly one armed bonus.
                Self::arm_pet_facet(
                    state,
                    player_id,
                    &[
                        (
                            stone_mech::NEXT_ATTACK_CRIT,
                            permyriad(settings.calibration_crit_percent),
                        ),
                        (
                            stone_mech::NEXT_ATTACK_CRIT_CHARGES,
                            settings.calibration_attacks.max(1),
                        ),
                    ],
                )
            }
            PetFacet::LuckyStar => Self::arm_pet_facet(
                state,
                player_id,
                &[
                    (mech::LUCKY_STAR, permyriad(settings.lucky_star_percent)),
                    (mech::LUCKY_STAR_CHARGES, 1),
                ],
            ),

            // ---- PET-06 Owl Auditor ----
            PetFacet::LeadReading => Self::arm_pet_facet(
                state,
                player_id,
                &[
                    (
                        mech::LEAD_READING_BONUS,
                        permyriad(settings.lead_reading_resonance_percent),
                    ),
                    (
                        mech::LEAD_READING_CHARGES,
                        settings.lead_reading_activations.max(1),
                    ),
                ],
            ),
            PetFacet::WildReading => {
                let until = ctx.now as i64 + settings.wild_reading_duration_ticks as i64 + 1;
                Self::arm_pet_facet(
                    state,
                    player_id,
                    &[
                        (
                            mech::WILD_READING_BONUS,
                            permyriad(settings.wild_reading_effect_percent),
                        ),
                        (mech::WILD_READING_UNTIL, until),
                    ],
                )
            }

            // ---- PET-08 Clock Crow ----
            PetFacet::AdvanceNotice => {
                let share = (permyriad(settings.advance_notice_gauge_percent) as f64 / 10_000.0)
                    .clamp(0.0, 0.99);
                let threshold =
                    crate::entities::combatant_flip_threshold(state, player_id, &game_config);
                let opening = threshold * share;
                let mut snapshot = None;
                if let Some(player) = state
                    .active_fight
                    .as_mut()
                    .and_then(|fight| fight.entities.iter_mut().find(|e| e.id == player_id))
                    && let Some(flip) = player.flip_state.as_mut()
                {
                    // The doc's one stated exception to "a facet creates no
                    // Gauge". Set rather than added: the phase has just started,
                    // the accumulator is at zero, and "starts with 12%" is a
                    // floor on the opening reading, not a gain on top of one.
                    flip.progress = flip.progress.max(opening);
                    snapshot = Some(*flip);
                }
                if let Some(snapshot) = snapshot {
                    crate::entities::mirror_combatant_flip_state(state, player_id, snapshot);
                }
            }
            PetFacet::RisingGate => Self::arm_pet_facet(
                state,
                player_id,
                &[
                    (
                        mech::RISING_GATE_MULT,
                        // BAL-014: a multiplier on the proc's own Gauge award,
                        // interpolated over pet levels instead of rank growth.
                        (configs::pet_facets::PetFacetSettings::level_interpolated(
                            settings.rising_gate_multiplier_l1,
                            settings.rising_gate_multiplier_l10,
                            pet_level,
                        ) * 100.0)
                            .round() as i64,
                    ),
                    (mech::RISING_GATE_PROCS, settings.rising_gate_procs.max(1)),
                ],
            ),

            // ---- PET-09 Toolbox Goblin ----
            PetFacet::PreparedSlots => Self::arm_pet_facet(
                state,
                player_id,
                &[(
                    mech::PREPARED_SLOTS,
                    permyriad(settings.prepared_slots_percent),
                )],
            ),
            PetFacet::FirstSpell => Self::arm_pet_facet(
                state,
                player_id,
                &[
                    (mech::FIRST_SPELL, permyriad(settings.first_spell_percent)),
                    (mech::FIRST_SPELL_CHARGES, 1),
                ],
            ),

            // ---- PET-10 Mirror Moth ----
            PetFacet::Souvenir => Self::arm_pet_facet(
                state,
                player_id,
                &[
                    (mech::SOUVENIR_SHARE, permyriad(settings.souvenir_percent)),
                    (mech::SOUVENIR_CHARGES, settings.souvenir_procs.max(1)),
                ],
            ),
            PetFacet::DreamReader => Self::arm_pet_facet(
                state,
                player_id,
                &[
                    (mech::DREAM_READER, permyriad(settings.dream_reader_percent)),
                    (mech::DREAM_READER_CHARGES, 1),
                ],
            ),

            // ---- PET-11 Lunchbox Boar ----
            PetFacet::PackedLunch => {
                let heal = (ctx.player_max_hp as f64
                    * (permyriad(settings.packed_lunch_heal_percent) as f64 / 10_000.0))
                    .round() as u64;
                if heal > 0 {
                    // Overheal is discarded by `handle_heal`, which clamps to
                    // `max_hp` — the facet needs no rule of its own for it.
                    events.push(EventPluginized::now(OverlordEvent::Heal {
                        by_entity_id: Some(player_id),
                        entity_id: player_id,
                        heal,
                        origin: CombatEventOrigin::Proc,
                        source: CombatSource::PetFacetProc {
                            facet: PetFacet::PackedLunch,
                        },
                    }));
                }
            }
            PetFacet::LifeBloom => {
                // BAL-014: L1/L10 endpoints interpolated over pet levels. The
                // interpolation IS the level scaling — running the result
                // through the generic rank multiplier again would double-scale
                // it (10% at L10 would become 14.5%), so convert directly, the
                // same way Rising Gate does.
                let percent = configs::pet_facets::PetFacetSettings::level_interpolated(
                    settings.life_bloom_percent_l1,
                    settings.life_bloom_percent_l10,
                    pet_level,
                );
                self.apply_timed_attribute(
                    events,
                    player_id,
                    mech::LIFE_BLOOM,
                    (percent * 100.0).round() as i64,
                    settings.life_bloom_duration_ticks,
                );
            }
        }
    }

    /// Writes facet state straight onto the player entity. A magnitude is a
    /// VALUE: re-arming overwrites it rather than stacking it into nonsense.
    fn arm_pet_facet(state: &mut OverlordState, player_id: EntityId, pairs: &[(&str, i64)]) {
        Self::with_player(state, player_id, |player| {
            for (key, value) in pairs {
                player.attributes.set(key, *value);
            }
        });
    }

    // ---- Spending armed facet state ----------------------------------------

    /// Success hook: spends the facet state this Core event consumes.
    ///
    /// The pet half of what [`crate::logic::stones::spend_effect_state`] does
    /// for stones, kept in its own hook because a facet must work for a player
    /// with nothing socketed — the stones hook leaves through an early return
    /// for exactly that player.
    ///
    /// Everything it emits is `Proc`. It leaves immediately while
    /// [`mech::APPLYING`] is raised, which is the guard against a
    /// facet-generated repeat repeating itself.
    pub fn apply_pet_facets(
        &mut self,
        state: &mut OverlordState,
        events: &mut Vec<EventPluginized<OverlordEvent, OverlordState>>,
        event: &OverlordEvent,
    ) {
        let Some(fight) = state.active_fight.as_ref() else {
            return;
        };
        if fight.fight_ended || fight.fight_stopped {
            return;
        }
        // Every character combatant spends their OWN armed facet state: the
        // armed keys live on the entity, so the pass is per combatant.
        let mut combatants = vec![fight.player_id];
        combatants.extend(fight.party_player_id);
        if let Some(pvp) = &state.pvp_state {
            let opponent_id = pvp.opponent_state.id();
            if fight.entities.iter().any(|e| e.id == opponent_id) {
                combatants.push(opponent_id);
            }
        }
        for combatant_id in combatants {
            self.apply_pet_facets_for(state, events, event, combatant_id);
        }
    }

    /// One combatant's pass of [`Self::apply_pet_facets`].
    fn apply_pet_facets_for(
        &mut self,
        state: &mut OverlordState,
        events: &mut Vec<EventPluginized<OverlordEvent, OverlordState>>,
        event: &OverlordEvent,
        combatant_id: EntityId,
    ) {
        let Some(fight) = state.active_fight.as_ref() else {
            return;
        };
        let player_id = combatant_id;
        let Some(player) = fight.entities.iter().find(|e| e.id == player_id) else {
            return;
        };
        if mech::attr(player, mech::APPLYING) != 0 {
            return;
        }
        // Cheap gate: this hook runs on every successfully handled event of the
        // session, and a player with no armed facet state has nothing to spend.
        if !ARMED_KEYS.iter().any(|key| mech::attr(player, key) != 0) {
            return;
        }

        let game_config = self.game_config.get();
        let facts: Vec<CombatFact> = {
            let classified = combat_facts::classify(&game_config, fight, event);
            combat_facts::facts_for(&classified, player_id).collect()
        };
        if facts.is_empty() {
            return;
        }

        let player_attack = get_entity_stat(self.behaviors.lookups(), player, "attack");
        let enemy_ids = crate::logic::stones::living_enemies(&fight.entities, player);
        let is_skill =
            combat_facts::current_cast_kind(player) == Some(combat_facts::CastKind::Skill);

        let derived = |share_permyriad: i64| {
            (player_attack * (share_permyriad as f64 / 10_000.0) * balance::DMG_K)
                .floor()
                .max(0.0) as u64
        };

        let Some(player) = state
            .active_fight
            .as_mut()
            .and_then(|fight| fight.entities.iter_mut().find(|e| e.id == player_id))
        else {
            return;
        };

        let mut produced: Vec<(EntityId, u64, PetFacet)> = Vec::new();
        let mut healed = 0_u64;
        for fact in facts {
            match fact {
                // `PET-04 Retaliation`: the next Core hit ON THE HERO answers
                // with a derived area burst.
                CombatFact::HitTaken { .. } => {
                    if let Some(share) =
                        mech::armed(player, mech::RETALIATION, mech::RETALIATION_CHARGES)
                    {
                        let damage = derived(share);
                        for target in &enemy_ids {
                            produced.push((*target, damage, PetFacet::Retaliation));
                        }
                        mech::spend_charge(player, mech::RETALIATION, mech::RETALIATION_CHARGES);
                    }
                }
                CombatFact::HitLanded {
                    crit,
                    victim,
                    damage,
                } => {
                    // `PET-11 Life Bloom`: a share of the Core damage this hit
                    // dealt, healed back. Read literally off the damage, which
                    // is what the facet says, rather than off Attack.
                    let bloom = mech::attr(player, mech::LIFE_BLOOM);
                    if bloom > 0 {
                        let heal = (damage as f64 * bloom as f64 / 10_000.0).round() as u64;
                        if heal > 0 {
                            healed += heal;
                        }
                    }
                    // `PET-05 Lucky Star`: one jackpot crit, on the enemy that
                    // took it.
                    if crit
                        && let Some(share) =
                            mech::armed(player, mech::LUCKY_STAR, mech::LUCKY_STAR_CHARGES)
                    {
                        produced.push((victim, derived(share), PetFacet::LuckyStar));
                        mech::spend_charge(player, mech::LUCKY_STAR, mech::LUCKY_STAR_CHARGES);
                    }
                    if is_skill {
                        // `PET-01 Second Spark`: one derived repeat of the next
                        // original Skill.
                        //
                        // A share of what that Skill JUST LANDED, not of Attack.
                        // The facet's wording is the same shape as `First
                        // Spell`'s ("executes a second time at 100%") — it
                        // repeats the thing, so it is worth what the thing was
                        // worth. The facets that are priced off Attack say so
                        // (`Magic Volley` 35% Attack, `Lucky Star` 180% Attack,
                        // `Retaliation` 220% Attack); this one does not.
                        if let Some(share) = mech::armed(
                            player,
                            mech::NEXT_SKILL_ECHO,
                            mech::NEXT_SKILL_ECHO_CHARGES,
                        ) {
                            let repeat =
                                (damage as f64 * share as f64 / 10_000.0).floor().max(0.0) as u64;
                            produced.push((victim, repeat, PetFacet::SecondSpark));
                            mech::spend_charge(
                                player,
                                mech::NEXT_SKILL_ECHO,
                                mech::NEXT_SKILL_ECHO_CHARGES,
                            );
                        }
                        // `PET-02 Open Tab`: the surcharge it paid at cast time,
                        // as extra payload on the hit that cast produced.
                        if let Some(bonus) = mech::armed(
                            player,
                            mech::NEXT_SKILL_BONUS,
                            mech::NEXT_SKILL_BONUS_CHARGES,
                        ) {
                            produced.push((victim, derived(bonus), PetFacet::OpenTab));
                            mech::spend_charge(
                                player,
                                mech::NEXT_SKILL_BONUS,
                                mech::NEXT_SKILL_BONUS_CHARGES,
                            );
                        }
                    }
                }
                _ => {}
            }
        }

        for (target, damage, facet) in produced {
            push_derived_damage(events, player_id, target, damage, facet);
        }
        if healed > 0 {
            events.push(EventPluginized::now(OverlordEvent::Heal {
                by_entity_id: Some(player_id),
                entity_id: player_id,
                heal: healed,
                origin: CombatEventOrigin::Proc,
                source: CombatSource::PetFacetProc {
                    facet: PetFacet::LifeBloom,
                },
            }));
        }
    }

    // ---- The three chosen-Law facets ---------------------------------------

    /// The Law a chosen-Law facet acts on: the player's own selection when it is
    /// still eligible, otherwise the deterministic fallback.
    ///
    /// Eligibility is `role`-specific because the three draw from three
    /// different populations, and the fallback is "the lowest slot index of the
    /// eligible side" — deterministic, non-panicking, and never a random pick:
    /// a player who has never opened the picker gets a stable answer rather than
    /// a facet that silently does nothing.
    pub(crate) fn pet_facet_law(
        &self,
        state: &OverlordState,
        owner_id: EntityId,
        role: PetFacetLawRole,
    ) -> Option<LawTemplateId> {
        let game_config = self.game_config.get();
        let owner = state
            .active_fight
            .as_ref()?
            .entities
            .iter()
            .find(|e| e.id == owner_id)?;
        let active_side = owner.flip_state?.active_side;
        let wanted_side = match role {
            // `Lead Reading` names a SOURCE law: it banks Resonance when the law
            // fires, and a law only fires while its own side is up.
            PetFacetLawRole::LeadReading | PetFacetLawRole::WildReading => Some(active_side),
            PetFacetLawRole::DreamReader => Some(active_side.flipped()),
        };

        let eligible = |law_id: LawTemplateId| -> Option<i64> {
            let owned = owner.law_cores.law(law_id)?;
            let slot_index = owned.slot_index?;
            let template = crate::mechanics::cores::law_template(&game_config, law_id)?;
            if !template.is_active {
                return None;
            }
            if wanted_side.is_some_and(|side| template.side != side) {
                return None;
            }
            Some(slot_index)
        };

        // The OWNER's own selection: `law_cores` is the entity-local cores
        // snapshot, so a party ally's or a PvP opponent's choice resolves from
        // their build, never from the session character's.
        let chosen = owner.law_cores.pet_facet_law_choices.get(role);
        if let Some(chosen) = chosen
            && eligible(chosen).is_some()
        {
            return Some(chosen);
        }
        // Fallback: lowest slot index on the eligible side, ties broken by law
        // id so two laws in the same slot can never make the answer depend on
        // vector order.
        owner
            .law_cores
            .slotted_laws()
            .filter_map(|owned| eligible(owned.template_id).map(|slot| (slot, owned.template_id)))
            .min_by_key(|(slot, law_id)| (*slot, *law_id))
            .map(|(_, law_id)| law_id)
    }

    /// Sets (or clears) one of the three out-of-combat Law selections.
    ///
    /// Refuses a law the character does not own — the selection is a pointer
    /// into the player's own collection, and a dangling one would make the
    /// fallback unreachable without ever telling anyone.
    pub fn handle_set_pet_facet_law(
        &self,
        role: PetFacetLawRole,
        law_template_id: Option<LawTemplateId>,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        if let Some(law_template_id) = law_template_id {
            if self
                .game_config
                .get()
                .laws
                .iter()
                .all(|law| law.id != law_template_id)
            {
                tracing::error!("SetPetFacetLaw refused: unknown law {law_template_id}");
                return EventHandleResult::fail(state);
            }
            if state.character_state.cores.law(law_template_id).is_none() {
                tracing::error!("SetPetFacetLaw refused: law {law_template_id} is not owned");
                return EventHandleResult::fail(state);
            }
        }
        state
            .character_state
            .cores
            .pet_facet_law_choices
            .set(role, law_template_id);
        EventHandleResult::ok(state)
    }
}

/// Every key whose presence means "this player has facet state to spend". Read
/// as the cheap gate of [`OverlordLogic::apply_pet_facets`].
const ARMED_KEYS: [&str; 5] = [
    mech::RETALIATION_CHARGES,
    mech::LUCKY_STAR_CHARGES,
    mech::NEXT_SKILL_ECHO_CHARGES,
    mech::NEXT_SKILL_BONUS_CHARGES,
    mech::LIFE_BLOOM,
];

/// `PetFacet` as a stable non-zero marker, so an untouched attribute (`0`) reads
/// as "the die has not been rolled".
fn facet_marker(facet: PetFacet) -> i64 {
    use strum::IntoEnumIterator;
    PetFacet::iter()
        .position(|candidate| candidate == facet)
        .map_or(0, |index| index as i64 + 1)
}

/// The facet a marker written by [`facet_marker`] names.
pub fn facet_from_marker(marker: i64) -> Option<PetFacet> {
    use strum::IntoEnumIterator;
    if marker <= 0 {
        return None;
    }
    PetFacet::iter().nth(marker as usize - 1)
}

/// One derived hit: `Proc`, so it feeds no trigger and starts no cascade.
fn push_derived_damage(
    events: &mut Vec<EventPluginized<OverlordEvent, OverlordState>>,
    player_id: EntityId,
    target_id: EntityId,
    damage: u64,
    facet: PetFacet,
) {
    if damage == 0 {
        return;
    }
    events.push(EventPluginized::now(OverlordEvent::Damage {
        by_entity_id: Some(player_id),
        entity_id: target_id,
        damage,
        damage_data: Default::default(),
        origin: CombatEventOrigin::Proc,
        source: CombatSource::PetFacetProc { facet },
    }));
}