overlord_event_system/logic/

artifacts.rs

//! Artifacts — collection handlers, acquisition, and the two Aspect rules that
//! do not ride on a trigger fire.
//!
//! Three of the six Aspect rules hang off a trigger and live in
//! [`crate::logic::stones`] («Нарастание», «Первый удар», «Фоновый голос»); the
//! remaining three hang off the fight's own moments and live here: «Теневой
//! круг» on the heartbeat, «Входящий залп» and «Поочерёдный вход» on the flip.
//!
//! # Provenance
//!
//! Every effect fired from this module goes through
//! [`crate::logic::stones::OverlordLogic::run_stone_effect`], whose combat
//! output is built `CombatEventOrigin::Proc` and whose bookkeeping output
//! (`EntityIncrAttribute`) carries no provenance at all and is not trigger
//! surface. Nothing here builds a combat event itself. That is what keeps the
//! artifact from closing the loop the Core/Proc boundary exists to prevent: an
//! artifact rebroadcasts effects, and a rebroadcast effect can never fire the
//! trigger that would rebroadcast it again.
//!
//! The **second** loop guard is that an artifact-driven fire never feeds the
//! flip gauge: `run_stone_effect`'s gauge return value is deliberately dropped
//! at every call site in this module. Without it, «Входящий залп» could fill the
//! gauge, flip, and volley again — the one cascade that is not covered by the
//! Core/Proc boundary, because a flip is a state transition rather than a combat
//! event and carries no provenance to inherit.
//!
//! The **third** guard is `artifact.flip.rev`: one flip runs at most one volley
//! even if `GlobalFlip` reaches the hook more than once.

use essences::artifacts::{
    ArtifactCollection, ArtifactSocketColumn, ArtifactSocketSlot, ArtifactStoneTemplateId,
    ArtifactTemplateId,
};
use essences::entity::EntityId;
use essences::fight_breakdown::CombatSource;
use essences::flip::WorldSide;
use essences::items::ItemType;
use essences::stones::{StoneSocketKey, StoneSocketSlot, StoneTier};

use configs::artifacts::ArtifactStoneRule;
use configs::game_config::GameConfig;
use strum::{EnumCount, IntoEnumIterator};

use crate::game_config_helpers::GameConfigLookup;
use crate::mechanics::{artifacts as mech, fight::get_entity_stat};
use crate::{
    EventHandleResult,
    event::OverlordEvent,
    logic::{EventPluginized, handler::OverlordLogic, stones::StoneEffectCtx},
    state::OverlordState,
};

/// Scale a rule's share is carried at on the wire. The event enum derives `Eq`,
/// which rules out an `f64` field, so a deferred fire ships its share as
/// ten-thousandths.
const SHARE_PERMYRIAD: i64 = 10_000;

/// One effect an artifact rule wants run: which stone, at what level, at what
/// share of its strength, and how far in the future. Grouped rather than passed
/// loose because the four are one decision — "run THIS effect, THEN".
#[derive(Clone, Copy)]
struct ArtifactFire {
    effect_template_id: uuid::Uuid,
    effect_level: i64,
    share: f64,
    /// Aspect stone whose rule ordered this fire — the breakdown row the
    /// rebroadcast effect's damage and healing land in.
    artifact_stone_id: ArtifactStoneTemplateId,
    /// `0` everywhere except `FA-05 Staggered Entrance`, the only rule that
    /// spaces its fires out. A non-zero delay defers the whole run through
    /// [`OverlordEvent::FireArtifactEffect`].
    delay_ticks: u64,
}

/// One socketed Aspect stone, flattened to the three numbers a rule needs.
///
/// Flattened deliberately: the callers read this *before* mutating the character
/// state, and an owned copy keeps the config borrow from outliving that read.
#[derive(Clone, Copy, Debug, PartialEq)]
pub(crate) struct AspectRuleInstance {
    pub(crate) rule: ArtifactStoneRule,
    /// Catalog id of the socketed Aspect stone this reading came from.
    pub(crate) stone_id: ArtifactStoneTemplateId,
    /// The rule's magnitude at the stone's current upgrade level, in percent.
    pub(crate) magnitude: f64,
    /// The rule's second percentage (a floor, a cap, a share of the gauge).
    /// Never scaled by level, for the same reason as `rule_param`.
    pub(crate) secondary_magnitude: f64,
    /// The rule's own parameter (a period in ticks, or a count). Never scaled by
    /// level — an upgrade changes how strong the rule is, never what it does.
    pub(crate) rule_param: i64,
    /// `VA-05 Small Gears` only: the per-tier share, resolved for every tier at
    /// read time. Flattened to an array rather than carried as the catalog's
    /// `Vec` so this struct stays `Copy` like the rest of the flattened reading;
    /// `100.0` everywhere for the fourteen rules that do not use it, which is
    /// also what a missing catalog rung means.
    pub(crate) tier_magnitudes: [f64; StoneTier::COUNT],
}

