overlord_event_system/

event.rs

use chrono::Utc;
use configs::cheats::CheatScriptId;
use essences::ability_presets::AbilityPresetId;
use essences::ability_stones::{
    AbilityStoneDrop, AbilityStoneId, AbilityStoneSocketIndex, UpgradedAbilityStonesMap,
};
use essences::ad_usage::AdPlacement;
use essences::artifacts::{ArtifactSocketSlot, ArtifactStoneTemplateId, ArtifactTemplateId};
use essences::autochest::{AutoChestFilter, AutoChestFilterId};
use essences::combat_origin::CombatEventOrigin;
use essences::cores::LawTemplateId;
use essences::currency::{CurrencyConsumer, CurrencySource, CurrencyUnit};
use essences::dungeons::DungeonTemplateId;
use essences::entity::EssencesCustomEventData;
use essences::entity::{Coordinates, EntityAttributes, EntityId};
use essences::fight_breakdown::CombatSource;
use essences::fighting::{EntityTeam, FightTemplateId};
use essences::flip::{FlipProgressSource, WorldSide};
use essences::game::EntityTemplateId;
use essences::gift::Gift;
use essences::items::{Item, ItemTemplateId, ItemType};
use essences::offers::{Offer, OfferId, OfferTemplateId};
use essences::pet_facets::PetFacetLawRole;
use essences::pets::{EquippedPets, PetCaseRollType, PetDrop, PetId, PetSlotId, UpgradedPetsMap};
use essences::plinko::PlinkoDirection;
use essences::prelude::*;
use essences::pvp::PVPState;
use essences::quest::QuestGroupType;
use essences::skins::SkinId;
use essences::stones::{StoneSocketSlot, StoneTemplateId, UpgradedStonesMap};
use essences::talent_tree::TalentId;
use essences::vassals::Suzerain;
use essences::vassals::VassalTask;
use essences::{
    abilities::{
        AbilityCaseRollType, AbilityDrop, AbilityId, AbilitySlotId, EquippedAbilities,
        UpgradedAbilitiesMap,
    },
    bundles::BundleId,
};
use event_system::derive::Event;
use event_system::derive::EventTypeName;
pub use event_system::event::Event;
use event_system::event::EventStruct;
use schemars::JsonSchema;
use std::collections::BTreeMap;

#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, JsonSchema, Tsify)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub enum AdRewardType {
    AfkInstant,
    AfkBoost,
    DailyBooster,
    UpgradeSpeedup,
    FreeAbilityCaseOpen,
    FreePetCaseOpen,
    DungeonRaid {
        dungeon_id: DungeonTemplateId,
        difficulty: i64,
    },
    ArenaRefresh,
    ClaimBirdReward {
        variant_id: configs::ads_settings::BirdVariantId,
    },
}

#[derive(
    PartialEq,
    Eq,
    Clone,
    Debug,
    Event,
    EventTypeName,
    JsonSchema,
    Tsify,
    Serialize,
    Deserialize,
    strum_macros::Display,
    strum_macros::VariantNames,
)]
#[tsify(into_wasm_abi, from_wasm_abi, namespace)]
pub enum OverlordEvent {
    // Item Case
    #[event_type(client)]
    OpenItemCase {
        batch_size: i64,
    },
    AutoChestOpenItemCase {
        batch_size: i64,
    },
    PlayerNewItems {
        items: Vec<Item>,
    },
    #[event_type(client)]
    PlayerEquipItem {
        item_id: Uuid,
    },
    #[event_type(client)]
    SellItem {
        item_id: Uuid,
    },
    ItemSold {
        item_id: Uuid,
    },
    /// Сервер→клиент: предметы с истёкшим TTL удалены (само удаление — в патче).
    ItemsExpired {
        item_ids: Vec<Uuid>,
    },
    /// Сервер→клиент: путь шарика Plinko для одного выданного предмета.
    ///
    /// Путь катит сервер (он же начисляет статы за задетые колышки), клиент
    /// только проигрывает анимацию ровно по этим шагам. Событие идёт СЛЕДОМ
    /// за `PlayerNewItems`, чтобы предмет уже был в инвентаре; связь с
    /// наградой — по `item_id`. `PlayerNewItems` выдаётся и вне Plinko
    /// (временные предметы при входе, награды) — там этого события нет.
    PlinkoBallDropped {
        item_id: Uuid,
        path: Vec<PlinkoDirection>,
    },
    #[event_type(client)]
    UpgradeItemCase {},
    ItemCaseUpgraded {},
    #[event_type(client)]
    SpeedupUpgradeItemCase {},
    #[event_type(client)]
    SkipUpgradeItemCase {},
    #[event_type(client)]
    ClaimUpgradeItemCase {},

    #[event_type(client)]
    EnableAutoSell {},

    #[event_type(client)]
    DisableAutoSell {},

    #[event_type(client)]
    SetGearOverrideEnabled {
        item_type: ItemType,
        enabled: bool,
    },

    // Auto-chest
    #[event_type(client)]
    EnableAutoChest {},

    #[event_type(client)]
    DisableAutoChest {},

    #[event_type(client)]
    EnableAutoChestFilter {
        filter_id: AutoChestFilterId,
    },

    #[event_type(client)]
    DisableAutoChestFilter {},

    #[event_type(client)]
    EnableAutoChestPowerCompare {},

    #[event_type(client)]
    DisableAutoChestPowerCompare {},

    #[event_type(client)]
    UpdateAutoChestBatchSize {
        batch_size: i64,
    },

    #[event_type(client)]
    NewAutoChestFilter {
        // Boxed: `AutoChestFilter` is ~104 bytes — keeping it inline pushes the
        // enum's stack size up across all 191 variants. Serde sees `Box<T>` as
        // `T`, so the wire format is unchanged.
        filter: Box<AutoChestFilter>,
    },

    #[event_type(client)]
    UpdateAutoChestFilter {
        updated_filter: Box<AutoChestFilter>,
    },

    #[event_type(client)]
    RemoveAutoChestFilter {
        filter_id: AutoChestFilterId,
    },

    // Ability Case
    #[event_type(client)]
    OpenAbilityCase {
        roll_type: AbilityCaseRollType,
    },

    /// Обновляет вишлист гачи способностей.
    /// Список ограничен числом слотов и разрешенными редкостями текущего уровня гачи.
    #[event_type(client)]
    SetAbilityGachaWishlist {
        ability_ids: Vec<AbilityId>,
    },

    /// Повышает уровень указанного слота способностей за Stardust.
    #[event_type(client)]
    UpgradeAbilitySlot {
        slot_id: u64,
    },

    AbilityCaseOpened {
        batch_size: u8,
    },

    // For frontend display and quest progression
    NewAbilities {
        abilities: Vec<AbilityDrop>,
    },

    #[event_type(client)]
    FastEquipAbilities {},

    #[event_type(client)]
    EquipAbility {
        slot_id: u64,
        ability_id: AbilityId,
    },

    #[event_type(client)]
    UnequipAbility {
        slot_id: AbilitySlotId,
    },

    EquipAbilities {
        equipped_abilities: EquippedAbilities,
    },

    #[event_type(client)]
    UpgradeAbility {
        ability_id: AbilityId,
    },

    #[event_type(client)]
    UpgradeAllAbilities {},

    // For frontend display and quests progression
    UpgradedAbilities {
        upgraded_abilities: UpgradedAbilitiesMap,
    },

