manabrew_engine/game_loop/

phase_handler.rs

use super::*;

impl GameLoop {
    pub(crate) fn run_turn_state_machine(
        &mut self,
        game: &mut GameState,
        agents: &mut [Box<dyn PlayerAgent>],
    ) {
        let _perf_scope =
            crate::perf::ParamsLookupScopeGuard::enter(crate::perf::ParamsLookupScope::Phase);
        // Run BeginTurn replacement effects before the turn begins.
        let active = game.active_player();
        {
            use crate::replacement::replacement_handler::{apply_replacements, ReplacementEvent};
            use crate::replacement::ReplacementResult;
            let mut event = ReplacementEvent::BeginTurn { player: active };
            let result = apply_replacements(game, &mut event);
            if result == ReplacementResult::Skipped || result == ReplacementResult::Replaced {
                return;
            }
        }

        // Fire TurnBegin trigger at the start of each turn.
        let active = game.active_player();
        crate::player::expire_until_your_next_turn_keywords(game, active);
        self.trigger_handler
            .handle_player_defined_del_triggers(active);
        self.trigger_handler.run_trigger(
            TriggerType::TurnBegin,
            RunParams {
                player: Some(active),
                ..Default::default()
            },
            false,
        );

        let mut state = TurnMachineState::Untap;
        while !game.game_over && state != TurnMachineState::Done {
            if self.is_aborted() {
                game.game_over = true;
                break;
            }
            // EndTurn (issue #22): if end_turn_requested, skip directly to cleanup.
            if game.end_turn_requested
                && state != TurnMachineState::Cleanup
                && state != TurnMachineState::Done
            {
                game.end_turn_requested = false;
                self.combat.clear_with_cards(&mut game.cards);
                state = TurnMachineState::Cleanup;
                continue;
            }
            state = match state {
                TurnMachineState::Untap => {
                    // SkipPhase: skip untap if flag set
                    let active = game.active_player();
                    if game.player(active).skip_next_untap {
                        game.player_clear_skip_untap(active);
                        TurnMachineState::Upkeep
                    } else {
                        self.apply_turn_event(
                            game,
                            agents,
                            TurnEvent::EnterPhase {
                                phase: PhaseType::Untap,
                                emit_phase_trigger: false,
                            },
                        );
                        self.apply_turn_event(game, agents, TurnEvent::UntapStep);
                        TurnMachineState::Upkeep
                    }
                }
                TurnMachineState::Upkeep => {
                    self.apply_turn_event(
                        game,
                        agents,
                        TurnEvent::EnterPhase {
                            phase: PhaseType::Upkeep,
                            emit_phase_trigger: true,
                        },
                    );
                    self.apply_turn_event(
                        game,
                        agents,
                        TurnEvent::PriorityWindow {
                            is_main_phase: false,
                        },
                    );
                    self.clear_came_under_control_since_last_upkeep(game);
                    // Cumulative upkeep is now handled as a Phase trigger
                    // (generated by generate_keyword_triggers from the keyword),
                    // so it fires alongside other upkeep triggers (e.g. Deep Spawn)
                    // and is ordered by the player. No separate procedural call needed.
                    TurnMachineState::Draw
                }
                TurnMachineState::Draw => {
                    // SkipPhase: skip draw if flag set
                    let active = game.active_player();
                    if game.player(active).skip_next_draw
                        || crate::replacement::replacement_handler::would_phase_be_skipped(
                            game,
                            active,
                            PhaseType::Draw,
                        )
                    {
                        game.player_clear_skip_draw(active);
                        TurnMachineState::Main1
                    } else {
                        // Java parity: Java still advances into the Draw phase and fires the
                        // phase-change event on turn 1 in a 2-player game, but then skips the
                        // draw-step actions, phase triggers, and priority window.
                        let skip_draw_phase = game.turn.turn_number == 1 && game.players.len() == 2;
                        if skip_draw_phase {
                            self.apply_turn_event(
                                game,
                                agents,
                                TurnEvent::EnterPhase {
                                    phase: PhaseType::Draw,
                                    emit_phase_trigger: false,
                                },
                            );
                            TurnMachineState::Main1
                        } else {
                            self.apply_turn_event(
                                game,
                                agents,
                                TurnEvent::EnterPhase {
                                    phase: PhaseType::Draw,
                                    emit_phase_trigger: true,
                                },
                            );
                            self.apply_turn_event(game, agents, TurnEvent::DrawStep);
                            self.apply_turn_event(
                                game,
                                agents,
                                TurnEvent::PriorityWindow {
                                    is_main_phase: false,
                                },
                            );
                            TurnMachineState::Main1
                        }
                    }
                }
                TurnMachineState::Main1 => {
                    self.apply_turn_event(
                        game,
                        agents,
                        TurnEvent::EnterPhase {
                            phase: PhaseType::Main1,
                            emit_phase_trigger: true,
                        },
                    );
                    if game
                        .cards_in_zone(ZoneType::Battlefield, game.active_player())
                        .iter()
                        .any(|&card_id| {
                            game.card(card_id)
                                .type_line
                                .subtypes
                                .iter()
                                .any(|s| s.eq_ignore_ascii_case("Attraction"))
                        })
                    {
                        crate::ability::effects::roll_dice_effect::roll_to_visit_attractions(
                            game,
                            &mut self.trigger_handler,
                            &mut *self.game_rng,
                            agents,
                            &mut self.mana_pools,
                            game.active_player(),
                        );
                    }
                    self.apply_turn_event(
                        game,
                        agents,
                        TurnEvent::PriorityWindow {
                            is_main_phase: true,
                        },
                    );
                    TurnMachineState::Combat
                }
                TurnMachineState::Combat => {
                    // SkipPhase: skip combat if flag set
                    let active = game.active_player();
                    if game.player(active).skip_next_combat {
                        game.player_clear_skip_combat(active);
                        TurnMachineState::Main2
                    } else {
                        self.apply_turn_event(game, agents, TurnEvent::CombatStep);
                        // Extra combat phases (issue #22, AddPhase effect)
                        if game.extra_combat_phases > 0 {
                            game.extra_combat_phases -= 1;
                            TurnMachineState::Combat // loop back for another combat
                        } else {
                            TurnMachineState::Main2
                        }
                    }
                }
                TurnMachineState::Main2 => {
                    self.apply_turn_event(
                        game,
                        agents,
                        TurnEvent::EnterPhase {
                            phase: PhaseType::Main2,
                            emit_phase_trigger: true,
                        },
                    );
                    self.apply_turn_event(
                        game,
                        agents,
                        TurnEvent::PriorityWindow {
                            is_main_phase: true,
                        },
                    );
                    TurnMachineState::EndOfTurn
                }
                TurnMachineState::EndOfTurn => {
                    self.apply_turn_event(
                        game,
                        agents,
                        TurnEvent::EnterPhase {
                            phase: PhaseType::EndOfTurn,
                            emit_phase_trigger: true,
                        },
                    );
                    self.apply_turn_event(
                        game,
                        agents,
                        TurnEvent::PriorityWindow {
                            is_main_phase: false,
                        },
                    );
                    TurnMachineState::Cleanup
                }
                TurnMachineState::Cleanup => {
                    self.apply_turn_event(
                        game,
                        agents,
                        TurnEvent::EnterPhase {
                            phase: PhaseType::Cleanup,
                            emit_phase_trigger: false,
                        },
                    );
                    self.apply_turn_event(game, agents, TurnEvent::CleanupStep);
                    self.apply_turn_event(game, agents, TurnEvent::AdvanceTurn);
                    TurnMachineState::Done
                }
                TurnMachineState::Done => TurnMachineState::Done,
            };
        }
    }