impl AspectRuleInstance {
    /// The share this rule gives an effect lit by a trigger of `tier`, as a
    /// multiplier. `1.0` for every rule except `VA-05`.
    pub(crate) fn tier_share(&self, tier: StoneTier) -> f64 {
        self.tier_magnitudes[tier as usize] / 100.0
    }
}

/// The Aspect rule sitting in `socket` — `None` when the socket is empty, when
/// the player owns no artifact at all, or when the stone in it ships switched
/// off.
///
/// Three left-column rules (`VA-02 Alternator`, `VA-03 Focused Engine`,
/// `VA-05 Small Gears`) are entered with their catalog numbers but cannot run
/// here: two need a slot-ordering rule for simultaneous procs and one needs
/// Legendary trigger content, and neither is on this branch. Filtering them at
/// the single read point is what makes "switched off" mean the same thing to
/// every rule site; `GameConfig::validate_artifacts` refuses to load such a stone
/// with `active: true` in the first place.
///
/// A socketed-but-inactive stone is deliberately still *socketed*: the player
/// keeps it, and the day its dependency ships it starts working with no
/// migration.
pub(crate) fn live_aspect_in_socket(
    config: &GameConfig,
    collection: &ArtifactCollection,
    socket: ArtifactSocketSlot,
) -> Option<AspectRuleInstance> {
    let (template, level) = mech::socketed_aspect(config, collection, socket)?;
    if !template.active {
        return None;
    }
    let mut tier_magnitudes = [100.0; StoneTier::COUNT];
    for tier in StoneTier::iter() {
        tier_magnitudes[tier as usize] = template.tier_magnitude(tier);
    }
    Some(AspectRuleInstance {
        rule: template.rule,
        stone_id: template.id,
        magnitude: template.magnitude_at_level(level),
        secondary_magnitude: template.secondary_magnitude,
        rule_param: template.rule_param,
        tier_magnitudes,
    })
}

/// Combat readings the flip/heartbeat rules need, taken in one immutable borrow.
///
/// Owns its enemy list rather than borrowing the fight: every caller reads first
/// and mutates the fight afterwards. [`FightReadings::ctx`] hands out the
/// borrowed, `Copy` view the effect runner wants.
struct FightReadings {
    player_id: EntityId,
    target_id: Option<EntityId>,
    enemy_ids: Vec<EntityId>,
    player_attack: f64,
    player_max_hp: u64,
    player_speed: i64,
    now: u64,
    active_side: WorldSide,
}

impl FightReadings {
    fn ctx(&self, source: CombatSource) -> StoneEffectCtx<'_> {
        StoneEffectCtx {
            source,
            target_id: self.target_id,
            enemy_ids: &self.enemy_ids,
            player_attack: self.player_attack,
            player_max_hp: self.player_max_hp,
            player_speed: self.player_speed,
            now: self.now,
        }
    }
}

impl OverlordLogic {
    /// Wears one artifact. Exactly one is worn at a time, so this is also the
    /// unequip path: the previously worn artifact keeps paying its ownership
    /// bonus and loses only its World Law.
    ///
    /// Putting on `ART-03 Halfway Bell` moves the flip bar *under* charge the
    /// player may already hold, so the persistent gauge is re-denominated here
    /// against the new bar. Without it, the next gain would find an accumulator
    /// past its threshold and zero it — an equip would silently burn up to a
    /// full gauge.
    pub fn handle_equip_artifact(
        &self,
        template_id: ArtifactTemplateId,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        // BAL-002/BAL-020: the artifact collection is server-denied before its
        // ch21 gate, not just hidden by client navigation.
        if state.character_state.character.current_chapter_level
            < self.game_config.get().artifacts_settings.unlock_chapter
        {
            tracing::error!("EquipArtifact refused: artifacts are locked at this chapter");
            return EventHandleResult::fail(state);
        }
        if let Err(err) = state.character_state.artifacts.equip(template_id) {
            tracing::error!("EquipArtifact refused: {err}");
            return EventHandleResult::fail(state);
        }
        let threshold =
            mech::flip_threshold(&self.game_config.get(), &state.character_state.artifacts);
        state.flip_state.retarget_progress(threshold);
        EventHandleResult::ok(state)
    }