    UpgradeAbilityCase {},

    // Ability stones
    /// Ставит камень способности в сокет. Сокет несёт сторону (Real/Fantasy),
    /// поэтому один и тот же камень подходит в любой из сокетов.
    #[event_type(client)]
    SocketAbilityStone {
        ability_id: AbilityId,
        socket_index: AbilityStoneSocketIndex,
        stone_id: AbilityStoneId,
    },

    /// Вынимает камень из сокета способности.
    #[event_type(client)]
    UnsocketAbilityStone {
        ability_id: AbilityId,
        socket_index: AbilityStoneSocketIndex,
    },

    /// Повышает уровень камня способности, тратя его сырые копии.
    #[event_type(client)]
    UpgradeAbilityStone {
        stone_id: AbilityStoneId,
    },

    /// Выдача копий камней способностей (дроп/награда). Серверное событие.
    NewAbilityStones {
        stones: Vec<AbilityStoneDrop>,
    },

    CurrencyIncrease {
        currencies: Vec<CurrencyUnit>,
        currency_source: CurrencySource,
    },

    CurrencyDecrease {
        currencies: Vec<CurrencyUnit>,
        currency_consumer: CurrencyConsumer,
    },

    // Level
    NewCharacterLevel {
        level: i64,
    },

    // Fight management
    // Server-only: emitted by the backend on the `ClientReady` handshake,
    // never accepted from a client `ClientEvents` envelope.
    StartGame {},
    #[event_type(client)]
    PrepareFight {
        prepare_fight_type: PrepareFightType,
    },
    #[event_type(client)]
    StartFight {
        fight_id: Uuid,
    },
    #[event_type(client)]
    FightProgress {},
    EndFight {
        fight_id: Uuid,
        is_win: bool,
        // Boxed: `PVPState` is 256 bytes, which alone determined sizeof
        // OverlordEvent (~280 bytes including discriminant). Boxing this one
        // field shrinks the enum's footprint across every queue/Vec/future
        // that carries an OverlordEvent. Serde-transparent over Box.
        pvp_state: Option<Box<PVPState>>,
    },
    StageCleared {},

    #[event_type(client)]
    RaidDungeon {
        dungeon_id: DungeonTemplateId,
        difficulty: i64,
        amount: i64,
    },

    WaveCleared {},

    // PVP
    #[event_type(client)]
    StartVassalPVPSync {
        opponent_id: Uuid,
        opponent_suzerain_id: Option<Uuid>,
    },

    #[event_type(client)]
    StartArenaPVPSync {
        opponent_id: Uuid,
        is_bot: bool,
    },

    #[event_type(client)]
    StartArenaRematchSync {
        match_id: Uuid,
    },

    #[event_type(client)]
    RefreshArenaMatchmaking {},

    #[event_type(client)]
    BuyArenaTicket {},

    // Moving
    StartMove {
        entity_id: Uuid,
        to: Coordinates,
        duration_ticks: u64,
    },
    // Event is delayed, so it must be non_deterministic
    EndMove {
        entity_id: Uuid,
    },

    // Fighting
    SpawnEntity {
        id: EntityId,
        entity_template_id: EntityTemplateId,
        position: Coordinates,
        entity_team: EntityTeam,
        has_big_hp_bar: bool,
        entity_attributes: EntityAttributes,
    },