    fn apply_turn_event(
        &mut self,
        game: &mut GameState,
        agents: &mut [Box<dyn PlayerAgent>],
        event: TurnEvent,
    ) {
        if game.game_over {
            return;
        }
        match event {
            TurnEvent::EnterPhase {
                phase,
                emit_phase_trigger,
            } => {
                // Clear undo stack on phase change (can't undo across phases).
                game.stack.clear_undo_stack();

                // Run BeginPhase replacement effects before entering the phase.
                {
                    use crate::replacement::replacement_handler::{
                        apply_replacements, ReplacementEvent,
                    };
                    use crate::replacement::ReplacementResult;
                    let active = game.active_player();
                    let mut event = ReplacementEvent::BeginPhase {
                        player: active,
                        phase,
                    };
                    let result = apply_replacements(game, &mut event);
                    if result == ReplacementResult::Skipped || result == ReplacementResult::Replaced
                    {
                        return;
                    }
                }

                // LKI: Snapshot battlefield state before phase transition.
                // Mirrors Java PhaseHandler line 1103: game.copyLastState().
                game.copy_last_state();
                self.set_phase(game, agents, phase);
                if emit_phase_trigger {
                    self.emit_phase_trigger(game, phase);
                }
                // Suspend: at the beginning of each upkeep, remove a time counter
                // from each suspended card in exile. If last counter removed, cast for free.
                if phase == PhaseType::Upkeep {
                    self.process_suspend_upkeep(game, agents);
                }
            }
            TurnEvent::PriorityWindow { is_main_phase } => {
                self.step_with_priority(game, agents, is_main_phase);
            }
            TurnEvent::UntapStep => {
                self.with_shared_state_mutation(game, agents, |this, game, agents| {
                    this.step_untap(game, agents);
                });
            }
            TurnEvent::DrawStep => {
                self.with_shared_state_mutation(game, agents, |this, game, agents| {
                    this.step_draw(game, agents);
                });
            }
            TurnEvent::CombatStep => {
                self.step_combat(game, agents);
            }
            TurnEvent::CleanupStep => {
                self.with_shared_state_mutation(game, agents, |this, game, agents| {
                    this.step_cleanup(game, agents);
                });
            }
            TurnEvent::AdvanceTurn => {
                self.with_shared_state_mutation(game, agents, |_this, game, _agents| {
                    // Rotate stack's turn-tracking (this_turn_cast → last_turn_cast).
                    game.stack.on_next_turn();
                    // Reset zone turn tracking for all zones.
                    game.reset_zone_turn_tracking();
                    game.reset_card_turn_tracking();
                    let player_order = game.player_order.clone();
                    if let Some((player, _skip)) =
                        game.turn.advance_turn(&mut game.extra_turns, &player_order)
                    {
                        game.player_set_skip_untap(player);
                    }
                });
            }
        }
    }