    /// Puts an artifact stone into one of the six sockets.
    ///
    /// Two gates, both from config: the stone's catalog entry names the only
    /// socket it fits, and the unlock schedule says whether that socket is open
    /// at the player's chapter. The right-hand (Law) column is scheduled past
    /// the end of the campaign, so it is this same check — not a missing socket
    /// — that keeps it shut.
    pub fn handle_insert_artifact_stone(
        &self,
        template_id: ArtifactStoneTemplateId,
        socket: ArtifactSocketSlot,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        let game_config = self.game_config.get();
        let Some(template) = game_config
            .artifact_stones
            .iter()
            .find(|entry| entry.id == template_id)
        else {
            tracing::error!("InsertArtifactStone: no catalog entry for {template_id}");
            return EventHandleResult::fail(state);
        };
        let unlocked = game_config.artifacts_settings.is_socket_unlocked(
            socket,
            state.character_state.character.current_chapter_level,
        );

        if let Err(err) = state.character_state.artifacts.insert_stone(
            template_id,
            socket,
            template.socket,
            unlocked,
        ) {
            tracing::error!("InsertArtifactStone refused: {err}");
            return EventHandleResult::fail(state);
        }

        EventHandleResult::ok(state)
    }

    /// Points a right-column stone at the law it acts on, or clears the choice.
    ///
    /// Three gates, and the third is the interesting one:
    ///
    /// * the stone is in the catalog and sits in a **Law** socket — an Aspect
    ///   stone has no law to choose;
    /// * the law is in the catalog;
    /// * the law is **slotted on a core**. A law off the core does nothing, so
    ///   pointing a stone at one would create a reference that has to be
    ///   cleaned up later; refusing here plus clearing on `UnslotLaw` (the
    ///   monolith's `unslot`) is what makes "no dangling reference" true from
    ///   both ends.
    ///
    /// Deliberately NOT checked: that the law's side matches the socket. The
    /// Law sockets are Visible / Hidden / Bridge, and visible-versus-hidden is a
    /// PHASE, not a side — the same law is the visible one while its side is up
    /// and the hidden one while it is down. Every slotted law is therefore a
    /// legal target for every Law socket, and the half of the fight a stone
    /// speaks in is decided by the flip (post-merge plan §8).
    pub fn handle_set_artifact_stone_law_target(
        &self,
        template_id: ArtifactStoneTemplateId,
        law_template_id: Option<essences::cores::LawTemplateId>,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        let game_config = self.game_config.get();
        let Some(template) = game_config
            .artifact_stones
            .iter()
            .find(|entry| entry.id == template_id)
        else {
            tracing::error!("SetArtifactStoneLawTarget: no catalog entry for {template_id}");
            return EventHandleResult::fail(state);
        };
        let is_law_socket = template.socket.column() == ArtifactSocketColumn::Law;

        let slotted = match law_template_id {
            Some(law) => {
                if crate::mechanics::cores::law_template(&game_config, law).is_none() {
                    tracing::error!("SetArtifactStoneLawTarget: unknown law {law}");
                    return EventHandleResult::fail(state);
                }
                state
                    .character_state
                    .cores
                    .law(law)
                    .is_some_and(|owned| owned.slot_index.is_some())
            }
            None => false,
        };

        if let Err(err) = state.character_state.artifacts.set_law_target(
            template_id,
            law_template_id,
            is_law_socket,
            slotted,
        ) {
            tracing::error!("SetArtifactStoneLawTarget refused: {err}");
            return EventHandleResult::fail(state);
        }
        EventHandleResult::ok(state)
    }