    StartCastAbility {
        by_entity_id: Uuid,
        ability_id: AbilityId,
        pet_id: Option<PetId>,
        /// Core/Proc provenance carried to this event's own output — see
        /// [`OverlordEvent::carried_origin`].
        origin: CombatEventOrigin,
    },
    // Event is delayed, so it must be non_deterministic
    StartedCastAbility {
        by_entity_id: Uuid,
        ability_id: AbilityId,
        duration_ticks: u64,
        /// Core/Proc provenance carried to this event's own output — see
        /// [`OverlordEvent::carried_origin`].
        origin: CombatEventOrigin,
    },
    CastAbility {
        by_entity_id: Uuid,
        to_entity_id: Uuid,
        ability_id: AbilityId,
        /// Core/Proc provenance carried to this event's own output — see
        /// [`OverlordEvent::carried_origin`].
        origin: CombatEventOrigin,
    },
    StartCastProjectile {
        by_entity_id: Uuid,
        to_entity_id: Uuid,
        projectile_id: Uuid,
        level: i64,
        delay: u64,
        /// What launched this projectile, carried to the landing so the hit is
        /// attributed to the ability rather than to the projectile template —
        /// a projectile is how a skill delivers its payload, and the catalog
        /// gives projectiles no display name of their own.
        source: CombatSource,
        /// Core/Proc provenance carried to this event's own output — see
        /// [`OverlordEvent::carried_origin`].
        origin: CombatEventOrigin,
    },
    StartedCastProjectile {
        by_entity_id: Uuid,
        to_entity_id: Uuid,
        projectile_id: Uuid,
        duration_ticks: u64,
        /// See [`OverlordEvent::StartCastProjectile::source`].
        source: CombatSource,
        /// Core/Proc provenance carried to this event's own output — see
        /// [`OverlordEvent::carried_origin`].
        origin: CombatEventOrigin,
    },
    /// A DERIVED copy of an ability's payload produced by a support stone
    /// (Repeat / Pulse): the ability's own payload, scaled by
    /// `payload_permille`, landing `delay` ticks after the original cast.
    ///
    /// It is deliberately NOT a cast: it never runs `on_cast`, never pays mana,
    /// never touches a cooldown and never charges the pet bar, and the damage it
    /// produces is tagged `derived` — so no Law, Resonance, Mastery or trigger
    /// reader may count it as a Core event.
    DerivedAbilityStrike {
        by_entity_id: Uuid,
        to_entity_id: Uuid,
        ability_id: AbilityId,
        level: i64,
        /// Payload share in permille (500 = 50% of the ability's payload).
        payload_permille: i64,
        /// What the SOURCE cast finally paid for its mana, in x100 fixed point,
        /// or `-1` when it never paid (no pool, a pet ult). A delayed copy
        /// resolves after other casts may have landed, so it carries the price
        /// with it instead of reading whatever the caster paid last — that is
        /// what lets a Mana-conditioned law or trigger judge the RE-trigger by
        /// the same cost as the original (BAL-019).
        source_paid_mana_x100: i64,
        /// Ticks (ms) to wait before the copy resolves. Routed onto the fight
        /// clock at the cast site; the scheduled copy carries 0.
        delay: u64,
    },
    /// `EntityIncrAttribute` that lands `delay` ticks later. Used by the
    /// Shelter support to close its damage-reduction window; the fight clock
    /// owns the timer, so nothing has to be polled per tick.
    EntityIncrAttributeDelayed {
        entity_id: Uuid,
        attribute: String,
        delta: i64,
        delay: u64,
    },
    // TODO move all projectiles into state, and make fight_progress manage them, so we dont need deterministic
    // Event is delayed, so it must be non_deterministic
    CastProjectile {
        by_entity_id: Uuid,
        to_entity_id: Uuid,
        projectile_id: Uuid,
        level: i64,
        projectile_data: CustomEventData,
        /// See [`OverlordEvent::StartCastProjectile::source`].
        source: CombatSource,
        /// Core/Proc provenance carried to this event's own output — see
        /// [`OverlordEvent::carried_origin`].
        origin: CombatEventOrigin,
    },
    Damage {
        /// Combatant responsible for this damage. Ownerless environment and
        /// legacy effects use `None` and do not grant flip progress.
        by_entity_id: Option<EntityId>,
        entity_id: Uuid,
        damage: u64,
        damage_data: CustomEventData,
        /// Core/Proc provenance — see [`OverlordEvent::combat_origin`].
        origin: CombatEventOrigin,
        /// WHICH producer this damage belongs to — the attribution the
        /// end-of-fight breakdown is built from. Stamped at the emit site,
        /// where the producing id is in scope; `origin` answers "was this a
        /// modifier's work", this answers "whose".
        source: CombatSource,
    },
    /// Server-authored marker for one completed global equipment-side flip.
    GlobalFlip {
        /// Fight-local entity whose equipment presentation changed. This is
        /// required because PvP and party fights can contain several players,
        /// each with an independent flip state.
        entity_id: EntityId,
        /// Producer that supplied the threshold-crossing progress gain.
        source: FlipProgressSource,
        /// Side presented before this transition.
        from_side: WorldSide,
        /// Side presented after this transition.
        to_side: WorldSide,
        /// Monotonic transition key copied from the resulting `FlipState`.
        revision: u64,
    },
    /// Server-authored marker for one Trigger-Stone fire. The combat outcomes a
    /// fire produces are deliberately anonymous (`origin: Proc` carries no
    /// source), so this is the only client-visible record of WHICH socketed
    /// trigger fired — the UI attributes the proc to its equipment slot with it.
    /// Nothing reads it server-side.
    StoneTriggerFired {
        /// Fight-local combatant whose socketed trigger fired.
        entity_id: EntityId,
        /// Equipment slot whose Trigger socket held the fired stone.
        item_type: ItemType,
        /// Catalog id of the fired Trigger Stone.
        trigger_stone_id: StoneTemplateId,
    },
    Heal {
        /// Combatant responsible for this heal. `None` for ownerless healing
        /// (regeneration on a mob, environment effects).
        by_entity_id: Option<EntityId>,
        entity_id: Uuid,
        heal: u64,
        /// Core/Proc provenance — see [`OverlordEvent::combat_origin`].
        origin: CombatEventOrigin,
        /// Producer of this heal — see [`OverlordEvent::Damage::source`].
        source: CombatSource,
    },
    CounterAttack {
        by_entity_id: Uuid,
        to_entity_id: Uuid,
        duration_ticks: u64,
        /// Core/Proc provenance — see [`OverlordEvent::combat_origin`].
        origin: CombatEventOrigin,
    },
    Multicast {
        entity_id: Uuid,
        amount: u64,
        /// Core/Proc provenance — see [`OverlordEvent::combat_origin`].
        origin: CombatEventOrigin,
    },
    Evasion {
        entity_id: Uuid,
        /// Core/Proc provenance — see [`OverlordEvent::combat_origin`].
        origin: CombatEventOrigin,
    },
    PlayerDeath {},
    EntityDeath {
        entity_id: Uuid,
        reward: Vec<CurrencyUnit>,
        /// Core/Proc provenance — see [`OverlordEvent::combat_origin`].
        origin: CombatEventOrigin,
    },
    EntityIncrAttribute {
        entity_id: Uuid,
        attribute: String,
        delta: i64,
    },
    EntityAddAbilityCooldown {
        entity_id: Uuid,
        ability_id: Uuid,
        delta_ticks: i64,
    },
    EntityCancelCastWithCooldown {
        entity_id: Uuid,
        ability_id: Uuid,
    },
    /// Stuns an entity for `duration_ticks`. Internally cancels any in-flight cast (sending it
    /// to its full cooldown), and freezes every ability's cooldown progression by extending
    /// each one by `duration_ticks`. Off-cooldown abilities get a fresh stun-only cooldown.
    /// Designers fire this from the `stun` effect's apply script — no per-ability iteration in
    EntityStun {
        entity_id: Uuid,
        duration_ticks: u64,
    },
    EntityApplyEffect {
        entity_id: Uuid,
        effect_id: Uuid,
        /// Core/Proc provenance carried to this event's own output — see
        /// [`OverlordEvent::carried_origin`].
        origin: CombatEventOrigin,
    },
    CastEffect {
        entity_id: Uuid,
        effect_id: Uuid,
        /// Core/Proc provenance carried to this event's own output — see
        /// [`OverlordEvent::carried_origin`].
        origin: CombatEventOrigin,
    },
    CastEffectFromEvent {
        entity_id: Uuid,
        effect_id: Uuid,
        caller_event: Box<OverlordEvent>,
    },
    FightCustomEvent {
        entity_id: u64,
        value: String,
    },
    FightVisualEvent {
        effect_type: String,
        effect_data: CustomEventData,
    },

    SetMaxHp {
        entity_id: EntityId,
        new_max_hp: u64,
        new_hp: u64,
    },

    // Vassal Links
    #[event_type(client)]
    ClaimVassalReward {
        character_id: Uuid,
    },

    #[event_type(client)]
    ClaimSuzerainReward {},

    NewSuzerain {
        new_suzerain: Option<Box<Suzerain>>,
    },

    RemoveVassal {
        vassal_id: Uuid,
    },

    // Vassal Tasks
    #[event_type(client)]
    GiveTask {
        vassal_id: Uuid,
        template_task_id: Uuid,
    },

    NewTask {
        new_task: Box<VassalTask>,
    },

    #[event_type(client)]
    AcceptTask {
        task_id: Uuid,
        is_good: bool,
    },

    TaskAccepted {
        task_id: Uuid,
        started_good: bool,
        started_at: chrono::DateTime<Utc>,
        finish_at: chrono::DateTime<Utc>,
    },

    #[event_type(client)]
    HitHands {
        task_id: Uuid,
    },

    HandsHitted {
        task_id: Uuid,
    },

    TaskFinished {
        task_id: Uuid,
    },

    #[event_type(client)]
    ClaimTaskReward {
        task_id: Uuid,
    },

    // Resist Task
    GiveResistTask {
        new_resist_task: Box<VassalTask>,
    },

    #[event_type(client)]
    AcceptResistTask {},

    ResistTaskAccepted {
        new_resist_task: Box<VassalTask>,
    },

    #[event_type(client)]
    CatchResistTask {
        task_id: Uuid,
    },

    ResistTaskCatched {
        task_id: Uuid,
    },

    ResistTaskFinished {
        task_id: Uuid,
    },

    #[event_type(client)]
    ClaimResistTaskReward {
        task_id: Uuid,
    },

    // Custom value
    SetCustomValue {
        key: String,
        value: i64,
    },

    // Connection store
    SetConnectionStore {
        key: String,
        value: i64,
    },

    // Quest
    #[event_type(client)]
    ClaimQuest {
        quest_id: Uuid,
    },

    #[event_type(client)]
    ClaimAllQuests {
        quest_group_type: QuestGroupType,
    },

    PatronQuestCompleted {
        quest_id: Uuid,
    },

    HiddenQuestCompleted {
        quest_id: Uuid,
    },

    QuestCompleted {
        quest_id: Uuid,
    },

    NewQuests {
        quest_ids: Vec<Uuid>,
    },

    // Triggered when loop task flow breaks
    UpdateActiveLoopTaskId {
        quest_id: Uuid,
    },

    ResetRepeatingQuests {
        quest_ids: Vec<Uuid>,
    },