    pub fn step_untap(&mut self, game: &mut GameState, agents: &mut [Box<dyn PlayerAgent>]) {
        let active = game.active_player();
        let cards_snapshot = game.cards.clone();

        // Delegate phasing to the phase module.
        crate::phase::untap::do_phasing(game, active);

        // Untap permanents — uses agent interaction for "may choose not to untap".
        let cards: Vec<crate::ids::CardId> =
            game.cards_in_zone(ZoneType::Battlefield, active).to_vec();
        for cid in cards {
            if game.card(cid).exerted {
                game.card_mut(cid).clear_exerted();
            } else {
                let optional_keyword =
                    "You may choose not to untap CARDNAME during your untap step.";
                let should_untap = if game.card(cid).has_keyword(optional_keyword) {
                    let question = format!("Untap {}?", game.card(cid).card_name);
                    let source_name = game.card(cid).card_name.clone();
                    agents[active.index()].choose_binary(
                        active,
                        &question,
                        crate::agent::BinaryChoiceKind::UntapOrLeaveTapped,
                        Some(true),
                        Some(cid),
                        None,
                    )
                } else {
                    true
                };
                if should_untap {
                    game.untap_during_untap_step(cid, active);
                }
            }
        }

        // Java parity: untap permanents on other players' battlefields that
        // have an UntapOtherPlayer static ability applying during the active
        // player's untap step, e.g. Bender's Waterskin.
        let other_battlefield_cards: Vec<_> = game
            .player_order
            .iter()
            .copied()
            .filter(|&pid| pid != active)
            .flat_map(|pid| {
                game.cards_in_zone(ZoneType::Battlefield, pid)
                    .iter()
                    .copied()
            })
            .collect();
        for cid in other_battlefield_cards {
            let card = game.card(cid);
            if !card.tapped {
                continue;
            }
            if crate::staticability::static_ability_untap_other_player::untap(
                &cards_snapshot,
                card,
                active,
            ) {
                game.untap_during_untap_step(cid, active);
            }
        }

        self.pool_mut(active).reset_pool();
    }