    /// Takes a stone out of its socket. The stone keeps its level, its copies
    /// and its chosen law, so re-socketing restores exactly what it was.
    ///
    /// Losing `BL-01 Extra Span` also gives back the bridge it paid for
    /// ([`crate::mechanics::cores::prune_bridges_over_budget`]) — otherwise the
    /// stone is a one-way ratchet. This is the artifact-side mirror of
    /// `UnslotLaw` clearing the stone targets that pointed at the law it
    /// unslotted: each side cleans up the other's dangling half.
    pub fn handle_remove_artifact_stone(
        &self,
        template_id: ArtifactStoneTemplateId,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        if let Err(err) = state.character_state.artifacts.remove_stone(template_id) {
            tracing::error!("RemoveArtifactStone refused: {err}");
            return EventHandleResult::fail(state);
        }
        let game_config = self.game_config.get();
        let extra =
            mech::law_column_mods(&game_config, &state.character_state.artifacts).extra_bridges();
        let dropped = crate::mechanics::cores::prune_bridges_over_budget(
            &game_config,
            &mut state.character_state.cores,
            extra,
        );
        if dropped > 0 {
            tracing::info!(
                "RemoveArtifactStone {template_id}: dropped {dropped} bridge(s) left over the \
                 budget"
            );
        }
        EventHandleResult::ok(state)
    }

    /// Raises one artifact stone by one level, paid for in raw copies.
    ///
    /// The rule itself came whole with the first copy; a level only scales the
    /// magnitude (design §3), which is why nothing here consults the rule.
    pub fn handle_upgrade_artifact_stone(
        &self,
        template_id: ArtifactStoneTemplateId,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        let settings = &self.game_config.get().artifacts_settings;
        let Some(stone) = state.character_state.artifacts.stone(template_id) else {
            tracing::error!("UpgradeArtifactStone refused: unknown stone {template_id}");
            return EventHandleResult::fail(state);
        };
        let next_level = stone.level + 1;
        let Some(required) = settings.stone_upgrade_copies_required(next_level) else {
            tracing::error!(
                "UpgradeArtifactStone refused: no ladder rung for level {next_level} (stone is at \
                 the cap or the config has a gap)"
            );
            return EventHandleResult::fail(state);
        };

        if let Err(err) = state.character_state.artifacts.upgrade_stone(
            template_id,
            required,
            settings.max_stone_level,
        ) {
            tracing::error!("UpgradeArtifactStone refused: {err}");
            return EventHandleResult::fail(state);
        }

        EventHandleResult::ok(state)
    }

    /// Raises one artifact by one level and spends the configured raw-copy rung.
    ///
    /// Ownership and cap are checked before consulting the GameConfig ladder;
    /// the collection then atomically checks copies, spends them, and raises
    /// the level. Every refusal returns the unmodified state.
    pub fn handle_upgrade_artifact(
        &self,
        template_id: ArtifactTemplateId,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        let settings = &self.game_config.get().artifacts_settings;
        // BAL-002/BAL-020: server-denied before the ch21 gate.
        if state.character_state.character.current_chapter_level < settings.unlock_chapter {
            tracing::error!("UpgradeArtifact refused: artifacts are locked at this chapter");
            return EventHandleResult::fail(state);
        }
        let Some(artifact) = state.character_state.artifacts.get(template_id) else {
            tracing::error!("UpgradeArtifact refused: unknown artifact {template_id}");
            return EventHandleResult::fail(state);
        };
        if artifact.level >= settings.max_artifact_level {
            tracing::error!(
                "UpgradeArtifact refused: artifact {template_id} is already at max level {}",
                settings.max_artifact_level
            );
            return EventHandleResult::fail(state);
        }
        let next_level = artifact.level + 1;
        let Some(required) = settings.upgrade_copies_required(next_level) else {
            tracing::error!(
                "UpgradeArtifact refused: no ladder rung for level {next_level} (artifact is at \
                 the cap or the config has a gap)"
            );
            return EventHandleResult::fail(state);
        };

        if let Err(err) = state.character_state.artifacts.upgrade_artifact(
            template_id,
            required,
            settings.max_artifact_level,
        ) {
            tracing::error!("UpgradeArtifact refused: {err}");
            return EventHandleResult::fail(state);
        }

        EventHandleResult::ok(state)
    }