    #[event_type(client)]
    ClaimQuestProgressionReward {
        quest_group_type: QuestGroupType,
    },

    // Referrals
    #[event_type(client)]
    ClaimReferralLvlUpReward {
        level: i64,
    },

    #[event_type(client)]
    ClaimReferralDailyReward {},

    ReferralDailyRewardStatusUpdate {
        referral_daily_reward_status: bool,
    },

    // Gifts
    #[event_type(client)]
    SendGift {
        receiver_id: Uuid,
        config_gift_id: Uuid,
    },

    NewGift {
        new_gift: Box<Gift>,
    },

    #[event_type(client)]
    AcceptGift {
        gift_id: Uuid,
    },

    // AfkReward
    #[event_type(client)]
    ClaimAfkReward {},

    AfkRewardClaimed {},

    /// Emitted when the player crosses the AFK rewards unlock chapter threshold
    /// and the async handler has adjusted `last_afk_reward_claimed_at` so that
    /// the elapsed time is not less than `min_required_time_sec`.
    /// The side effect handler persists the new value to the database.
    AfkRewardsGatingUnlocked {},

    #[event_type(client)]
    ClaimAfkInstantRewardGems {},

    // Ad Rewards
    #[event_type(client)]
    WatchAd {
        ad_reward_type: AdRewardType,
    },

    ShowBird {
        variant_id: configs::ads_settings::BirdVariantId,
    },

    /// Отправляется клиентом, когда птица была успешно показана игроку.
    /// Переводит птицу в полный кулдаун.
    #[event_type(client)]
    BirdShown {},

    ResetAdUsage {
        placements: Vec<AdPlacement>,
    },

    ResetInstantRewardGemsPressCount {},

    // Bundles
    #[event_type(client)]
    ClaimBundleStepGeneric {},

    AddBundleGroup {
        bundle_ids: Vec<BundleId>,
        // Origin of the bundle — propagates through claim so currency analytics
        // sees the real source (e.g. `QuestClaim`) instead of the generic
        // `BundleClaim`.
        //
        // `#[serde(skip)]` keeps this server-only. The event still flows
        // through `ServerTick.events` over postcard to the client, but the field
        // is omitted from the wire so the layout matches what pre-PR clients
        // already know. The server always constructs this event with `source`
        // populated at the call site, then consumes it in
        // `handle_add_bundle_group` before any wire encoding happens, so the
        // skip never loses real data.
        #[serde(skip)]
        source: essences::currency::CurrencySource,
    },

    // Classes
    #[event_type(client)]
    LevelUpClass {
        class_id: uuid::Uuid,
    },

    #[event_type(client)]
    Respec {
        new_class_id: uuid::Uuid,
    },

    // User Account
    #[event_type(client)]
    LinkGuestAccount {
        token: String,
    },

    #[event_type(client)]
    SetUsername {
        username: String,
    },

    #[event_type(client)]
    SetCharacterBlocked {
        character_id: Uuid,
        blocked: bool,
    },

    // Ability Presets
    #[event_type(client)]
    CreateAbilityPreset {
        name: Option<String>,
        ability_ids: Vec<AbilityId>,
        index: i64,
    },

    #[event_type(client)]
    EditAbilityPreset {
        preset_id: AbilityPresetId,
        name: String,
        ability_ids: Vec<AbilityId>,
    },

    EnableCaseUpgradePopUp {},

    #[event_type(client)]
    DisableCaseUpgradePopUp {},

    // Skins
    #[event_type(client)]
    BuySkins {
        skin_ids: Vec<SkinId>,
        equip: bool,
    },

    #[event_type(client)]
    EquipAndUnequipSkins {
        equip_skin_ids: Vec<SkinId>,
        unequip_skin_ids: Vec<SkinId>,
    },

    // Cheat
    #[event_type(client)]
    RunCheat {
        cheat: Cheat,
    },

    // Mail
    #[event_type(client)]
    ClaimMail {
        mail_id: essences::mail::MailId,
    },

    #[event_type(client)]
    ClaimAllMails {},

    #[event_type(client)]
    MakeRead {
        mail_id: essences::mail::MailId,
    },

    #[event_type(client)]
    MakeAllRead {},

    #[event_type(client)]
    DeleteMail {
        mail_id: essences::mail::MailId,
    },

    #[event_type(client)]
    DeleteAllMails {},

    NewMail {
        new_mail: Box<essences::mail::Mail>,
    },

    // Offers
    #[event_type(client)]
    NewOffer {
        offer_template_id: OfferTemplateId,
    },

    #[event_type(client)]
    BuyOffer {
        purchase_token: Option<String>,
        offer_id: OfferId,
    },

    OfferPurchaseCompleted {
        purchase_token: String,
        offer_id: OfferId,
        is_test_purchase: bool,
    },

    OfferPurchaseFailed {
        purchase_token: String,
        offer_id: OfferId,
    },

    PurchasesBanned {},

    ResetOffers {
        new_offers: Vec<Offer>,
    },

    // Pets
    #[event_type(client)]
    EquipPet {
        slot_id: u64,
        pet_id: PetId,
    },

    #[event_type(client)]
    UnequipPet {
        slot_id: PetSlotId,
    },

    #[event_type(client)]
    FastEquipPets {},

    EquipPets {
        equipped_pets: EquippedPets,
    },

    #[event_type(client)]
    UpgradePet {
        pet_id: PetId,
    },

    #[event_type(client)]
    UpgradeAllPets {},

    /// Pet Facets: the out-of-combat pre-selection the three "one chosen Law"
    /// facets act on (`Lead Reading`, `Wild Reading`, `Dream Reader`).
    ///
    /// `None` clears the slot, which is legal: an unset selection falls back to
    /// the lowest-slot eligible Law rather than switching the facet off.
    #[event_type(client)]
    SetPetFacetLaw {
        role: PetFacetLawRole,
        law_template_id: Option<LawTemplateId>,
    },

    // For frontend display and quests progression
    UpgradedPets {
        upgraded_pets: UpgradedPetsMap,
    },

    #[event_type(client)]
    UpgradePetSlot {
        slot_id: u64,
    },

    // Pet Case (Gacha)
    #[event_type(client)]
    OpenPetCase {
        roll_type: PetCaseRollType,
    },

    /// Обновляет вишлист гачи петов.
    #[event_type(client)]
    SetPetGachaWishlist {
        pet_ids: Vec<PetId>,
    },

    PetCaseOpened {
        batch_size: u8,
    },

    // For frontend display and quest progression
    NewPets {
        pets: Vec<PetDrop>,
    },

    UpgradePetCase {},

    // Tutorial
    #[event_type(client)]
    TutorialShown {
        step_number: i16,
    },
    #[event_type(client)]
    TutorialStepCompleted {
        step_number: i16,
    },

    /// Client lifecycle transition used for churn diagnostics.
    /// Sent when the Unity app is paused/resumed or loses/regains focus.
    #[event_type(client)]
    ClientLifecycle {
        lifecycle_status: String,
        active_screen_code: String,
        session_uptime_secs: i64,
        current_chapter_level: i64,
        current_character_level: i64,
        current_power: i64,
        active_fight: bool,
        active_fight_current_wave: i64,
    },

    // Party
    #[event_type(client)]
    AddCharacterToParty {
        character_id: uuid::Uuid,
    },
    #[event_type(client)]
    RemoveCharacterFromParty {},
    #[event_type(client)]
    RefreshPartyPlayers {},
    RefreshPartyMemberState {},