    pub fn step_draw(&mut self, game: &mut GameState, agents: &mut [Box<dyn PlayerAgent>]) {
        let active = game.active_player();
        // Skip draw on turn 1
        if game.turn.turn_number > 1 {
            use crate::replacement::replacement_handler::{
                apply_replacements_with_agents, ReplacementEvent,
            };
            use crate::replacement::ReplacementResult;

            // Dredge is now handled through the replacement effect system:
            // Dredge:N keywords generate a Draw replacement effect during card
            // assembly (card_factory_util::add_dredge_replacement). When the
            // draw fires ReplacementEvent::Draw inside player_draw_one_internal,
            // the replacement handler detects the Dredge replacement on the
            // graveyard card, calls confirm_replacement_effect (Optional$ True),
            // and executes the mill + return in replace_draw::execute.
            let mut draw_count = 1;
            let mut draw_cards_event = ReplacementEvent::DrawCards {
                player: active,
                count: draw_count,
            };
            let result = apply_replacements_with_agents(game, agents, &mut draw_cards_event);
            if result == ReplacementResult::Skipped || result == ReplacementResult::Replaced {
                return;
            }
            if let ReplacementEvent::DrawCards { count, .. } = draw_cards_event {
                draw_count = count;
            }

            for draw_index in 0..draw_count {
                if let Some(card_id) =
                    game.player_draw_one_internal(active, draw_index == 0, Some(agents))
                {
                    let drawn_snapshot = game.player(active).drawn_this_turn;
                    // Fire Drawn trigger for turn draw
                    self.trigger_handler.run_trigger(
                        TriggerType::Drawn,
                        RunParams {
                            card: Some(card_id),
                            player: Some(active),
                            drawn_this_turn_snapshot: Some(drawn_snapshot),
                            ..Default::default()
                        },
                        false,
                    );
                    // Match Drawn triggers immediately so Number$ N checks see
                    // the correct drawn count at fire time.
                    if self.trigger_handler.has_number_drawn_triggers(game) {
                        self.trigger_handler.flush_waiting_triggers(game);
                    }
                }
            }
        }
    }

    pub fn step_with_priority(
        &mut self,
        game: &mut GameState,
        agents: &mut [Box<dyn PlayerAgent>],
        is_main_phase: bool,
    ) {
        let _perf_scope =
            crate::perf::ParamsLookupScopeGuard::enter(crate::perf::ParamsLookupScope::Priority);
        self.game_log.log(
            GameLogEntryType::Info,
            2,
            format!(
                "Priority window opened ({}, stack depth: {})",
                if is_main_phase {
                    "main-phase speed"
                } else {
                    "instant speed only"
                },
                game.stack.len()
            ),
        );
        self.with_shared_state_mutation(game, agents, |_this, game, _agents| {
            game.turn.priority_player = game.active_player();
        });
        loop {
            if game.game_over {
                return;
            }

            // 1. Give players priority (process_triggers + SBA are handled
            //    inside priority_round at the top of each iteration, matching
            //    Java's checkStateBasedEffects() → addAllTriggeredAbilitiesToStack()
            //    before chooseSpellAbilityToPlay()).
            self.priority_round(game, agents, is_main_phase);

            if std::env::var("FORGE_STACK_TRACE").is_ok() {
                let names: Vec<String> = game
                    .stack
                    .iter()
                    .map(|entry| {
                        entry
                            .spell_ability
                            .source
                            .map(|cid| game.card(cid).card_name.clone())
                            .unwrap_or_else(|| "<effect>".to_string())
                    })
                    .collect();
                eprintln!(
                    "[stack-trace] AFTER priority_round phase={:?} active={:?} priority={:?} depth={} {:?}",
                    game.turn.phase,
                    game.active_player(),
                    game.turn.priority_player,
                    game.stack.len(),
                    names
                );
            }

            if game.game_over {
                return;
            }

            // 3. If stack is empty after everyone passed, the phase ends
            if game.stack.is_empty() {
                break;
            }

            // 4. Resolve top of stack (resolve_stack resolves one and gives priority)
            self.with_shared_state_mutation(game, agents, |this, game, agents| {
                this.resolve_stack(game, agents);
            });
        }
    }
    pub fn step_main_phase(&mut self, game: &mut GameState, agents: &mut [Box<dyn PlayerAgent>]) {
        self.step_with_priority(game, agents, true);
    }