    /// Banks granted artifacts and artifact stones.
    ///
    /// An artifact duplicate banks one copy, including at the level cap. A
    /// stone duplicate likewise banks a copy. Neither grant path upgrades.
    ///
    /// A template that is not in the catalog is skipped and logged rather than
    /// stored: a dangling id would sit in the collection forever with no name,
    /// no rule and no way to remove it.
    pub fn handle_player_new_artifacts(
        &self,
        artifacts: &[ArtifactTemplateId],
        artifact_stones: &[ArtifactStoneTemplateId],
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        let game_config = self.game_config.get();
        for template_id in artifacts {
            if !game_config
                .artifacts
                .iter()
                .any(|entry| entry.id == *template_id)
            {
                tracing::warn!("Granted artifact {template_id} has no catalog entry — skipped");
                continue;
            }
            state.character_state.artifacts.grant_artifact(*template_id);
        }

        for template_id in artifact_stones {
            if !game_config
                .artifact_stones
                .iter()
                .any(|entry| entry.id == *template_id)
            {
                tracing::warn!(
                    "Granted artifact stone {template_id} has no catalog entry — skipped"
                );
                continue;
            }
            state.character_state.artifacts.grant_stone(*template_id);
        }

        EventHandleResult::ok(state)
    }

    /// BAL-031 faucet: one artifact stone from a campaign mob, a chapter boss
    /// or a cleared dungeon (the caller supplies the leg's signed chance).
    ///
    /// Deliberately a different faucet from the artifacts themselves (design
    /// §5), so the two collections never compete for one drop. The pick is
    /// uniform over the stones of the socket families the player's chapter has
    /// already made usable — before the first socket (ch91) the pool is empty
    /// and nothing drops, after the last (ch191) it is all 29.
    pub fn roll_artifact_stone_drop(
        &self,
        rng: &mut rand::rngs::StdRng,
        chance: f64,
        chapter_level: i64,
    ) -> Option<EventPluginized<OverlordEvent, OverlordState>> {
        if chance <= 0.0 {
            return None;
        }
        let game_config = self.game_config.get();
        let pool: Vec<_> = game_config
            .artifact_stones
            .iter()
            .filter(|stone| {
                game_config
                    .artifacts_settings
                    .is_socket_unlocked(stone.socket, chapter_level)
            })
            .map(|stone| stone.id)
            .collect();
        if pool.is_empty() {
            return None;
        }
        if rand::RngExt::random::<f64>(rng) >= chance {
            return None;
        }
        let index = rand::RngExt::random_range(rng, 0..pool.len());
        let template_id = *pool.get(index)?;
        Some(EventPluginized::now(OverlordEvent::PlayerNewArtifacts {
            artifacts: Vec::new(),
            artifact_stones: vec![template_id],
        }))
    }

    /// BAL-031: the guaranteed compatible L1 stones the character's chapter
    /// owes but the collection cannot serve. Each newly-usable socket family
    /// (ch91/111/131/151/171/191) guarantees ONE stone of its family; a family
    /// the player already owns any stone of needs nothing. Granting the result
    /// converges, so the check is safe on every chapter advance and on connect.
    pub fn missing_socket_artifact_stones(
        game_config: &configs::game_config::GameConfig,
        chapter: i64,
        collection: &essences::artifacts::ArtifactCollection,
    ) -> Vec<uuid::Uuid> {
        let owned_sockets: std::collections::HashSet<_> = collection
            .stones
            .iter()
            .filter_map(|stone| {
                game_config
                    .artifact_stones
                    .iter()
                    .find(|tpl| tpl.id == stone.template_id)
                    .map(|tpl| tpl.socket)
            })
            .collect();
        let mut missing: Vec<uuid::Uuid> = game_config
            .artifacts_settings
            .socket_unlocks
            .iter()
            .filter(|unlock| chapter >= unlock.unlock_chapter)
            .filter(|unlock| !owned_sockets.contains(&unlock.socket))
            .filter_map(|unlock| {
                game_config
                    .artifact_stones
                    .iter()
                    .find(|tpl| tpl.socket == unlock.socket && tpl.active)
                    .map(|tpl| tpl.id)
            })
            .collect();
        // Grant in template-id order — the same order `fetch_artifacts` loads
        // the rows back in, so the granted in-memory collection and the next
        // fetch stay byte-identical.
        missing.sort();
        missing
    }