    // Talent Tree
    /// Начать изучение следующего уровня таланта (клиент -> бэкенд).
    #[event_type(client)]
    StartTalentResearch {
        talent_id: TalentId,
    },
    /// Бэкенд подтверждает начало изучения таланта.
    TalentResearchStarted {
        talent_id: TalentId,
        finish_at: chrono::DateTime<chrono::Utc>,
    },
    /// Ускорить изучение таланта с помощью таймскип-билетика.
    #[event_type(client)]
    SpeedupTalentResearch {},
    /// Пропустить оставшееся время изучения за валюту (брюли/таймскипы).
    #[event_type(client)]
    SkipTalentResearch {},
    /// Забрать завершённый талант (после истечения таймера). Эмитируется бэкендом автоматически.
    ClaimTalentResearch {},

    // Statue
    /// Откатить незаблокированные слоты статуи. Списывает валюту, начисляет опыт статуе.
    #[event_type(client)]
    StatueRoll {
        set_index: u8,
        locked_slot_indices: Vec<u8>,
    },
    /// Сделать указанный сет статуи активным ("In Use").
    #[event_type(client)]
    StatueActivateSet {
        set_index: u8,
    },
    /// Добавить новый сет статуи (если уровень статуи позволяет).
    #[event_type(client)]
    StatueAddSet {},
    /// Переименовать сет статуи.
    #[event_type(client)]
    StatueRenameSet {
        set_index: u8,
        name: String,
    },
    /// Заблокировать или разблокировать слот статуи.
    #[event_type(client)]
    StatueLockSlot {
        set_index: u8,
        slot_index: u8,
        is_locked: bool,
    },
    /// Бесплатный первичный ролл для нового слота на любом сете (после создания сета или повышения уровня статуи).
    #[event_type(client)]
    StatueRollNewSlot {
        set_index: u8,
        slot_index: u8,
    },

    // Cores / laws / bridges (OVT-2517)
    /// Поднять уровень одного ядра на 1 за валюту ядер.
    #[event_type(client)]
    UpgradeCore {
        side: WorldSide,
    },
    /// Поднять уровень закона, потратив сырые копии этого же закона. Если бой
    /// уже идёт, новая сборка применяется со следующего боя.
    #[event_type(client)]
    UpgradeLaw {
        law_template_id: LawTemplateId,
    },
    /// Поставить закон в слот ядра своей стороны. Текущий бой не пересчитывается.
    #[event_type(client)]
    SlotLaw {
        law_template_id: LawTemplateId,
        slot_index: i64,
    },
    /// Снять закон со слота. Снимает и все его мосты; текущий бой не
    /// пересчитывается.
    #[event_type(client)]
    UnslotLaw {
        law_template_id: LawTemplateId,
    },
    /// Создать мост между двумя законами из разных ядер. Текущий бой сохраняет
    /// свой снимок.
    #[event_type(client)]
    CreateLawBridge {
        first_law_template_id: LawTemplateId,
        second_law_template_id: LawTemplateId,
    },
    /// Снять мост между двумя законами. Текущий бой сохраняет свой снимок.
    #[event_type(client)]
    RemoveLawBridge {
        first_law_template_id: LawTemplateId,
        second_law_template_id: LawTemplateId,
    },
    /// Серверный маркер: игрок получил копии закона (дроп).
    NewLawCopies {
        law_template_id: LawTemplateId,
        amount: i64,
    },

    // Trigger/Effect Stones
    /// Вставить камень в сокет предмета. Камень адресуется своим шаблоном:
    /// у игрока не больше одного экземпляра каждого шаблона. Можно менять и в
    /// бою.
    #[event_type(client)]
    InsertStone {
        template_id: StoneTemplateId,
        item_type: ItemType,
        socket: StoneSocketSlot,
    },
    /// Вынуть камень из сокета. Камень возвращается в инвентарь без потерь.
    /// Можно менять и в бою.
    #[event_type(client)]
    RemoveStone {
        template_id: StoneTemplateId,
    },
    /// Поднять камень на уровень за сырые копии. Игрок называет камень, сервер
    /// сам списывает нужное число копий по лестнице из конфига. Триггеры и
    /// эффекты качаются раздельно. Можно качать и в бою.
    #[event_type(client)]
    UpgradeStone {
        template_id: StoneTemplateId,
    },
    /// Быстро надеть в предмет лучшие свободные камни: один Trigger и два
    /// Effect — или столько, сколько сокетов открыто. Закрытые и уже занятые
    /// сокеты пропускаются, камни из других предметов не трогаются, «лучший»
    /// считается сначала по тиру, потом по уровню. Можно менять и в бою.
    #[event_type(client)]
    QuickEquipStones {
        item_type: ItemType,
    },
    /// Прокачать все Trigger-камни, которым хватает сырых копий, за один вызов —
    /// столько уровней подряд, сколько позволяет лестница. Камни в сокетах и в
    /// инвентаре обрабатываются одинаково. Можно качать и в бою.
    ///
    /// Каталоги разделены на два события, потому что кнопка на экране качает ту
    /// вкладку, которая открыта, а не обе сразу.
    #[event_type(client)]
    UpgradeAllTriggerStones {},

    /// То же самое для Effect-камней. См. `UpgradeAllTriggerStones`.
    #[event_type(client)]
    UpgradeAllEffectStones {},

    /// Что именно подняла прокачка камней: id шаблона -> (уровень до, после).
    /// Как `UpgradedAbilities` — фронт показывает по нему окно результата, а
    /// квесты читают прогресс. Пустым не отправляется.
    UpgradedStones {
        upgraded_stones: UpgradedStonesMap,
    },
    /// Сервер выдал новые сырые копии камней (ВРЕМЕННО — с открытия сундука,
    /// см. `configs::stones::StoneDropSettings`). Каждый элемент — одна копия;
    /// повторы допустимы и считаются штуками.
    PlayerNewStones {
        trigger_stones: Vec<StoneTemplateId>,
        effect_stones: Vec<StoneTemplateId>,
    },

    // Progress Pass
    #[event_type(client)]
    ClaimProgressPassFreeReward {
        tier: u32,
    },

    #[event_type(client)]
    ClaimProgressPassPaidReward {
        tier: u32,
    },

    #[event_type(client)]
    ClaimAllProgressPassRewards {
        is_paid: bool,
    },

    // User Rating
    /// User rated the game (1–5) or declined to rate (rating = None).
    #[event_type(client)]
    UserRating {
        rating: Option<i8>,
    },

    /// Server tells the client to display the rate-us prompt.
    /// Emitted whenever `current_chapter_level >= game_settings.rate_us_chapter`
    /// and `character.rate_us_shown` is still false. Re-emitted on every new
    /// session start until the client acknowledges with `RateUsShown`.
    ShowRateUs {},

    /// Client confirms the rate-us prompt was displayed.
    /// Flips `character.rate_us_shown` to true so the server stops emitting.
    #[event_type(client)]
    RateUsShown {},

    /// Client reports the rate-us star selection (1–5).
    #[event_type(client)]
    RateUs {
        stars: i32,
    },

    // Error
    Error {
        code: String,
        message: String,
    },

    #[event_type(client)]
    CustomEvent {
        event_type: String,
        data: CustomEventData,
    },