    pub fn step_cleanup(&mut self, game: &mut GameState, agents: &mut [Box<dyn PlayerAgent>]) {
        // Rule 514.3a: If state-based actions are performed or triggers fire
        // during Cleanup, players get priority and then a new Cleanup step
        // begins. This mirrors Java's bRepeatCleanup / givePriorityToPlayer
        // loop in PhaseHandler.java.
        let mut is_repeat = false;
        loop {
            // On repeat iterations, re-notify the phase so that parity agents
            // see the same snapshot Java emits when it re-enters onPhaseBegin(CLEANUP).
            if is_repeat {
                self.notify_phase_changed(game, agents);
            }

            let active = game.active_player();

            // Rule 514.1: Discard down to max hand size.
            // Reliquary Tower etc. set `unlimited_hand_size = true` via
            // `SetMaxHandSize$ Unlimited` and skip the discard entirely.
            let hand_size = game.zone(ZoneType::Hand, active).len() as i32;
            let max = game.player(active).max_hand_size;
            let unlimited = game.player(active).unlimited_hand_size;
            if !unlimited && hand_size > max {
                let to_discard = (hand_size - max) as usize;
                let hand: Vec<CardId> = game.cards_in_zone(ZoneType::Hand, active).to_vec();
                agents[active.index()].snapshot_state(game, &self.mana_pools);
                self.game_log.log(
                    GameLogEntryType::PriorityWaiting,
                    2,
                    format!(
                        "Waiting for {} discard decision (choose {})",
                        game.player(active).name,
                        to_discard
                    ),
                );
                let chosen = agents[active.index()].choose_discard(active, &hand, to_discard);
                self.game_log.log(
                    GameLogEntryType::PriorityResponse,
                    2,
                    format!(
                        "{} selected {} card(s) to discard",
                        game.player(active).name,
                        chosen.len().min(to_discard)
                    ),
                );
                for card_id in chosen.iter().take(to_discard) {
                    if game.card(*card_id).zone == ZoneType::Hand {
                        game.discard_card(
                            *card_id,
                            active,
                            None,
                            Some(agents),
                            &mut self.trigger_handler,
                        );
                    }
                }
            }

            // Rule 514.2: Remove damage from permanents and end "until end of
            // turn" / "this turn" effects.  Java does this inside
            // onPhaseBegin(CLEANUP) every iteration.
            self.cleanup_damage_and_eot(game);

            self.trigger_handler.flush_waiting_triggers(game);
            if game.stack.is_empty() && self.trigger_handler.pre_matched_trigger_count() == 0 {
                break;
            }
            self.step_with_priority(game, agents, false);
            is_repeat = true;
        }

        // --- One-time end-of-turn resets (after the cleanup loop) ---

        // Reset fog flag (issue #22: Fog effect lasts until end of turn).
        game.prevent_all_combat_damage = false;

        // Reset end-of-turn flags (issue #22).
        game.end_turn_requested = false;
        game.end_combat_requested = false;
        game.extra_combat_phases = 0;
        game.stack.reset_max_distinct_sources();

        // Empty mana pool at end of turn (cleanup step), per Magic rules.
        let active = game.active_player();
        self.pool_mut(active).reset_pool();
        self.trigger_handler.clear_this_turn_delayed_trigger();
    }