    /// Readings the flip/heartbeat rules need. `None` when there is no live
    /// fight — which is also the cheap gate that keeps this hook off the hot
    /// path for every non-combat event.
    fn read_fight_for_aspects(
        &self,
        state: &OverlordState,
        owner_id: EntityId,
    ) -> Option<FightReadings> {
        let fight = state.active_fight.as_ref()?;
        if fight.fight_ended || fight.fight_stopped {
            return None;
        }
        let player_id = owner_id;
        let player = fight.entities.iter().find(|e| e.id == player_id)?;
        let game_config = self.game_config.get();

        let active_side = player
            .flip_state
            .map_or_else(essences::flip::WorldSide::default, |flip| flip.active_side);

        Some(FightReadings {
            player_id,
            target_id: crate::logic::stones::nearest_enemy(&fight.entities, player),
            enemy_ids: crate::logic::stones::living_enemies(&fight.entities, player),
            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),
            now: self.fight_clock.now(),
            active_side,
        })
    }

    /// The two Aspect rules that hang off the fight rather than off a trigger:
    /// «Теневой круг» on the heartbeat and the Flip pair on `GlobalFlip`.
    ///
    /// Runs from `apply_success_hooks`, like the stone triggers, for the same
    /// reason: the events it reacts to are properties of the event, not of which
    /// arm handled them.
    ///
    /// A build with no artifact leaves through the first early return having
    /// touched no state at all.
    pub fn apply_artifact_aspects(
        &mut self,
        state: &mut OverlordState,
        events: &mut Vec<EventPluginized<OverlordEvent, OverlordState>>,
        event: &OverlordEvent,
    ) {
        let Some(fight) = state.active_fight.as_ref() else {
            return;
        };
        // Every character combatant runs their OWN artifact: the local hero,
        // the party ally, and a human PvP opponent. Mobs and arena filler bots
        // carry no CharacterState and are skipped inside.
        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 owner_id in combatants {
            self.apply_artifact_aspects_for(state, events, event, owner_id);
        }
    }

    /// One combatant's pass of [`Self::apply_artifact_aspects`].
    fn apply_artifact_aspects_for(
        &mut self,
        state: &mut OverlordState,
        events: &mut Vec<EventPluginized<OverlordEvent, OverlordState>>,
        event: &OverlordEvent,
        owner_id: EntityId,
    ) {
        let Some(build) = crate::entities::combatant_character_state_of(state, owner_id) else {
            return;
        };
        if build.artifacts.stones.is_empty() {
            return;
        }
        match event {
            OverlordEvent::FightProgress {} => self.run_shadow_circle(state, events, owner_id),
            // Only the owner's own flip runs the owner's artifact.
            OverlordEvent::GlobalFlip {
                entity_id,
                to_side,
                revision,
                ..
            } if *entity_id == owner_id => {
                self.run_flip_aspect(state, events, owner_id, *to_side, *revision)
            }
            _ => {}
        }
    }

    /// «Теневой круг»: once every `rule_param` ticks, one hidden-side effect
    /// fires by itself, walking the slots in order.
    ///
    /// The fire is gated on wall position (`now >= due`), never on a count of
    /// heartbeats, and the next period is armed *before* the effect runs — the
    /// same two invariants the interval trigger rests on, and for the same
    /// reason: `FightProgress` is reachable from a Proc cascade.
    fn run_shadow_circle(
        &mut self,
        state: &mut OverlordState,
        events: &mut Vec<EventPluginized<OverlordEvent, OverlordState>>,
        owner_id: EntityId,
    ) {
        let game_config = self.game_config.get();
        // Clones, not borrows: the loop below interleaves mutable fight
        // borrows, and the build may live in `state.party` / `state.pvp_state`.
        let Some(build) = crate::entities::combatant_character_state_of(state, owner_id) else {
            return;
        };
        let stones = build.stones.clone();
        let Some(aspect) = live_aspect_in_socket(
            &game_config,
            &build.artifacts,
            ArtifactSocketSlot::HiddenAspect,
        )
        .filter(|aspect| aspect.rule == ArtifactStoneRule::ShadowRound) else {
            return;
        };
        let Some(readings) = self.read_fight_for_aspects(state, owner_id) else {
            return;
        };

        let now = self.fight_clock.now();
        let period = aspect.rule_param.max(1);
        let slots: Vec<ItemType> = ItemType::iter()
            .filter(|t| t.supports_world_side())
            .collect();
        if slots.is_empty() {
            return;
        }

        let (due, index) = {
            let Some(player) = state
                .active_fight
                .as_ref()
                .and_then(|fight| fight.entities.iter().find(|e| e.id == readings.player_id))
            else {
                return;
            };
            (
                crate::mechanics::stones::attr(player, mech::SHADOW_CIRCLE_DUE),
                crate::mechanics::stones::attr(player, mech::SHADOW_CIRCLE_INDEX),
            )
        };

        // Not armed yet: this is the first heartbeat of the fight. Arm the
        // period, do not fire on it — the same rule the interval trigger uses,
        // so the circle cannot fire on tick 0 of every fight.
        let armed = due != 0;
        if armed && (now as i64) < due {
            return;
        }

        let next_index = (index.rem_euclid(slots.len() as i64) + 1) % slots.len() as i64;
        {
            let Some(player) = state.active_fight.as_mut().and_then(|fight| {
                fight
                    .entities
                    .iter_mut()
                    .find(|e| e.id == readings.player_id)
            }) else {
                return;
            };
            player
                .attributes
                .set(mech::SHADOW_CIRCLE_DUE, now as i64 + period);
            if armed {
                player.attributes.set(mech::SHADOW_CIRCLE_INDEX, next_index);
            }
        }
        if !armed {
            return;
        }

        let slot = slots[index.rem_euclid(slots.len() as i64) as usize];
        let hidden_side = readings.active_side.flipped();
        let Some((template_id, level)) =
            StoneSocketKey::new(slot, StoneSocketSlot::effect_for(hidden_side))
                .and_then(|key| stones.socketed(key))
                .map(|stone| (stone.template_id, stone.level))
        else {
            // The visited slot has no hidden effect — the circle moves on rather
            // than searching, so its rate stays exactly one fire per period.
            return;
        };

        self.fire_artifact_effect(
            state,
            events,
            &readings,
            ArtifactFire {
                effect_template_id: template_id,
                effect_level: level,
                share: mech::share_multiplier(aspect.magnitude),
                delay_ticks: 0,
                artifact_stone_id: aspect.stone_id,
            },
        );
    }

    /// The three Flip-Aspect rules that land on the flip tick itself:
    ///
    /// * `FA-01 Incoming Salvo` — the five newly active effects, all at once;
    /// * `FA-05 Staggered Entrance` — the same five, spaced by the stone's
    ///   `rule_param`;
    /// * `FA-02 Last Word` — the five *departing* effects instead, one last time.
    ///
    /// The first two are a side-grade pair (burst versus stream); the third is
    /// their mirror in time — it pays the build that is being left behind rather
    /// than the one arriving. The remaining two rules of the socket (`FA-03`,
    /// `FA-04`) describe the ordinary procs *after* a flip and live in
    /// [`crate::logic::stones`].
    fn run_flip_aspect(
        &mut self,
        state: &mut OverlordState,
        events: &mut Vec<EventPluginized<OverlordEvent, OverlordState>>,
        flipped_entity: EntityId,
        to_side: WorldSide,
        revision: u64,
    ) {
        let game_config = self.game_config.get();
        // The flipping combatant's own build; the caller already matched the
        // flip to its owner, so this can only be a character combatant.
        let Some(build) = crate::entities::combatant_character_state_of(state, flipped_entity)
        else {
            return;
        };
        let stones = build.stones.clone();
        let Some(aspect) = live_aspect_in_socket(
            &game_config,
            &build.artifacts,
            ArtifactSocketSlot::FlipAspect,
        ) else {
            return;
        };
        // Which side speaks, and whether the fires land together or in order.
        let (side, spacing) = match aspect.rule {
            ArtifactStoneRule::IncomingSalvo => (to_side, 0),
            ArtifactStoneRule::StaggeredEntrance => (to_side, aspect.rule_param.max(0) as u64),
            ArtifactStoneRule::LastWord => (to_side.flipped(), 0),
            _ => return,
        };
        let Some(readings) = self.read_fight_for_aspects(state, flipped_entity) else {
            return;
        };

        // One volley per flip. `revision + 1` so an untouched attribute reads as
        // "no volley yet" even at revision 0.
        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 == readings.player_id)
            }) else {
                return;
            };
            if crate::mechanics::stones::attr(player, mech::FLIP_ASPECT_REVISION) == this_flip {
                return;
            }
            player.attributes.set(mech::FLIP_ASPECT_REVISION, this_flip);
        }

        let share = mech::share_multiplier(aspect.magnitude);
        let fires: Vec<(ItemType, uuid::Uuid, i64)> = ItemType::iter()
            .filter(|item_type| item_type.supports_world_side())
            .filter_map(|item_type| {
                StoneSocketKey::new(item_type, StoneSocketSlot::effect_for(side))
                    .and_then(|key| stones.socketed(key))
                    .map(|stone| (item_type, stone.template_id, stone.level))
            })
            .collect();

        for (position, (_, template_id, level)) in fires.into_iter().enumerate() {
            self.fire_artifact_effect(
                state,
                events,
                &readings,
                ArtifactFire {
                    effect_template_id: template_id,
                    effect_level: level,
                    share,
                    delay_ticks: spacing * position as u64,
                    artifact_stone_id: aspect.stone_id,
                },
            );
        }
    }

    /// Runs one Effect Stone as an artifact rebroadcast.
    ///
    /// Two things make this the single safe entry point for every artifact-fired
    /// effect, and both are asserted by `tests/test_artifact_provenance.rs`:
    ///
    /// * it goes through `run_stone_effect`, so its combat output is `Proc` and
    ///   can never re-enter a trigger;
    /// * it **drops** the gauge contribution, so a rebroadcast cannot fill the
    ///   gauge that would flip and rebroadcast again.
    ///
    /// The tier coefficient matrix is deliberately not consulted: there is no
    /// trigger in this path, so there is no `(trigger tier × effect tier)` pair
    /// to look up — the strength is the effect's own level scaling times the
    /// rule's share.
    fn fire_artifact_effect(
        &mut self,
        state: &mut OverlordState,
        events: &mut Vec<EventPluginized<OverlordEvent, OverlordState>>,
        readings: &FightReadings,
        fire: ArtifactFire,
    ) {
        let ArtifactFire {
            effect_template_id,
            effect_level,
            share,
            delay_ticks,
            artifact_stone_id,
        } = fire;
        if share <= 0.0 {
            return;
        }
        // A spaced-out fire defers the whole run rather than the events it would
        // emit. Under v0.2 arming is a direct write with no event to postpone,
        // and deferring the run keeps `FA-05` a real side-grade of `FA-01`:
        // effects half a second apart get spent between each other instead of
        // overwriting one another inside a single tick.
        if delay_ticks > 0 {
            self.fight_clock.schedule(
                OverlordEvent::FireArtifactEffect {
                    owner_id: readings.player_id,
                    effect_template_id,
                    effect_level,
                    share_permyriad: (share * SHARE_PERMYRIAD as f64).round() as i64,
                    artifact_stone_id,
                },
                delay_ticks,
            );
            return;
        }
        let game_config = self.game_config.get();
        let Some(effect) = game_config.effect_stone_template(effect_template_id) else {
            tracing::warn!(
                template_id = %effect_template_id,
                "Skipping artifact-fired Effect Stone with no catalog entry"
            );
            return;
        };
        let magnitude = (effect.magnitude
            + effect.magnitude_per_level * (effect_level - 1).max(0) as f64)
            * share;

        let _gauge_is_dropped_on_purpose = self.run_stone_effect(
            state,
            events,
            readings.player_id,
            effect,
            magnitude,
            readings.ctx(CombatSource::ArtifactStoneProc {
                artifact_stone_template_id: artifact_stone_id,
            }),
        );
    }

    /// Runs the deferred half of `FA-05 Staggered Entrance`.
    ///
    /// The readings are taken **now**, not carried from the flip: the nearest
    /// enemy half a second later may be a different one, and a fight that ended
    /// in between leaves nothing to run against — in which case the event quietly
    /// does nothing.
    pub fn handle_fire_artifact_effect(
        &mut self,
        owner_id: EntityId,
        effect_template_id: uuid::Uuid,
        effect_level: i64,
        share_permyriad: i64,
        artifact_stone_id: ArtifactStoneTemplateId,
        mut state: OverlordState,
    ) -> EventHandleResult<OverlordEvent, OverlordState> {
        let Some(readings) = self.read_fight_for_aspects(&state, owner_id) else {
            return EventHandleResult::ok(state);
        };
        let mut events = Vec::new();
        self.fire_artifact_effect(
            &mut state,
            &mut events,
            &readings,
            ArtifactFire {
                effect_template_id,
                effect_level,
                share: share_permyriad as f64 / SHARE_PERMYRIAD as f64,
                delay_ticks: 0,
                artifact_stone_id,
            },
        );
        EventHandleResult::ok_events(state, events)
    }
}