    /// Server-only: a multi-cell run passes its next cell. Keeps the runner's
    /// coordinates ticking cell-by-cell during a single `StartMove` so
    /// opponents target the cell he is actually passing, not the run's
    /// destination. Scheduled by `handle_start_move`; appended at the enum
    /// tail to keep postcard variant tags of older events stable.
    MoveProgress {
        entity_id: Uuid,
        to: Coordinates,
    },

    /// Temporarily pauses the matching active fight while the client downloads
    /// required visual content, or a completed fight while it preloads the next
    /// campaign location. Kept at the enum tail so postcard variant tags of
    /// existing events remain stable.
    #[event_type(client)]
    SetFightContentLoading {
        fight_id: Uuid,
        loading: bool,
    },

    /// Claims every unclaimed Daily and Weekly entitlement for one rating as
    /// a single standard bundle group. Duplicate requests are a no-op.
    /// Appended at the enum tail to preserve postcard tags of existing events.
    #[event_type(client)]
    ClaimRatingRewards {
        rating_type: essences::ratings::RatingType,
    },

    /// Server-only projection event used by cron wake-ups to refresh one
    /// rating's authoritative notification flags on a connected client.
    /// Appended at the enum tail to preserve postcard tags of existing events.
    SetRatingRewardAvailability {
        availability: essences::ratings::RatingRewardAvailability,
    },

    // Артефакты. Все пять событий добавлены в хвост enum, чтобы не сдвинуть
    // postcard-теги уже существующих.
    /// Надеть артефакт. Одновременно надет ровно один: событие заменяет
    /// предыдущий, снимая только его World Law. Владение и бонус за владение не
    /// меняются. Можно менять в бою.
    #[event_type(client)]
    EquipArtifact {
        template_id: ArtifactTemplateId,
    },
    /// Вставить камень артефакта в один из шести сокетов. Сокет, который камень
    /// принимает, задан его шаблоном; чужой сокет отклоняется. Можно менять в бою.
    #[event_type(client)]
    InsertArtifactStone {
        template_id: ArtifactStoneTemplateId,
        socket: ArtifactSocketSlot,
    },
    /// Вынуть камень артефакта из сокета. Камень остаётся в коллекции с
    /// уровнем и копиями. Можно менять в бою.
    #[event_type(client)]
    RemoveArtifactStone {
        template_id: ArtifactStoneTemplateId,
    },
    /// Поднять камень артефакта на уровень за сырые копии. Правило не меняется,
    /// растёт только величина. Можно менять в бою.
    #[event_type(client)]
    UpgradeArtifactStone {
        template_id: ArtifactStoneTemplateId,
    },
    /// Сервер выдал артефакты и/или камни артефакта. Первая копия создаёт
    /// предмет первого уровня; каждый дубликат только банкуется сырой копией,
    /// в том числе на максимальном уровне. Уровни меняют отдельные клиентские
    /// события улучшения.
    PlayerNewArtifacts {
        artifacts: Vec<ArtifactTemplateId>,
        artifact_stones: Vec<ArtifactStoneTemplateId>,
    },
    /// Запустить эффект-камень от имени артефакта — серверное событие, клиент
    /// его не шлёт.
    ///
    /// Существует ради одного правила: `FA-05 Staggered Entrance` разносит свои
    /// пять эффектов по полсекунды. Взвод в v0.2 — прямая запись в атрибут, а не
    /// событие, поэтому отложить сам эффект нечем; откладывается весь запуск
    /// целиком, и отложенный запуск ничем не отличается от обычного, кроме
    /// момента. Боевые показания перечитываются на исполнении: ближайший враг
    /// через полсекунды может быть другим. Если боя уже нет — событие ничего не
    /// делает.
    FireArtifactEffect {
        /// Боец, чей артефакт запускает эффект: локальный герой, союзник по
        /// party или PvP-соперник. Показания боя перечитываются от его имени.
        owner_id: EntityId,
        effect_template_id: StoneTemplateId,
        effect_level: i64,
        /// Доля силы правила, посчитанная на флипе. В десятитысячных, потому что
        /// enum событий выводит `Eq`, а `f64` его не реализует: `7000` — это 0,7.
        share_permyriad: i64,
        /// Камень-аспект, чьё правило отложило этот прогон. Нужен, чтобы
        /// отложенный запуск попал в ту же строку разбора боя, что и мгновенный.
        artifact_stone_id: ArtifactStoneTemplateId,
    },
    /// Назначить камню правой колонки закон, на который он действует, или снять
    /// назначение (`law_template_id: None`). Можно менять в бою.
    ///
    /// Адресом служит один закон, и этого хватает в том числе камням про мосты:
    /// у моста нет своего идентификатора, но в v0.2 у закона ровно один партнёр,
    /// поэтому «мост, в котором состоит закон X» — однозначный адрес. Отсюда
    /// следствие: если игрок разберёт мост выбранного закона и построит ему
    /// другой, камень переедет на новый мост сам.
    #[event_type(client)]
    SetArtifactStoneLawTarget {
        template_id: ArtifactStoneTemplateId,
        law_template_id: Option<LawTemplateId>,
    },

    /// Заполняет свободные открытые сокеты ОДНОЙ способности лучшими камнями из
    /// коллекции. Закрытые и уже занятые сокеты пропускаются, правила приёма те
    /// же, что у ручной установки: совместимость по тегам, одно семейство на
    /// один Imprint, один шаблон на способность. Сокет, которому нечего
    /// предложить, остаётся пустым без ошибки.
    /// Добавлено в хвост enum, чтобы не сдвинуть postcard-теги существующих.
    #[event_type(client)]
    QuickEquipAbilityStones {
        ability_id: AbilityId,
    },

    /// Поднимает уровень каждого камня способности, которому хватает сырых
    /// копий, — столько уровней подряд, сколько позволяет лестница. Камни в
    /// сокетах и в коллекции обрабатываются одинаково; камень, который не может
    /// оплатить следующий уровень, пропускается, а не роняет весь вызов.
    /// Добавлено в хвост enum, чтобы не сдвинуть postcard-теги существующих.
    #[event_type(client)]
    UpgradeAllAbilityStones {},

    /// Что именно подняла массовая прокачка камней способностей: id шаблона ->
    /// (уровень до, после). Как `UpgradedStones` — фронт показывает по нему окно
    /// результата. Пустым не отправляется.
    /// Добавлено в хвост enum, чтобы не сдвинуть postcard-теги существующих.
    UpgradedAbilityStones {
        upgraded_ability_stones: UpgradedAbilityStonesMap,
    },

    /// Raises one owned artifact by one level and atomically spends the exact
    /// raw-copy cost configured for that next level. Appended at the enum tail
    /// to preserve postcard tags of every existing event.
    #[event_type(client)]
    UpgradeArtifact {
        template_id: ArtifactTemplateId,
    },

    /// Сбрасывает уровни ОБОИХ ядер в 0 и возвращает всю валюту, потраченную
    /// на их подъём (точная сумма `core_level_cost` по обеим лестницам).
    /// Уровень 0 не даёт слотов законов, поэтому все законы снимаются со
    /// слотов путём `UnslotLaw`: мосты уходят, камни артефакта забывают
    /// выбранные законы. Сами законы, их уровни и копии не трогаются.
    /// Добавлено в хвост enum ради стабильности postcard-тегов.
    #[event_type(client)]
    ResetCores {},