    /// Rule 514.2: Remove damage from permanents, expire "until end of turn"
    /// effects, and clean up temporary state. Called every cleanup iteration
    /// (including repeats per rule 514.3a), mirroring Java's onPhaseBegin(CLEANUP).
    fn cleanup_damage_and_eot(&mut self, game: &mut GameState) {
        // Remove temporary command-zone effect cards created by AB$ Effect
        // that expire at end of turn.
        let temp_effect_ids: Vec<CardId> = game
            .cards
            .iter()
            .filter(|c| c.zone == ZoneType::Command && c.temp_effect_until_eot)
            .map(|c| c.id)
            .collect();
        for effect_id in temp_effect_ids {
            if game.card(effect_id).zone == ZoneType::Command {
                let controller = game.card(effect_id).controller;
                game.remove_card_from_zone(ZoneType::Command, controller, effect_id);
                game.card_mut(effect_id).set_zone(ZoneType::None);
            }
        }

        // Return stolen creatures (LoseControl$ EOT) to their original controllers
        let stolen: Vec<(CardId, crate::ids::PlayerId)> = game
            .cards
            .iter()
            .filter(|c| c.zone == ZoneType::Battlefield && c.original_controller_eot.is_some())
            .map(|c| (c.id, c.original_controller_eot.unwrap()))
            .collect();
        for (card_id, original) in stolen {
            let current = game.card(card_id).controller;
            game.card_mut(card_id).clear_original_controller_eot();
            // Remove granted keywords (e.g. Haste from Act of Aggression)
            game.card_mut(card_id).clear_granted_keywords();
            if current != original {
                game.change_controller(card_id, original);
            }
        }

        // Player-owned cleanup state that expires at end of turn.
        let player_ids = game.player_order.clone();
        for player in player_ids {
            game.player_cleanup_turn_state(player);
            crate::player::expire_end_of_turn_keywords(game, player);
        }

        for i in 0..game.cards.len() {
            let card_id = game.cards[i].id;
            crate::ability::effects::change_text_effect::run(game, card_id);
        }

        // Remove damage and reset until-end-of-turn effects on all battlefield permanents
        for i in 0..game.cards.len() {
            if game.cards[i].zone == ZoneType::Battlefield {
                // Restore animate state before checking creature status (issue #52).
                if let Some(state) = game.cards[i].animate_state.take() {
                    game.cards[i].restore_animate_snapshot(
                        state.original_type_line,
                        state.original_base_power,
                        state.original_base_toughness,
                        state.original_color,
                    );
                    game.cards[i].clear_damage();
                }
                if game.cards[i]
                    .clone_state
                    .as_ref()
                    .is_some_and(|state| state.expires_at_cleanup)
                {
                    if let Some(state) = game.cards[i].clone_state.take() {
                        game.cards[i].restore_clone_snapshot(state);
                    }
                }

                game.cards[i].reset_turn_modifiers();
                game.cards[i].cant_have_keywords.clear();
                game.cards[i].clear_pump_keywords();
                game.cards[i].clear_pump_triggers();
                game.cards[i].clear_deathtouch_damage();
                game.cards[i].reset_regeneration_shields();
                game.cards[i].reset_shield_count();
                game.cards[i].reset_crewed();

                if game.cards[i].is_creature() {
                    let keep_damage =
                        crate::staticability::static_ability_no_cleanup_damage::damage_not_removed(
                            &game.cards,
                            &game.cards[i],
                        );
                    if !keep_damage {
                        game.cards[i].clear_damage();
                    }
                    game.cards[i].reset_turn_modifiers();
                    game.cards[i].clear_deathtouch_damage();
                    game.cards[i].reset_regeneration_shields();
                    game.cards[i].reset_shield_count();
                    game.cards[i].damage_history.new_turn();
                }
                // Effects with "until end of turn" duration end at cleanup
                // (CR 514.2). Pump keywords and "can't have" tags apply to
                // ANY permanent (e.g. Heroic Intervention grants hexproof to
                // creatures AND artifacts/lands), so the clear must run on
                // every battlefield card, not just creatures. Without this,
                // an artifact like Lightning Greaves keeps Heroic
                // Intervention's hexproof past the turn it was cast.
                game.cards[i].cant_have_keywords.clear();
                game.cards[i].clear_pump_keywords();
                game.cards[i].clear_pump_triggers();
            } else {
                game.cards[i].cant_have_keywords.clear();
                game.cards[i].clear_pump_keywords();
                game.cards[i].clear_pump_triggers();
            }
        }
    }
    pub(crate) fn emit_phase_trigger(&mut self, game: &mut GameState, phase: PhaseType) {
        let active = game.active_player();
        self.trigger_handler.run_trigger(
            TriggerType::Phase,
            RunParams {
                phase: Some(phase),
                player: Some(active),
                ..Default::default()
            },
            false,
        );
        self.trigger_handler.run_trigger(
            TriggerType::Always,
            RunParams {
                phase: Some(phase),
                player: Some(active),
                ..Default::default()
            },
            false,
        );
    }