    /// Выбор мира (Real/Fantasy), с которого игрок стартует арена-бои — и как
    /// атакующий, и как снапшот-оппонент в чужих боях. Валиден только при
    /// разлоченном флипе. Добавлено в хвост enum ради стабильности
    /// postcard-тегов.
    #[event_type(client)]
    SetArenaWorldSide {
        side: WorldSide,
    },
}

impl OverlordEvent {
    /// Provenance of a trigger-eligible combat **outcome**, or `None` when this
    /// event is not one.
    ///
    /// The outcome vocabulary is exactly what a trigger can subscribe to:
    /// `Damage` (an attack, a crit — the crit flag rides in `damage_data`),
    /// `Heal`, `Evasion` (a dodge), `CounterAttack`, `Multicast` and
    /// `EntityDeath` (a mob death). Everything else answers `None`, including
    /// the *carriers* of [`OverlordEvent::carried_origin`]: a trigger fires on
    /// the damage a cast produced, never on the cast itself. `GlobalFlip`
    /// answers `None` too — a flip is a state transition, not a combat action,
    /// and must never read as Core.
    pub fn combat_origin(&self) -> Option<CombatEventOrigin> {
        match self {
            Self::Damage { origin, .. }
            | Self::Heal { origin, .. }
            | Self::Evasion { origin, .. }
            | Self::CounterAttack { origin, .. }
            | Self::Multicast { origin, .. }
            | Self::EntityDeath { origin, .. } => Some(*origin),
            _ => None,
        }
    }

    /// Whether a trigger may react to this event. False for every non-combat
    /// event, for every carrier, and for anything a modifier produced.
    pub fn is_core_combat_event(&self) -> bool {
        self.combat_origin().is_some_and(CombatEventOrigin::is_core)
    }

    /// Provenance this event hands down to whatever it produces — the outcomes
    /// above *plus* the carriers that forward a producer's work.
    ///
    /// A modifier's work does not reach its outcome in one hop: a stone that
    /// grants an extra swing emits a cast, the cast schedules a projectile, the
    /// projectile lands damage. Each link therefore carries provenance, so the
    /// mark survives every hop, including the delayed ones that leave through
    /// [`crate::fight::FightClock`]. The carriers are the ability-cast chain
    /// (`StartCastAbility` / `StartedCastAbility` / `CastAbility`), the
    /// projectile chain (`StartCastProjectile` / `StartedCastProjectile` /
    /// `CastProjectile`) and effect dispatch (`EntityApplyEffect` / `CastEffect`
    /// / `CastEffectFromEvent`).
    ///
    /// `CastEffectFromEvent` derives instead of storing: it already boxes the
    /// event the subscription fired on, which is the exact producer to inherit
    /// from. This is what keeps the "Proc damage → subscribed effect → heal"
    /// hop from resetting to Core, at any depth.
    ///
    /// Two things are deliberately *not* carriers. A combatant spawned by a
    /// modifier fights with its own Core actions — it is a real fighter whose
    /// rate is bounded by its own cadence, not an instant re-entry. And
    /// `FightProgress`, the global heartbeat, drives every entity's turn, so it
    /// belongs to no single producer.
    pub fn carried_origin(&self) -> Option<CombatEventOrigin> {
        match self {
            Self::CastEffectFromEvent { caller_event, .. } => caller_event.carried_origin(),
            Self::StartCastAbility { origin, .. }
            | Self::StartedCastAbility { origin, .. }
            | Self::CastAbility { origin, .. }
            | Self::StartCastProjectile { origin, .. }
            | Self::StartedCastProjectile { origin, .. }
            | Self::CastProjectile { origin, .. }
            | Self::EntityApplyEffect { origin, .. }
            | Self::CastEffect { origin, .. } => Some(*origin),
            _ => self.combat_origin(),
        }
    }

    /// Restamps provenance on any event that carries it — outcome or carrier.
    /// Returns `false` (and changes nothing) for events that carry none,
    /// `CastEffectFromEvent` included: it derives from its boxed caller and has
    /// no field of its own.
    ///
    /// This is how a modifier's output is marked without every emit site
    /// knowing about modifiers: the producing scope restamps whatever the fight
    /// primitives emitted.
    pub fn set_origin(&mut self, new_origin: CombatEventOrigin) -> bool {
        match self {
            Self::Damage { origin, .. }
            | Self::Heal { origin, .. }
            | Self::Evasion { origin, .. }
            | Self::CounterAttack { origin, .. }
            | Self::Multicast { origin, .. }
            | Self::EntityDeath { origin, .. }
            | Self::StartCastAbility { origin, .. }
            | Self::StartedCastAbility { origin, .. }
            | Self::CastAbility { origin, .. }
            | Self::StartCastProjectile { origin, .. }
            | Self::StartedCastProjectile { origin, .. }
            | Self::CastProjectile { origin, .. }
            | Self::EntityApplyEffect { origin, .. }
            | Self::CastEffect { origin, .. } => {
                *origin = new_origin;
                true
            }
            _ => false,
        }
    }

    /// Owned form of [`OverlordEvent::set_origin`].
    pub fn with_origin(mut self, new_origin: CombatEventOrigin) -> Self {
        self.set_origin(new_origin);
        self
    }

    /// Whether this event already carries provenance, i.e. whether
    /// [`OverlordEvent::set_origin`] can mark it. A non-Core producer scope may
    /// only emit events for which this holds — see
    /// [`crate::mechanics::fight::OriginSink`].
    pub fn carries_origin(&self) -> bool {
        self.carried_origin().is_some()
    }
}

#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, JsonSchema, Tsify)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub enum PrepareFightType {
    PVEFight,
    PVPFight {
        fight_id: FightTemplateId,
        pvp_state: Box<PVPState>,
    },
    RetryBossFight,
    DungeonFight {
        dungeon_id: DungeonTemplateId,
        difficulty: i64,
    },
    ForfeitDungeonFight,
    SingleFight {
        fight_templated_id: FightTemplateId,
    },
}