    fn clear_came_under_control_since_last_upkeep(&mut self, game: &mut GameState) {
        let active = game.active_player();
        let turn_number = game.turn.turn_number;
        for card in &mut game.cards {
            if card.controller == active
                && card.zone == ZoneType::Battlefield
                && card.turn_in_zone < turn_number
            {
                card.came_under_control_since_last_upkeep = false;
            }
        }
    }

    /// Fire DamageDone and LifeGained triggers from combat damage events.
    /// DamageDone fires per source-target pair; DamageDoneOnce fires once per
    /// target with aggregated damage (mirrors Java CardDamageMap.triggerDamageOnce).
    pub(crate) fn fire_combat_damage_triggers(&mut self, events: &[combat::CombatDamageEvent]) {
        use crate::card::card_damage_map::{CardDamageMap, DamageTarget};
        use crate::ids::{CardId, PlayerId};
        use std::collections::HashMap;

        // Per-event: fire DamageDone and LifeGained
        for event in events {
            self.trigger_handler.run_trigger(
                TriggerType::DamageDone,
                RunParams {
                    damage_source: Some(event.source),
                    damage_target_player: event.target_player,
                    damage_target_card: event.target_card,
                    damage_amount: Some(event.amount),
                    is_combat_damage: Some(event.is_combat),
                    ..Default::default()
                },
                false,
            );
            if let Some(player) = event.lifelink_player {
                if event.lifelink_amount > 0 {
                    self.trigger_handler.run_trigger(
                        TriggerType::LifeGained,
                        RunParams {
                            player: Some(player),
                            life_amount: Some(event.lifelink_amount),
                            source_card: Some(event.source),
                            ..Default::default()
                        },
                        false,
                    );
                }
            }
        }

        // Aggregate damage by target, then fire DamageDoneOnce once per target.
        // Mirrors Java's CardDamageMap.triggerDamageOnce() which batches damage
        // so Enrage (e.g. Raptor Hatchling) fires only once per damage step.
        #[derive(Hash, PartialEq, Eq, Clone, Copy)]
        enum Target {
            Card(CardId),
            Player(PlayerId),
        }
        let mut by_target: HashMap<Target, i32> = HashMap::new();
        let mut maps_by_target: HashMap<Target, CardDamageMap> = HashMap::new();
        for event in events {
            if event.amount <= 0 {
                continue;
            }
            let target = if let Some(cid) = event.target_card {
                Target::Card(cid)
            } else if let Some(pid) = event.target_player {
                Target::Player(pid)
            } else {
                continue;
            };
            *by_target.entry(target).or_insert(0) += event.amount;
            let damage_target = match target {
                Target::Card(cid) => DamageTarget::Card(cid),
                Target::Player(pid) => DamageTarget::Player(pid),
            };
            maps_by_target.entry(target).or_default().put(
                event.source,
                damage_target,
                event.amount,
            );
        }
        for (target, total) in by_target {
            if total <= 0 {
                continue;
            }
            let params = match target {
                Target::Card(cid) => RunParams {
                    damage_target_card: Some(cid),
                    damage_amount: Some(total),
                    damage_map: maps_by_target.get(&target).cloned(),
                    is_combat_damage: Some(true),
                    ..Default::default()
                },
                Target::Player(pid) => RunParams {
                    damage_target_player: Some(pid),
                    damage_amount: Some(total),
                    damage_map: maps_by_target.get(&target).cloned(),
                    is_combat_damage: Some(true),
                    ..Default::default()
                },
            };
            self.trigger_handler
                .run_trigger(TriggerType::DamageDoneOnce, params, false);
        }
    }