#[derive(Clone, Debug, Serialize, Deserialize, PartialEq, Eq, JsonSchema, Tsify)]
#[tsify(from_wasm_abi, into_wasm_abi)]
pub enum Cheat {
    PauseCombat,
    UnpauseCombat,
    GodModeOn,
    GodModeOff,
    GetRich,
    ClearInventory,
    ClearSlot {
        item_id: Uuid,
    },
    GetAllSpells,
    SetChapter {
        chapter: i64,
    },
    StartFight {
        templated_id: FightTemplateId,
    },
    SpawnEntity {
        entity_id: EntityTemplateId,
        x: i64,
        y: i64,
        team: EntityTeam,
        attributes: Vec<(String, i64)>,
    },
    WearItems {
        items_ids: Vec<ItemTemplateId>,
    },
    EquipSkin {
        skin_id: SkinId,
    },
    UnequipSkin {
        skin_id: SkinId,
    },
    NewLevel {
        level: i64,
    },
    Script {
        script_id: CheatScriptId,
    },
    /// Reopens the latest Daily Arena and PvE rating reward entitlements.
    /// Appended at the enum tail to preserve postcard tags of existing cheats.
    MakeDailyRatingRewardsReady,
    /// Reopens the latest Weekly Arena and PvE rating reward entitlements.
    /// Appended at the enum tail to preserve postcard tags of existing cheats.
    MakeWeeklyRatingRewardsReady,
    /// Grants one copy of every Trigger and Effect Stone in the catalog.
    /// A template already owned gains a raw copy instead of a second instance,
    /// so running it repeatedly feeds upgrades.
    /// Appended at the enum tail to preserve postcard tags of existing cheats.
    GetAllStones,
    /// Grants one raw copy of every ability support stone in the catalog.
    /// Ownership is a per-template stack, so running it repeatedly banks the
    /// copies an upgrade costs — the only other source is the chapter faucet,
    /// which hands out one copy per `chapter_reward_period` cleared chapters.
    /// Appended at the enum tail to preserve postcard tags of existing cheats.
    GetAllAbilityStones,
    /// Grants one copy of every pet in the catalog. A pet already owned gains a
    /// shard instead of a second entry, so running it repeatedly feeds upgrades
    /// exactly as the gacha does.
    /// Appended at the enum tail to preserve postcard tags of existing cheats.
    GetAllPets,
    /// Grants one copy of every artifact and every artifact stone in the
    /// catalog through the normal grant path, so duplicates bank upgrade
    /// copies exactly as a repeat bundle/drop would.
    /// Appended at the enum tail to preserve postcard tags of existing cheats.
    GetAllArtifacts,
    /// Grants every catalog law as an owned level-1 law (already-owned laws
    /// are untouched — the cheat unlocks, copy income levels).
    /// Appended at the enum tail to preserve postcard tags of existing cheats.
    GetAllLaws,
    /// Rolls `batch_size` items through the normal case pipeline with the
    /// chest-level batch cap lifted — any size is accepted — but PAID for out
    /// of the character's own chest keys, so it fails on an empty wallet
    /// exactly as a manual open does. With auto-chest off it then applies the
    /// client's own keep/sell rule over the batch: per logical slot only the
    /// strongest roll survives.
    /// Appended at the enum tail to preserve postcard tags of existing cheats.
    OpenItemCase {
        batch_size: i64,
    },
    /// [`Cheat::OpenItemCase`] with the key price lifted as well: the keys the
    /// open spends are granted by the cheat, so the wallet nets zero and a
    /// character with no keys can still roll. Everything else — the batch cap,
    /// the roll, the keep/sell pass — is identical.
    /// Appended at the enum tail to preserve postcard tags of existing cheats.
    OpenItemCaseFree {
        batch_size: i64,
    },
}

#[derive(Clone, Debug, Default, Serialize, Deserialize, PartialEq, Eq, JsonSchema)]
pub struct CustomEventData(pub BTreeMap<String, i64>);

impl CustomEventData {
    pub fn add(&mut self, key: &str, delta: i64) {
        let value = self
            .0
            .entry(key.to_owned())
            .and_modify(|x| *x += delta)
            .or_insert(delta);
        if *value == 0 {
            self.0.remove(key);
        }
    }
}

impl From<EssencesCustomEventData> for CustomEventData {
    fn from(value: EssencesCustomEventData) -> Self {
        CustomEventData(value.0)
    }
}

impl From<CustomEventData> for EssencesCustomEventData {
    fn from(value: CustomEventData) -> Self {
        EssencesCustomEventData(value.0)
    }
}

#[cfg(test)]
mod combat_origin_tests {
    use super::*;

    fn id() -> Uuid {
        Uuid::from_u128(1)
    }

    fn damage(origin: CombatEventOrigin) -> OverlordEvent {
        OverlordEvent::Damage {
            by_entity_id: Some(id()),
            entity_id: id(),
            damage: 5,
            damage_data: CustomEventData::default(),
            origin,
            source: essences::fight_breakdown::CombatSource::Other,
        }
    }

    /// The whole combat-outcome vocabulary carries provenance — a trigger asks
    /// one question of any of them.
    #[test]
    fn every_marked_combat_event_reports_its_origin() {
        let marked = [
            damage(CombatEventOrigin::Core),
            OverlordEvent::Heal {
                entity_id: id(),
                heal: 1,
                origin: CombatEventOrigin::Core,
                by_entity_id: None,
                source: essences::fight_breakdown::CombatSource::Other,
            },
            OverlordEvent::Evasion {
                entity_id: id(),
                origin: CombatEventOrigin::Core,
            },
            OverlordEvent::CounterAttack {
                by_entity_id: id(),
                to_entity_id: id(),
                duration_ticks: 1,
                origin: CombatEventOrigin::Core,
            },
            OverlordEvent::Multicast {
                entity_id: id(),
                amount: 1,
                origin: CombatEventOrigin::Core,
            },
            OverlordEvent::EntityDeath {
                entity_id: id(),
                reward: Vec::new(),
                origin: CombatEventOrigin::Core,
            },
        ];

        for event in marked {
            assert_eq!(
                event.combat_origin(),
                Some(CombatEventOrigin::Core),
                "{event}"
            );
            assert!(event.is_core_combat_event(), "{event}");
            let procced = event.with_origin(CombatEventOrigin::Proc);
            assert_eq!(procced.combat_origin(), Some(CombatEventOrigin::Proc));
            assert!(!procced.is_core_combat_event());
        }
    }

    /// A flip is a state transition, not a combat action. It must never read as
    /// Core, or a "flip → trigger → effect → flip" loop becomes expressible.
    #[test]
    fn a_flip_is_not_a_core_event() {
        let flip = OverlordEvent::GlobalFlip {
            entity_id: id(),
            source: FlipProgressSource::TriggerFired,
            from_side: WorldSide::Fantasy,
            to_side: WorldSide::Real,
            revision: 1,
        };

        assert_eq!(flip.combat_origin(), None);
        assert!(!flip.is_core_combat_event());
    }

    /// Restamping is a no-op for events that carry no origin — including the
    /// flip, which stays unmarked even inside a Proc cascade.
    #[test]
    fn unmarked_events_cannot_be_stamped() {
        let mut flip = OverlordEvent::GlobalFlip {
            entity_id: id(),
            source: FlipProgressSource::TriggerFired,
            from_side: WorldSide::Fantasy,
            to_side: WorldSide::Real,
            revision: 1,
        };
        assert!(!flip.set_origin(CombatEventOrigin::Proc));
        assert_eq!(flip.combat_origin(), None);

        let mut player_death = OverlordEvent::PlayerDeath {};
        assert!(!player_death.set_origin(CombatEventOrigin::Proc));

        let mut stage = OverlordEvent::StageCleared {};
        assert!(!stage.set_origin(CombatEventOrigin::Proc));
        assert!(!stage.is_core_combat_event());
    }

    /// Provenance is the only thing restamping touches.
    #[test]
    fn restamping_preserves_the_payload() {
        let core = damage(CombatEventOrigin::Core);
        let procced = core.clone().with_origin(CombatEventOrigin::Proc);

        let (
            OverlordEvent::Damage {
                by_entity_id: core_by,
                entity_id: core_entity,
                damage: core_damage,
                damage_data: core_data,
                ..
            },
            OverlordEvent::Damage {
                by_entity_id: proc_by,
                entity_id: proc_entity,
                damage: proc_damage,
                damage_data: proc_data,
                ..
            },
        ) = (core, procced)
        else {
            panic!("both events are Damage");
        };

        assert_eq!(core_by, proc_by);
        assert_eq!(core_entity, proc_entity);
        assert_eq!(core_damage, proc_damage);
        assert_eq!(core_data, proc_data);
    }
}