    /// Suspend upkeep processing: for each suspended card in exile owned by the
    /// active player, remove a time counter. If the last counter was removed,
    /// cast the card for free (and grant haste if creature).
    /// Mirrors Java's GameAction.handleSuspendTriggers().
    pub(crate) fn process_suspend_upkeep(
        &mut self,
        game: &mut GameState,
        agents: &mut [Box<dyn PlayerAgent>],
    ) {
        let active = game.active_player();
        let exile: Vec<CardId> = game.cards_in_zone(ZoneType::Exile, active).to_vec();
        for card_id in exile {
            let card = game.card(card_id);
            // Check if the card has suspend keyword and time counters
            if card.get_suspend_cost().is_none() {
                continue;
            }
            let time_counters = *card
                .counters
                .get(&crate::card::CounterType::Time)
                .unwrap_or(&0);
            if time_counters <= 0 {
                continue;
            }
            // Remove one time counter
            game.card_mut(card_id)
                .remove_counter(&crate::card::CounterType::Time, 1);

            // Emit CounterRemoved trigger
            self.trigger_handler.run_trigger(
                TriggerType::CounterRemoved,
                RunParams {
                    card: Some(card_id),
                    player: Some(active),
                    ..Default::default()
                },
                false,
            );

            let remaining = *game
                .card(card_id)
                .counters
                .get(&crate::card::CounterType::Time)
                .unwrap_or(&0);
            if remaining <= 0 {
                // Last counter removed — cast for free
                let card_name = game.card(card_id).card_name.clone();
                let is_creature = game.card(card_id).is_creature();
                let is_permanent = game.card(card_id).is_permanent();
                // Move from exile to stack
                game.player_record_spell_cast(active, card_id);

                // Emit SpellCast trigger
                self.trigger_handler.run_trigger(
                    TriggerType::SpellCast,
                    RunParams {
                        spell_card: Some(card_id),
                        spell_controller: Some(active),
                        ..Default::default()
                    },
                    false,
                );

                // Build SpellAbility
                let mut sa =
                    crate::spellability::build_spell_ability_for_card_cast(game, card_id, active);
                sa.alt_cost = Some(crate::spellability::AlternativeCost::Suspend);
                sa.setup_targets(game, agents, &self.mana_pools);

                let entry = StackEntry {
                    id: 0,
                    spell_ability: sa,
                    is_pending_cast: false,
                    is_creature_spell: is_creature,
                    is_permanent_spell: is_permanent,
                    cast_from_zone: Some(ZoneType::Exile),
                    optional_trigger_decider: None,
                    optional_trigger_description: None,
                    optional_trigger_source_name: None,
                };

                game.stack.push(entry);
                self.log_stack_push(&card_name, &game.player(active).name);
                self.move_card_with_runtime(game, card_id, ZoneType::Stack, active, agents);
                crate::agent::notify_all_agents(
                    agents,
                    crate::agent::GameLogEvent::stack(format!(
                        "Suspend: casting {} for free!",
                        card_name
                    ))
                    .with_player(active)
                    .with_card(card_id),
                );

                // Grant haste if creature (suspend creatures get haste)
                if is_creature && !game.card(card_id).has_haste() {
                    game.card_mut(card_id).granted_keywords.add("Haste");
                }
            }
        }
    }
}