thebigjc shared

Public

Improving Game Engine for Card Set SupportPublic

Agent

Claude Code

Model

Claude Opus 4.6

Shared

Feb 15, 2:53 PM

Messages4,291

Summary

Caveat: The messages below were generated by the user while running local commands. DO NOT respond to these messages or otherwise consider them in your response unless the user explicitly asks you to.

Caveat: Caveat: The messages below were generated by the user while running local commands. DO NOT respond to these messages or otherwise consider them in your response unless the user explicitly asks you to.

Session command

ralph-loop:ralph-loop

Args: "Read mtg-rs/ROADMAP.md, and identify work that is outstanding to bring our rust engine into parity with Java. Do not implement any new sets, but add engine features that area missing. Our goal is to complete the fully functional implementation of ECL by implementing engine capabilities and updating cards to use them. Work one task at a time until we are done. Read the corresponding java source to understand how to shape the implementation. Update the ROADMAP and leave a note as you progress. Add tests for each engine feature you add. Commit changes after each item. Then get another ROADMAP item until the engine is at parity with the Java engine." --completion-promise "DONE" --max-iterations 90

Ralph Loop Command

Execute the setup script to initialize the Ralph loop:

🔄 Ralph loop activated in this session!

Iteration: 1
Max iterations: 90
Completion promise: DONE (ONLY output when TRUE - do not lie!)

The stop hook is now active. When you try to exit, the SAME PROMPT will be
fed back to you. You'll see your previous work in files, creating a
self-referential loop where you iteratively improve on the same task.

To monitor: head -10 .claude/ralph-loop.local.md

⚠️ WARNING: This loop cannot be stopped manually! It will run infinitely
unless you set --max-iterations or --completion-promise.

🔄

Read mtg-rs/ROADMAP.md, and identify work that is outstanding to bring our rust engine into parity with Java. Do not implement any new sets, but add engine features that area missing. Our goal is to complete the fully functional implementation of ECL by implementing engine capabilities and updating cards to use them. Work one task at a time until we are done. Read the corresponding java source to understand how to shape the implementation. Update the ROADMAP and leave a note as you progress. Add tests for each engine feature you add. Commit changes after each item. Then get another ROADMAP item until the engine is at parity with the Java engine.

═══════════════════════════════════════════════════════════
CRITICAL - Ralph Loop Completion Promise
═══════════════════════════════════════════════════════════

To complete this loop, output this EXACT text:
<promise>DONE</promise>

STRICT REQUIREMENTS (DO NOT VIOLATE):
✓ Use <promise> XML tags EXACTLY as shown above
✓ The statement MUST be completely and unequivocally TRUE
✓ Do NOT output false statements to exit the loop
✓ Do NOT lie even if you think you should exit

IMPORTANT - Do not circumvent the loop:
Even if you believe you're stuck, the task is impossible,
or you've been running too long - you MUST NOT output a
false promise statement. The loop is designed to continue
until the promise is GENUINELY TRUE. Trust the process.

If the loop should stop, the promise statement will become
true naturally. Do not force it by lying.
═══════════════════════════════════════════════════════════

Please work on the task. When you try to exit, the Ralph loop will feed the SAME PROMPT back to you for the next iteration. You'll see your previous work in files and git history, allowing you to iterate and improve.

CRITICAL RULE: If a completion promise is set, you may ONLY output it when the statement is completely and unequivocally TRUE. Do not output false promises to escape the loop, even if you think you're stuck or should exit for other reasons. The loop is designed to continue until genuine completion.

I'll start by reading the ROADMAP.md to understand what work is outstanding.

ReadROADMAP.md

This is a comprehensive ROADMAP. Let me understand the current state and identify the first task to work on. The phased implementation plan suggests:

Phase 1: Make the Engine Functional

Combat integration
Triggered ability stacking
Continuous effect layer application

These are the highest impact items. Let me start with Combat Integration since it affects 800+ cards and is the most critical gap. Let me first explore the current state of the codebase to understand what exists.

Let me read the key files to understand the current state:

combat.rs - already has combat functions
game.rs - needs combat wired in
The PlayerDecisionMaker trait needs implementations for choose_attackers() and choose_blockers() to handle the decision-making logic during combat phases.

This is a large roadmap. The highest-impact item is Combat Integration (Phase 1, Item 1), which affects 800+ cards. Let me start by exploring the current codebase to understand what exists and what needs to be wired in.

Perfect! Now let me write out a comprehensive report based on my exploration.

---

## Comprehensive Exploration Report: mtg-rl Rust Codebase

I've completed a thorough exploration of the mtg-rl game engine. Here's what I found:

### 1. COMBAT.RS - Combat System (/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/combat.rs)

**Current State:** Fully implemented combat framework with two main data structures:

**CombatGroup Struct (lines 24-71):**
- Represents one attacker and its blockers
- Fields: `attacker_id`, `defending_id`, `defending_player` (bool), `blockers` (Vec), `blocked` (bool), `damage_to_blockers` (HashMap), `trample_damage`
- Methods: `new()`, `add_blocker()`, `is_blocked()`, `is_unblocked()`

**CombatState Struct (lines 79-187):**
- Complete combat phase state
- Fields: `attacking_player`, `groups` (Vec<CombatGroup>), `attackers` (Vec), `blocker_to_attacker` (HashMap), `first_strike_dealt`, `regular_damage_dealt`
- Methods:
  - `new()`, `clear()` — reset combat state
  - `has_attackers()`, `is_attacking()`, `is_blocking()` — queries
  - `declare_attacker()` — adds attacker with defending target
  - `declare_blocker()` — assigns blocker to attacker group
  - `group_for_attacker()` / `group_for_attacker_mut()` — accessor methods
  - `defenders()` — returns unique defender list
  - `has_first_strikers()` — checks if any creature has first/double strike

**Combat Validation Functions (lines 193-224):**
- `can_attack(perm)` — checks if creature can legally attack
- `can_block(blocker, attacker)` — validates blocker vs attacker (checks flying, reach, etc.)
- `satisfies_menace(attacker, blocker_count)` — validates menace requirement (needs 2+ blockers if menace)

**Damage Assignment Functions (lines 231-324):**
- `assign_combat_damage()` — primary function (lines 233-302)
  - Input: combat group, attacker, blockers (Vec of (ObjectId, &Permanent) pairs), is_first_strike_step
  - Returns: Vec<(ObjectId, u32, bool)> = (target_id, damage_amount, is_player)
  - Handles: unblocked damage → defender, blocked damage → blockers in order, trample overflow, deathtouch lethal calculation
  - First/double strike timing checks determine if attacker deals damage in this step
- `assign_blocker_damage()` — blocker damage calculation (lines 305-324)
  - Input: blocker, attacker_id, is_first_strike_step
  - Returns: u32 (damage amount)
  - Respects first strike timing

**Comprehensive Test Suite (lines 327-560)** covering:
- Basic combat state operations
- Blocking mechanics
- Unblocked/blocked damage assignment
- Trample overflow
- Deathtouch minimization
- First strike and double strike timing
- Flying/reach blocking rules
- Menace requirements
- Combat clear operations

---

### 2. GAME.RS - Game Loop (/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/game.rs, ~4436 lines)

**Game Struct (lines 76-85):**
```rust
pub struct Game {
    pub state: GameState,
    pub turn_manager: TurnManager,
    decision_makers: HashMap<PlayerId, Box<dyn PlayerDecisionMaker>>,
    pub watchers: WatcherManager,
}
```

**Main Game Loop (`run()` method, lines 154-235):**
1. Shuffle libraries
2. Draw opening hands (7 cards each)
3. London mulligan phase
4. Notify decision makers of game start
5. **Main loop:**
   - Process current step
   - Check game end conditions
   - Advance to next step OR start new turn
   - Loop until game ends or max turns reached

**Step Processing (`process_step()`, lines 343-360):**
```rust
fn process_step(&mut self, step: PhaseStep, active_player: PlayerId) {
    1. turn_based_actions(step, active_player)
    2. process_state_based_actions()
    3. // TODO: Put triggered abilities on stack (task #13)
    4. if has_priority(step) { priority_loop() }
}
```

**Turn-Based Actions (`turn_based_actions()`, lines 363-448):**
Currently handles:
- **PhaseStep::Untap:** Untap all permanents controlled by active player, clear mana pool
- **PhaseStep::Draw:** Draw 1 card (skip on turn 1 for starting player)
- **PhaseStep::Cleanup:** Discard down to 7 cards, clear all creature damage, remove temporary effects (granted keywords, control changes), empty mana pools

**Key Missing:** Combat steps (DeclareAttackers, DeclareBlockers, FirstStrikeDamage, CombatDamage, EndCombat) are NOT implemented in turn_based_actions. They fall through to the default case (no-op).

**Priority Loop (`priority_loop()`, lines 452-534):**
- Manages priority passing during each step
- Uses PriorityTracker to track consecutive passes (all-pass = step ends or stack resolves)
- When all players pass:
  - If stack empty → step ends, return
  - If stack has items → resolve top item, reset passes, priority back to active player
- Player actions: Pass, PlayLand, CastSpell, ActivateAbility, ActivateManaAbility

**Compute Legal Actions (`compute_legal_actions()`, lines 537-625):**
- Always includes Pass action
- Checks for playable lands (if can_sorcery and can_play_land())
- Checks for castable spells (mana available, sorcery-speed check)
- Checks for activatable abilities on permanents player controls

**Effects Execution (`execute_effects()`, lines 1089+):**
Handles ~20 effect types:
- DealDamage, Destroy, Exile, Bounce, PutOnLibrary
- DrawCards, GainLife, LoseLife, LoseLifeOpponents, DealDamageOpponents
- AddCounters, AddCountersSelf
- BoostUntilEndOfTurn, TapTarget, UntapTarget
- CounterSpell, AddMana, DiscardCards, DiscardOpponents
- GainKeywordUntilEndOfTurn (referenced in cleanup)
- CreateToken (simplified), Search library, etc.

---

### 3. DECISION.RS - PlayerDecisionMaker Trait (/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/decision.rs)

**PlayerDecisionMaker Trait (lines 168-353):**

Core decision methods:
- `priority()` — player has priority; returns one legal action from provided list
- `choose_targets()` — select targets for spell/ability
- `choose_use()` — yes/no decisions with Outcome hint
- `choose_mode()` — mode selection for modal spells
- **`select_attackers()`** — declare attackers
  - Input: possible_attackers (Vec<ObjectId>), possible_defenders (Vec<ObjectId>)
  - Returns: Vec<(ObjectId, ObjectId)> pairs = (attacker_id, defender_id)
- **`select_blockers()`** — declare blockers
  - Input: attackers (Vec<AttackerInfo>)
  - Returns: Vec<(ObjectId, ObjectId)> pairs = (blocker_id, attacker_id)
- `assign_damage()` — distribute damage among targets (trample, split damage)
- `choose_mulligan()`, `choose_cards_to_put_back()`, `choose_discard()` — hand management
- `choose_amount()` — X costs, counter selection, etc.
- `choose_mana_payment()` — mana ability activation during payment
- `choose_replacement_effect()` — pick among multiple replacement effects
- `choose_pile()` — Fact or Fiction style splits
- `choose_option()` — generic named option selection
- `on_game_start()`, `on_game_end()` — lifecycle callbacks

**AttackerInfo Struct (lines 109-115):**
```rust
pub struct AttackerInfo {
    pub attacker_id: ObjectId,
    pub defending_id: ObjectId,  // player or planeswalker being attacked
    pub legal_blockers: Vec<ObjectId>,  // creatures that can block this attacker
}
```

**GameView Placeholder (lines 144-162):**
- Currently just a placeholder with PhantomData
- Intended to provide read-only access to GameState for decision-making
- Will be expanded when full GameState integration occurs

---

### 4. TURN.RS - Turn Manager (/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/turn.rs)

**Turn Sequence Constant (lines 19-33):**
```rust
const TURN_STEPS: &[PhaseStep] = &[
    Untap, Upkeep, Draw,
    PrecombatMain,
    BeginCombat, DeclareAttackers, DeclareBlockers,
    FirstStrikeDamage, CombatDamage, EndCombat,
    PostcombatMain,
    EndStep, Cleanup,
];
```

**TurnManager Struct (lines 65-95):**
- `current_step_index` — position in TURN_STEPS
- `turn_order` — Vec<PlayerId> rotation
- `next_normal_turn_index` — tracks normal turn progression (separate from extra turns)
- `current_active_player` — whose turn it is
- `turn_number` — 1-based
- `extra_turns` — VecDeque<PlayerId> (LIFO for MTG rules)
- `end_turn_requested` — "end the turn" effect flag
- `had_combat` — whether combat occurred (for end-of-combat triggers)
- `has_first_strike` — whether to include FirstStrikeDamage step

**Key Methods:**
- `new()` — initialize for given players
- `current_step()` / `current_phase()` — get current position
- `active_player()` — whose turn
- `advance_step()` — move to next step (returns Option<PhaseStep>)
  - Skips FirstStrikeDamage if `has_first_strike == false`
  - Skips to Cleanup if `end_turn_requested == true`
- `next_turn()` — rotate active player, handle extra turns LIFO
- `add_extra_turn()` — queue extra turn (pushes to front for LIFO)
- `request_end_turn()` — set flag to skip to cleanup
- `turn_order()` — read turn order
- `has_extra_turns()` — check for pending extra turns

**PriorityTracker Struct (lines 206-240):**
- `current` — player with priority
- `passes` — consecutive passes count
- `player_count` — total players
- Methods: `pass()` (returns true if all passed), `reset()`, `all_passed()`

**Helper Functions (lines 36-60):**
- `step_to_phase()` — maps PhaseStep to TurnPhase
- `has_priority()` — false for Untap/Cleanup (normally)
- `is_sorcery_speed()` — true for main phases only

---

### 5. EVENTS.RS - Game Event System (/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/events.rs)

**EventType Enum (lines 30-295):**
~90 event types across categories:

**Combat-Related Events:**
- DeclareAttacker / AttackerDeclared / DeclaredAttackers
- DeclareBlocker / BlockerDeclared / DeclaredBlockers
- CreatureBlocked / UnblockedAttacker
- CombatDamageStepPre / CombatDamageStep

**Turn Structure Events:**
- BeginTurn, EndTurn, ChangePhase, ChangeStep
- UntapStepPre / UntapStep, UpkeepStepPre / UpkeepStep, DrawStepPre / DrawStep
- PrecombatMainPre / PrecombatMain, BeginCombatPre / BeginCombat
- DeclareAttackersPre / DeclareAttackers, DeclareBlockersPre / DeclareBlockers
- FirstStrikeDamage (implied), CombatDamageStepPre / CombatDamageStep, EndCombatPre / EndCombat
- PostcombatMainPre / PostcombatMain, EndStepPre / EndStep, CleanupStepPre / CleanupStep

**Zone/Card Events:** ZoneChange, DrawCard, DiscardCard, EntersTheBattlefield, Dies, ExileCard, MillCards
**Spell/Ability Events:** CastSpell, ActivateAbility, TriggeredAbility, ResolveSpell, Counter
**Damage/Life Events:** DamagePlayer, DamagePermanent, CombatDamageApplied, GainLife, LoseLife, PayLife
**Permanent Events:** Tap, Untap, Destroy, Sacrifice, Regenerate, AddCounters, RemoveCounters
**Other:** CreateToken, PlayLand, SearchLibrary, GainControl, etc.

**GameEvent Struct (lines 305-412):**
```rust
pub struct GameEvent {
    pub event_type: EventType,
    pub target_id: Option<ObjectId>,  // damaged creature, countered spell, etc.
    pub source_id: Option<ObjectId>,  // ability/spell causing event
    pub player_id: Option<PlayerId>,  // casting/damaged player
    pub amount: i32,  // damage, life, counters, etc.
    pub flag: bool,  // event-type-specific
    pub data: Option<String>,  // zone transitions, etc.
    pub zone: Option<Zone>,  // from/to zones
    pub prevented: bool,  // was event prevented?
    pub applied_effects: Vec<ObjectId>,  // tracking applied replacements
}
```
- Builder pattern methods: `.target()`, `.source()`, `.player()`, `.amount()`, `.flag()`, `.data()`, `.zone()`
- Methods: `prevent()`, `mark_applied()`, `was_applied()`

**Convenience Constructors:**
- `damage_player()`, `damage_permanent()`
- `gain_life()`, `lose_life()`
- `draw_card()`, `discard_card()`
- `zone_change()`, `spell_cast()`, `enters_battlefield()`, `dies()`
- `declare_attacker()`, `declare_blocker()`
- `destroy_permanent()`, `add_counters()`, `tap()`

**EventLog Struct (lines 580-627):**
- Tracks all events during a game action
- Methods: `push()`, `events_of_type()`, `iter()`, `len()`, `has_event()`, `count_events()`, `clear()`

---

### 6. STATE.RS - GameState (/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/state.rs)

**GameState Struct (lines 25-102):**
```rust
pub struct GameState {
    pub players: HashMap<PlayerId, Player>,
    pub turn_order: Vec<PlayerId>,
    pub battlefield: Battlefield,
    pub stack: Stack,
    pub exile: Exile,
    pub card_store: CardStore,
    pub ability_store: AbilityStore,
    pub object_zones: HashMap<ObjectId, ZoneLocation>,
    pub turn_number: u32,
    pub active_player: PlayerId,
    pub priority_player: PlayerId,
    pub current_phase: TurnPhase,
    pub current_step: PhaseStep,
    pub game_over: bool,
    pub winner: Option<PlayerId>,
    pub resolving: bool,
    pub consecutive_passes: u32,
    pub has_day_night: bool,
    pub is_daytime: bool,
    pub monarch: Option<PlayerId>,
    pub initiative: Option<PlayerId>,
    pub values: HashMap<String, i64>,
}
```

**Key Methods:**
- Player access: `player()`, `player_mut()`, `active_player()`, `opponent_of()`, `active_players()`, `next_player()`
- Zone tracking: `set_zone()`, `get_zone()`, `zone_of()`, `find_card_owner_in_graveyard()`
- Phase queries: `is_main_phase()`, `stack_is_empty()`, `can_cast_sorcery()`
- State checks: `check_state_based_actions()` — returns StateBasedActions

**StateBasedActions Struct:**
Holds lists of:
- `players_losing` — players at 0 life or with 10 poison
- `permanents_to_graveyard` — creatures with 0 toughness
- `permanents_to_destroy` — creatures with lethal damage (not indestructible)
- `counters_to_annihilate` — permanents with both +1/+1 and -1/-1 counters

---

### 7. ZONES.RS - Zone Containers (/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/zones.rs)

**StackItem Struct (lines 431-442):**
```rust
pub struct StackItem {
    pub id: ObjectId,
    pub kind: StackItemKind,  // Spell or Ability
    pub controller: PlayerId,
    pub targets: Vec<ObjectId>,
    pub countered: bool,
}
```

**StackItemKind Enum (lines 446-461):**
```rust
pub enum StackItemKind {
    Spell { card: CardData },
    Ability { source_id: ObjectId, ability_id: AbilityId, description: String },
}
```

**Stack Struct (lines 465-525):**
- LIFO structure
- Methods: `push()`, `pop()`, `top()`, `get()`, `remove()`, `len()`, `is_empty()`, `iter()`, `clear()`

**Battlefield, Hand, Graveyard, Library, Exile:**
- Library: ordered, top=index 0; methods: `draw()`, `peek()`, `put_on_top()`, `put_on_bottom()`, `shuffle()`
- Hand: unordered set; methods: `add()`, `remove()`, `contains()`
- Graveyard: ordered LIFO (most recent on top); same interface as hand
- Exile: supports main zone + named sub-zones
- Battlefield: holds Permanent objects, keyed by ObjectId for O(1) lookup

---

## Summary of Current State

**What Exists:**
- Combat framework fully implemented (CombatState, CombatGroup, damage assignment logic)
- Event system with ~90 event types including combat events
- Turn management with proper step sequencing, phase handling, extra turns, priority tracking
- PlayerDecisionMaker trait with `select_attackers()` and `select_blockers()` methods
- Game loop with priority handling and spell resolution
- Effect execution for ~20 effect types
- State-based actions detection and application

**What's Missing / TODO:**
1. **Combat step handling in game loop** — `turn_based_actions()` doesn't implement DeclareAttackers, DeclareBlockers, FirstStrikeDamage, CombatDamage, EndCombat steps
2. **Combat state integration** — CombatState exists in combat.rs but is never instantiated or used in GameState
3. **Triggered ability resolution** — TODO comment at line 354 in game.rs: "Put triggered abilities on the stack (task #13)"
4. **Full event integration** — Events are defined but not being emitted during game actions
5. **Watchers/Watcher system** — WatcherManager exists but isn't fully connected
6. **Replacement effects** — Framework exists but not integrated into event handling
7. **Continuous effects** — References exist but full layer system not implemented
8. **GameView implementation** — Currently just a placeholder; needs to expose GameState

**Critical Gap:** The game loop is missing the entire combat phase implementation. Combat steps are defined in TURN_STEPS and will be reached by `advance_step()`, but when they arrive in `process_step()`, they fall through to the default case (do nothing) because `turn_based_actions()` doesn't handle them.

Absolute file paths for reference:
- `/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/combat.rs`
- `/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/game.rs`
- `/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/decision.rs`
- `/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/turn.rs`
- `/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/events.rs`
- `/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/state.rs`
- `/mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/zones.rs`
agentId: ac95cd6 (for resuming to continue this agent's work if needed)
<usage>total_tokens: 88171
tool_uses: 20
duration_ms: 87645</usage>

Excellent! Now I have a thorough understanding of the codebase. Let me plan the combat integration work:

Add CombatState to GameState - The combat state needs to be part of the game state
Implement combat steps in turn_based_actions():
- DeclareAttackers: prompt active player for attackers, tap them (unless vigilance), emit events
- DeclareBlockers: prompt defending player for blockers, validate, emit events
- FirstStrikeDamage: deal first/double strike damage
- CombatDamage: deal regular combat damage
- EndCombat: clean up combat state
Wire in damage application - apply combat damage to permanents and players
Handle lifelink - when dealing combat damage, gain life if lifelink
Handle vigilance - don't tap attackers with vigilance
Add tests

Now I need to examine the specific sections of game.rs and state.rs that I'll be modifying.

Now I have a comprehensive understanding. Let me read the specific sections I need to modify.

Readstate.rs110 lines

Readgame.rs120 lines

Readcombat.rs

Now I have a thorough understanding of the codebase. Let me also read the game.rs to understand how damage dealing works and the permanent struct to understand what methods are available on it.

Let me read some more context needed:

How damage is dealt to permanents and players (in game.rs)
The Permanent struct (permanent.rs) to understand available methods
The existing AI decision makers to see if they have select_attackers/select_blockers implementations

Let me read more context needed to implement combat integration.

Readgame.rs200 lines

Readpermanent.rs100 lines

Greppedfn select_attackers|fn select_blockers

Readpermanent.rs200 lines

Greppedfn select_attackers|fn select_blockers

Readtoolu_01EsPUKHZRALuN4JnocpgJDw.txt

Now let me look at how damage dealing works in the game loop, and also how process_state_based_actions works since we'll need to ensure SBAs fire after combat damage.

Greppedfn deal_damage|fn process_state_based_actions|fn apply_damage_to_permanent

Greppedfn deal_damage_to|fn damage_player|fn damage_permanent

GreppedDealDamage

Now I have a thorough understanding of the codebase. Let me plan the combat integration:

Add CombatState to GameState — Add a combat field to GameState
Implement combat steps in turn_based_actions():
- DeclareAttackers:
  - Collect possible attackers (creatures active player controls that can attack)
  - Collect possible defenders (opponent player IDs, represented as ObjectIds)
  - Call select_attackers() on decision maker
  - Register chosen attackers in CombatState
  - Tap attacking creatures unless they have vigilance, then emit DeclareAttacker events
- DeclareBlockers:
  - Skip if no attackers exist
  - For each defending player, gather available blockers and build AttackerInfo for each attacker with legal blockers
  - Call select_blockers() on each defending player's decision maker, register blockers, validate menace requirements, and emit DeclareBlocker events
- FirstStrikeDamage:
  - Skip if no first or double strikers exist
  - For each combat group, compute damage using assign_combat_damage(), apply it to permanents and players, and handle lifelink by gaining life equal to damage dealt
- CombatDamage:
  - Apply regular damage the same way as first strike damage
- EndCombat:
  - Clear the combat state
- Now I need to check how CombatState is imported and used in game.rs, and verify the combat module is already accessible

Let me check the module structure and imports in game.rs.

Readgame.rs80 lines

Readlib.rs

Good - the combat module is already in lib.rs. Now I have all the context I need. Let me implement combat integration. This is a large task, so let me break it down:

Add CombatState to GameState
Add combat step handling to turn_based_actions() in game.rs
Add tests

Let me start implementing. First, add CombatState to GameState.

Readstate.rs200 lines

Now I have all the context I need. Let me implement the combat integration step by step.

Plan:

Add combat: CombatState to GameState struct and initialize it in new()
Import combat module in state.rs
Add combat step implementations to turn_based_actions() in game.rs
Import CombatState and related types in game.rs
Add tests

Let me start with the changes:

state.rs changes:

Add use crate::combat::CombatState;
Add the combat field to the struct and initialize it when creating a new game state

game.rs changes:

Import the necessary combat types
Add handlers for each combat phase (declaring attackers and blockers, resolving first strike and regular damage, ending combat) in the turn_based_actions() function

Now I'll write the implementation code.

Now I have everything I need. Let me implement combat integration step by step.

Step 1: Add CombatState to GameState

Now add combat: CombatState::new() to the new() constructor:

Step 2: Implement combat steps in game.rs

First, add the imports needed:

Now implement the combat steps. Let me replace the _ => catch-all in turn_based_actions():

Now let me check if the gain_life method exists on Player:

Greppedfn gain_life|fn is_in_game

Good. Now let's check if it compiles:

It compiles with just one unused import warning. Let me fix that:

Clean compile. Now let me check the rest of the workspace:

Full workspace compiles. Now let me run existing tests to make sure nothing is broken:

All 19 tests pass. Let me also check the engine tests:

All 188 engine tests pass. Now let me write tests for the combat integration. Let me find a good spot to add them in game.rs tests:

Readgame.rs70 lines

Let me find the end of the test module to add combat tests:

Readgame.rs30 lines

Now I need to look at the test setup pattern to understand how to construct a game for combat testing. Let me read a nearby test setup:

Readgame.rs100 lines

Good. Now I understand the test pattern. I need to write combat tests that create a game, manually set up the battlefield, and then call the combat step methods directly. Let me add tests at the end of the test module.

Readgame.rs60 lines

Now let me understand how to set up a quick test game. I'll need a helper function that creates a game and lets me add creatures to the battlefield, then I'll test combat directly. Let me add the tests:

Readgame.rs10 lines

cat >> /mnt/dest-btrfs/home/jc/src/mage/mtg-rl/mtg-engine/src/game.rs << 'RUSTEOF'

#[cfg(test)]
mod combat_tests {
    use super::*;
    use crate::card::CardData;
    use crate::constants::{CardType, KeywordAbilities, Outcome};
    use crate::decision::{
        AttackerInfo, DamageAssignment, GameView, NamedChoice, PlayerAction,
        ReplacementEffectChoice, TargetRequirement, UnpaidMana,
    };

    /// Decision maker that attacks with all creatures.
    struct AttackAllPlayer;

    impl PlayerDecisionMaker for AttackAllPlayer {
        fn priority(&mut self, _: &GameView<'_>, _: &[PlayerAction]) -> PlayerAction {
            PlayerAction::Pass
        }
        fn choose_targets(&mut self, _: &GameView<'_>, _: Outcome, _: &TargetRequirement) -> Vec<ObjectId> { vec![] }
        fn choose_use(&mut self, _: &GameView<'_>, _: Outcome, _: &str) -> bool { false }
        fn choose_mode(&mut self, _: &GameView<'_>, _: &[NamedChoice]) -> usize { 0 }
        fn select_attackers(
            &mut self,
            _: &GameView<'_>,
            possible_attackers: &[ObjectId],
            possible_defenders: &[ObjectId],
        ) -> Vec<(ObjectId, ObjectId)> {
            let defender = possible_defenders[0];
            possible_attackers
                .iter()
                .map(|&a| (a, defender))
                .collect()
        }
        fn select_blockers(&mut self, _: &GameView<'_>, _: &[AttackerInfo]) -> Vec<(ObjectId, ObjectId)> { vec![] }
        fn assign_damage(&mut self, _: &GameView<'_>, _: &DamageAssignment) -> Vec<(ObjectId, u32)> { vec![] }
        fn choose_mulligan(&mut self, _: &GameView<'_>, _: &[ObjectId]) -> bool { false }
        fn choose_cards_to_put_back(&mut self, _: &GameView<'_>, _: &[ObjectId], _: usize) -> Vec<ObjectId> { vec![] }
        fn choose_discard(&mut self, _: &GameView<'_>, _: &[ObjectId], _: usize) -> Vec<ObjectId> { vec![] }
        fn choose_amount(&mut self, _: &GameView<'_>, _: &str, min: u32, _: u32) -> u32 { min }
        fn choose_mana_payment(&mut self, _: &GameView<'_>, _: &UnpaidMana, _: &[PlayerAction]) -> Option<PlayerAction> { None }
        fn choose_replacement_effect(&mut self, _: &GameView<'_>, _: &[ReplacementEffectChoice]) -> usize { 0 }
        fn choose_pile(&mut self, _: &GameView<'_>, _: Outcome, _: &str, _: &[ObjectId], _: &[ObjectId]) -> bool { true }
        fn choose_option(&mut self, _: &GameView<'_>, _: Outcome, _: &str, _: &[NamedChoice]) -> usize { 0 }
    }

    /// Decision maker that blocks with all available creatures (first available for each attacker).
    struct BlockAllPlayer;

    impl PlayerDecisionMaker for BlockAllPlayer {
        fn priority(&mut self, _: &GameView<'_>, _: &[PlayerAction]) -> PlayerAction {
            PlayerAction::Pass
        }
        fn choose_targets(&mut self, _: &GameView<'_>, _: Outcome, _: &TargetRequirement) -> Vec<ObjectId> { vec![] }
        fn choose_use(&mut self, _: &GameView<'_>, _: Outcome, _: &str) -> bool { false }
        fn choose_mode(&mut self, _: &GameView<'_>, _: &[NamedChoice]) -> usize { 0 }
        fn select_attackers(&mut self, _: &GameView<'_>, _: &[ObjectId], _: &[ObjectId]) -> Vec<(ObjectId, ObjectId)> { vec![] }
        fn select_blockers(
            &mut self,
            _: &GameView<'_>,
            attackers: &[AttackerInfo],
        ) -> Vec<(ObjectId, ObjectId)> {
            let mut blocks = Vec::new();
            let mut used = std::collections::HashSet::new();
            for info in attackers {
                for &blocker_id in &info.legal_blockers {
                    if !used.contains(&blocker_id) {
                        blocks.push((blocker_id, info.attacker_id));
                        used.insert(blocker_id);
                        break;
                    }
                }
            }
            blocks
        }
        fn assign_damage(&mut self, _: &GameView<'_>, _: &DamageAssignment) -> Vec<(ObjectId, u32)> { vec![] }
        fn choose_mulligan(&mut self, _: &GameView<'_>, _: &[ObjectId]) -> bool { false }
        fn choose_cards_to_put_back(&mut self, _: &GameView<'_>, _: &[ObjectId], _: usize) -> Vec<ObjectId> { vec![] }
        fn choose_discard(&mut self, _: &GameView<'_>, _: &[ObjectId], _: usize) -> Vec<ObjectId> { vec![] }
        fn choose_amount(&mut self, _: &GameView<'_>, _: &str, min: u32, _: u32) -> u32 { min }
        fn choose_mana_payment(&mut self, _: &GameView<'_>, _: &UnpaidMana, _: &[PlayerAction]) -> Option<PlayerAction> { None }
        fn choose_replacement_effect(&mut self, _: &GameView<'_>, _: &[ReplacementEffectChoice]) -> usize { 0 }
        fn choose_pile(&mut self, _: &GameView<'_>, _: Outcome, _: &str, _: &[ObjectId], _: &[ObjectId]) -> bool { true }
        fn choose_option(&mut self, _: &GameView<'_>, _: Outcome, _: &str, _: &[NamedChoice]) -> usize { 0 }
    }

    fn make_creature(
        name: &str,
        owner: PlayerId,
        power: i32,
        toughness: i32,
        keywords: KeywordAbilities,
    ) -> CardData {
        let mut card = CardData::new(ObjectId::new(), owner, name);
        card.card_types = vec![CardType::Creature];
        card.power = Some(power);
        card.toughness = Some(toughness);
        card.keywords = keywords;
        card
    }

    fn make_deck(owner: PlayerId) -> Vec<CardData> {
        (0..40)
            .map(|i| {
                let mut c = CardData::new(ObjectId::new(), owner, &format!("Card {i}"));
                c.card_types = vec![CardType::Land];
                c
            })
            .collect()
    }

    fn setup_combat_game(
        p1_dm: Box<dyn PlayerDecisionMaker>,
        p2_dm: Box<dyn PlayerDecisionMaker>,
    ) -> (Game, PlayerId, PlayerId) {
        let p1 = PlayerId::new();
        let p2 = PlayerId::new();
        let config = GameConfig {
            players: vec![
                PlayerConfig {
                    name: "Attacker".to_string(),
                    deck: make_deck(p1),
                },
                PlayerConfig {
                    name: "Defender".to_string(),
                    deck: make_deck(p2),
                },
            ],
            starting_life: 20,
        };
        let game = Game::new_two_player(config, vec![(p1, p1_dm), (p2, p2_dm)]);
        (game, p1, p2)
    }

    /// Helper to add a creature to the battlefield and remove summoning sickness.
    fn add_creature(
        game: &mut Game,
        owner: PlayerId,
        name: &str,
        power: i32,
        toughness: i32,
        keywords: KeywordAbilities,
    ) -> ObjectId {
        let card = make_creature(name, owner, power, toughness, keywords);
        let id = card.id;
        let mut perm = Permanent::new(card, owner);
        perm.remove_summoning_sickness();
        game.state.battlefield.add(perm);
        id
    }

    // ── Test: Unblocked combat damage ──────────────────────────────

    #[test]
    fn unblocked_attacker_deals_damage_to_player() {
        let (mut game, p1, p2) = setup_combat_game(
            Box::new(AttackAllPlayer),
            Box::new(BlockAllPlayer),
        );

        // Add a 3/3 creature for p1 (attacker)
        let bear_id = add_creature(&mut game, p1, "Bear", 3, 3, KeywordAbilities::empty());

        // Set active player to p1
        game.state.active_player = p1;

        // Run declare attackers step
        game.declare_attackers_step(p1);

        // Bear should be attacking
        assert!(game.state.combat.is_attacking(bear_id));
        // Bear should be tapped (no vigilance)
        assert!(game.state.battlefield.get(bear_id).unwrap().tapped);

        // Run declare blockers (no blockers for p2)
        game.declare_blockers_step(p1);

        // Run combat damage (regular)
        game.combat_damage_step(false);

        // p2 should have taken 3 damage
        assert_eq!(game.state.players[&p2].life, 17);
    }

    #[test]
    fn vigilance_does_not_tap_attacker() {
        let (mut game, p1, _p2) = setup_combat_game(
            Box::new(AttackAllPlayer),
            Box::new(BlockAllPlayer),
        );

        let vig_id = add_creature(&mut game, p1, "Vigilant", 2, 2, KeywordAbilities::VIGILANCE);
        game.state.active_player = p1;
        game.declare_attackers_step(p1);

        // Should be attacking but NOT tapped
        assert!(game.state.combat.is_attacking(vig_id));
        assert!(!game.state.battlefield.get(vig_id).unwrap().tapped);
    }

    #[test]
    fn blocked_creature_deals_damage_to_blocker() {
        let (mut game, p1, p2) = setup_combat_game(
            Box::new(AttackAllPlayer),
            Box::new(BlockAllPlayer),
        );

        let attacker_id = add_creature(&mut game, p1, "Attacker", 3, 3, KeywordAbilities::empty());
        let blocker_id = add_creature(&mut game, p2, "Blocker", 2, 4, KeywordAbilities::empty());

        game.state.active_player = p1;
        game.declare_attackers_step(p1);
        game.declare_blockers_step(p1);

        // Blocker should be blocking
        assert!(game.state.combat.is_blocking(blocker_id));

        // Apply combat damage
        game.combat_damage_step(false);

        // Blocker should have 3 damage, attacker should have 2 damage
        assert_eq!(game.state.battlefield.get(blocker_id).unwrap().damage, 3);
        assert_eq!(game.state.battlefield.get(attacker_id).unwrap().damage, 2);
        // Player should NOT have taken damage (blocked)
        assert_eq!(game.state.players[&p2].life, 20);
    }

    #[test]
    fn lifelink_gains_life_on_combat_damage() {
        let (mut game, p1, p2) = setup_combat_game(
            Box::new(AttackAllPlayer),
            Box::new(BlockAllPlayer),
        );

        add_creature(&mut game, p1, "Lifelinker", 4, 4, KeywordAbilities::LIFELINK);

        game.state.active_player = p1;

        // Reduce p1 life to verify gain
        game.state.players.get_mut(&p1).unwrap().life = 15;

        game.declare_attackers_step(p1);
        game.declare_blockers_step(p1);
        game.combat_damage_step(false);

        // p1 should gain 4 life (lifelink), p2 takes 4
        assert_eq!(game.state.players[&p1].life, 19);
        assert_eq!(game.state.players[&p2].life, 16);
    }

    #[test]
    fn first_strike_deals_damage_first() {
        let (mut game, p1, p2) = setup_combat_game(
            Box::new(AttackAllPlayer),
            Box::new(BlockAllPlayer),
        );

        let fs_id = add_creature(&mut game, p1, "FirstStriker", 3, 2, KeywordAbilities::FIRST_STRIKE);
        let blocker_id = add_creature(&mut game, p2, "Blocker", 3, 3, KeywordAbilities::empty());

        game.state.active_player = p1;
        game.declare_attackers_step(p1);
        game.declare_blockers_step(p1);

        // First strike damage step
        game.combat_damage_step(true);

        // Blocker takes 3 first strike damage
        assert_eq!(game.state.battlefield.get(blocker_id).unwrap().damage, 3);
        // First striker takes 0 (normal creature doesn't deal in first strike step)
        assert_eq!(game.state.battlefield.get(fs_id).unwrap().damage, 0);

        // Regular damage step
        game.combat_damage_step(false);

        // First striker still takes 0 more (first strike creature doesn't deal in regular step)
        // But blocker deals its 3 damage to first striker in regular step
        assert_eq!(game.state.battlefield.get(fs_id).unwrap().damage, 3);
    }

    #[test]
    fn trample_overflow_to_player() {
        let (mut game, p1, p2) = setup_combat_game(
            Box::new(AttackAllPlayer),
            Box::new(BlockAllPlayer),
        );

        add_creature(&mut game, p1, "Trampler", 5, 5, KeywordAbilities::TRAMPLE);
        let blocker_id = add_creature(&mut game, p2, "SmallBlocker", 1, 2, KeywordAbilities::empty());

        game.state.active_player = p1;
        game.declare_attackers_step(p1);
        game.declare_blockers_step(p1);
        game.combat_damage_step(false);

        // Blocker takes 2 damage (lethal), 3 tramples to player
        assert_eq!(game.state.battlefield.get(blocker_id).unwrap().damage, 2);
        assert_eq!(game.state.players[&p2].life, 17);
    }

    #[test]
    fn end_combat_clears_state() {
        let (mut game, p1, _p2) = setup_combat_game(
            Box::new(AttackAllPlayer),
            Box::new(BlockAllPlayer),
        );

        add_creature(&mut game, p1, "Bear", 2, 2, KeywordAbilities::empty());

        game.state.active_player = p1;
        game.declare_attackers_step(p1);
        assert!(game.state.combat.has_attackers());

        // End combat clears state
        game.state.combat.clear();
        assert!(!game.state.combat.has_attackers());
    }

    #[test]
    fn defender_cannot_attack() {
        let (mut game, p1, p2) = setup_combat_game(
            Box::new(AttackAllPlayer),
            Box::new(BlockAllPlayer),
        );

        // Only a defender creature
        add_creature(&mut game, p1, "Wall", 0, 5, KeywordAbilities::DEFENDER);

        game.state.active_player = p1;
        game.declare_attackers_step(p1);

        // Should have no attackers (defender can't attack)
        assert!(!game.state.combat.has_attackers());
        assert_eq!(game.state.players[&p2].life, 20);
    }

    #[test]
    fn summoning_sick_creature_cannot_attack() {
        let (mut game, p1, p2) = setup_combat_game(
            Box::new(AttackAllPlayer),
            Box::new(BlockAllPlayer),
        );

        // Add creature WITH summoning sickness (don't remove it)
        let card = make_creature("SickBear", p1, 3, 3, KeywordAbilities::empty());
        let perm = Permanent::new(card, p1);
        game.state.battlefield.add(perm);

        game.state.active_player = p1;
        game.declare_attackers_step(p1);

        // Should not have attacked
        assert!(!game.state.combat.has_attackers());
        assert_eq!(game.state.players[&p2].life, 20);
    }

    #[test]
    fn haste_bypasses_summoning_sickness() {
        let (mut game, p1, p2) = setup_combat_game(
            Box::new(AttackAllPlayer),
            Box::new(BlockAllPlayer),
        );

        // Add creature with haste and summoning sickness
        let card = make_creature("Hasty", p1, 2, 1, KeywordAbilities::HASTE);
        let perm = Permanent::new(card, p1);
        game.state.battlefield.add(perm);

        game.state.active_player = p1;
        game.declare_attackers_step(p1);
        game.declare_blockers_step(p1);
        game.combat_damage_step(false);

        // Should have attacked and dealt damage
        assert_eq!(game.state.players[&p2].life, 18);
    }

    #[test]
    fn flying_cannot_be_blocked_by_ground() {
        let (mut game, p1, p2) = setup_combat_game(
            Box::new(AttackAllPlayer),
            Box::new(BlockAllPlayer),
        );

        add_creature(&mut game, p1, "Flyer", 3, 3, KeywordAbilities::FLYING);
        // Ground creature cannot block a flyer
        add_creature(&mut game, p2, "Ground", 2, 2, KeywordAbilities::empty());

        game.state.active_player = p1;
        game.declare_attackers_step(p1);
        game.declare_blockers_step(p1);
        game.combat_damage_step(false);

        // Flyer should get through unblocked
        assert_eq!(game.state.players[&p2].life, 17);
    }

    #[test]
    fn reach_can_block_flying() {
        let (mut game, p1, p2) = setup_combat_game(
            Box::new(AttackAllPlayer),
            Box::new(BlockAllPlayer),
        );

        let flyer_id = add_creature(&mut game, p1, "Flyer", 2, 2, KeywordAbilities::FLYING);
        let reacher_id = add_creature(&mut game, p2, "Reacher", 1, 4, KeywordAbilities::REACH);

        game.state.active_player = p1;
        game.declare_attackers_step(p1);
        game.declare_blockers_step(p1);

        // Reacher should be blocking the flyer
        assert!(game.state.combat.is_blocking(reacher_id));

        game.combat_damage_step(false);

        // No damage to player
        assert_eq!(game.state.players[&p2].life, 20);
        // Creatures trade damage
        assert_eq!(game.state.battlefield.get(reacher_id).unwrap().damage, 2);
        assert_eq!(game.state.battlefield.get(flyer_id).unwrap().damage, 1);
    }

    #[test]
    fn multiple_attackers_deal_combined_damage() {
        let (mut game, p1, p2) = setup_combat_game(
            Box::new(AttackAllPlayer),
            Box::new(BlockAllPlayer),
        );

        add_creature(&mut game, p1, "Bear1", 2, 2, KeywordAbilities::empty());
        add_creature(&mut game, p1, "Bear2", 3, 3, KeywordAbilities::empty());

        game.state.active_player = p1;
        game.declare_attackers_step(p1);
        game.declare_blockers_step(p1);
        game.combat_damage_step(false);

        // Both should deal damage: 2 + 3 = 5
        assert_eq!(game.state.players[&p2].life, 15);
    }
}
RUSTEOF

All 13 combat tests pass. Let me run the full test suite to make sure nothing is broken:

All tests pass (201 engine + 19 integration = 220 total). Now let me update the ROADMAP.md to reflect this completed work:

ReadROADMAP.md25 lines

Now update the step table and the combat integration section in the phased plan:

ReadROADMAP.md20 lines

Now update the Phase 1 section:

ReadROADMAP.md20 lines

ReadROADMAP.md40 lines

Now commit this change:

cd /mnt/dest-btrfs/home/jc/src/mage && git add mtg-rl/ROADMAP.md mtg-rl/mtg-engine/src/game.rs mtg-rl/mtg-engine/src/state.rs && git commit -m "$(cat <<'EOF'
Wire combat phase into game loop: declare attackers/blockers, combat damage

- Add CombatState to GameState for tracking combat phase
- Implement DeclareAttackers step: prompts active player, taps attackers
  (respects vigilance), validates legal attackers
- Implement DeclareBlockers step: prompts defending player, validates
  flying/reach blocking restrictions
- Implement FirstStrikeDamage and CombatDamage steps: assigns damage via
  combat.rs functions, applies to permanents/players, handles lifelink
- Implement EndCombat step: clears combat state
- Add 13 unit tests covering unblocked damage, blocked damage, vigilance,
  lifelink, first strike, trample, defender, summoning sickness, haste,
  flying/reach, multiple attackers
- Update ROADMAP.md to mark combat integration as done

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
EOF
)"

Combat integration is complete and committed. Now let me move on to the next ROADMAP item: Triggered Ability Stacking (Phase 1, Item 2). This is the second highest-impact item, affecting ~400+ cards.

Let me explore the current state of the triggered ability system:

Now I have a comprehensive understanding. Let me create a detailed report:

## Comprehensive Analysis of the mtg-rl Triggered Ability System

I've thoroughly explored the mtg-rl Rust codebase to understand how triggered abilities are structured and how they fit into the game loop. Here's the complete picture:

### 1. **Ability Structure** (`mtg-engine/src/abilities.rs`)

**The Ability struct** is a data-oriented design containing:
- `id`: Unique ability identifier (`AbilityId`)
- `source_id`: Card/permanent that owns this ability (`ObjectId`)
- `ability_type`: Enum indicating `TriggeredNonMana`, `ActivatedNonMana`, `ActivatedMana`, `Static`, or `Spell`
- `trigger_events`: **Vec of `EventType`** that trigger this ability
- `optional_trigger`: Boolean flag for "may" triggers
- `effects`: Vec of `Effect` (what happens when ability resolves)
- `targets`: `TargetSpec` (what the ability can target)
- `costs`: Vec of `Cost` (for activated abilities)
- `static_effects`: Vec of `StaticEffect` (for static abilities)

**Key insight**: Triggered abilities ARE stored with their trigger conditions directly on the ability object. The `trigger_events` field holds the event types that should trigger it.

**Crucial method**:
```rust
pub fn should_trigger(&self, event: &GameEvent) -> bool {
    if self.ability_type != AbilityType::TriggeredNonMana {
        return false;
    }
    self.trigger_events.contains(&event.event_type)
}
```

### 2. **Event System** (`mtg-engine/src/events.rs`)

**GameEvent struct** carries:
- `event_type`: The type of event that occurred (from ~100 event types)
- `target_id`: Primary object involved (e.g., creature damaged)
- `source_id`: What caused the event (e.g., source of damage)
- `player_id`: Associated player
- `amount`: Numeric amount (damage, life, counters, etc.)
- `flag`: Boolean for context (is_combat damage, etc.)
- `data`: Optional string data
- `zone`: Which zone is involved
- `prevented`: Whether the event was prevented
- `applied_effects`: Tracks which effects have already applied (to prevent infinite loops)

**EventType examples**: `EnteredTheBattlefield`, `Dies`, `DamagedPlayer`, `SpellCast`, `GainLife`, `UpkeepStep`, `EndStep`, `DeclareAttackers`, `AttackerDeclared`, etc.

**Convenience constructors** exist for common events like:
```rust
GameEvent::enters_battlefield(permanent_id, player_id)
GameEvent::dies(permanent_id, player_id)
GameEvent::damage_player(target_player, source, amount, is_combat)
```

### 3. **AbilityStore** (`mtg-engine/src/abilities.rs`)

The central registry for all abilities in the game:
- `abilities`: HashMap of all abilities keyed by `AbilityId`
- `by_source`: Index mapping `ObjectId` → Vec of `AbilityId` for fast lookup

**Key methods**:
```rust
pub fn triggered_by(&self, event: &GameEvent) -> Vec<&Ability>
// ↑ Returns all triggered abilities that should fire for an event
pub fn for_source(&self, source_id: ObjectId) -> Vec<&Ability>
// ↑ Get all abilities on a specific permanent
```

### 4. **Stack Structure** (`mtg-engine/src/zones.rs`)

**StackItem**:
```rust
pub struct StackItem {
    pub id: ObjectId,
    pub kind: StackItemKind,
    pub controller: PlayerId,
    pub targets: Vec<ObjectId>,
    pub countered: bool,
}

pub enum StackItemKind {
    Spell { card: CardData },
    Ability { source_id: ObjectId, ability_id: AbilityId, description: String }
}
```

The stack is **LIFO** (last item pushed resolves first):
```rust
pub fn push(&mut self, item: StackItem)  // add to top
pub fn pop(&mut self) -> Option<StackItem>  // remove from top (resolves next)
pub fn top(&self) -> Option<&StackItem>  // peek without removing
```

### 5. **Current Game Loop** (`mtg-engine/src/game.rs`, line 344)

The `process_step()` method shows the CURRENT flow:
```rust
fn process_step(&mut self) {
    let step = self.state.current_step;
    let active = self.state.active_player;

    // 1. Turn-based actions (untap, draw, etc.)
    self.turn_based_actions(step, active);

    // 2. Check state-based actions (loop until stable)
    self.process_state_based_actions();

    // 3. Handle triggered abilities
    // TODO: Put triggered abilities on the stack (task #13)  ← *** THIS IS MISSING ***

    // 4. Priority loop (players can cast spells/activate abilities)
    if has_priority(step) {
        self.priority_loop();
    }
}
```

The priority loop (`priority_loop()` at line 707) manages:
- Legal action computation
- Player decision-making
- Stack resolution (LIFO)
- Passing priority between players

### 6. **Example: How Cards Register Triggered Abilities**

From `mtg-cards/src/sets/fdn.rs`:

```rust
fn ajanis_pridemate(id: ObjectId, owner: PlayerId) -> CardData {
    CardData {
        id, owner,
        name: "Ajani's Pridemate".into(),
        mana_cost: ManaCost::parse("{1}{W}"),
        card_types: vec![CardType::Creature],
        subtypes: vec![SubType::Cat, SubType::Soldier],
        power: Some(2), toughness: Some(2),
        abilities: vec![
            Ability::triggered(id,
                "Whenever you gain life, put a +1/+1 counter on Ajani's Pridemate.",
                vec![EventType::GainLife],  // ← This is the trigger event
                vec![Effect::add_p1p1_counters(1)],
                TargetSpec::None),
        ],
        ..Default::default()
    }
}

fn pulse_tracker(id: ObjectId, owner: PlayerId) -> CardData {
    CardData {
        id, owner,
        name: "Pulse Tracker".into(),
        mana_cost: ManaCost::parse("{B}"),
        card_types: vec![CardType::Creature],
        subtypes: vec![SubType::Vampire, SubType::Rogue],
        power: Some(1), toughness: Some(1),
        abilities: vec![
            Ability::attacks_triggered(id,
                "Whenever Pulse Tracker attacks, each opponent loses 1 life.",
                vec![Effect::Custom("Each opponent loses 1 life.".into())],  // ← Note: some effects use Custom
                TargetSpec::None),
        ],
        ..Default::default()
    }
}
```

### 7. **Java Reference: How XMage Handles It**

From `Mage/src/main/java/mage/game/GameImpl.java`:

**checkStateAndTriggered()** (line 2303):
```java
boolean checkStateAndTriggered() {
    boolean somethingHappened = false;
    while (!isPaused() && !checkIfGameIsOver()) {
        if (!checkStateBasedActions()) {  // First run SBAs
            state.handleSimultaneousEvent(this);
            if (!checkTriggered()) {  // Then check triggers
                break;
            }
        }
        processAction();
        somethingHappened = true;
    }
    return somethingHappened;
}
```

**checkTriggered()** (line 2324):
1. Calls `state.getTriggers().checkStateTriggers(this)` to identify triggered abilities
2. Iterates through players in APNAP order (active player first)
3. For each player's triggered abilities:
   - Executes non-stack-using triggers first (like "if unblocked" effects)
   - If multiple stack-using triggers, lets player choose order
   - Removes ability from triggered list and executes it
4. Loops back in case execution creates new triggers

**Key rule (MTG Comprehensive Rules 117.5)**:
> Each time a player would get priority:
> 1. Perform all applicable state-based actions (loop until none found)
> 2. Put triggered abilities on the stack
> 3. Repeat 1-2 until no SBAs or triggers
> 4. Player gets priority

### 8. **Current Gaps in mtg-rl**

The Rust implementation has:
- ✅ **Ability definition**: Abilities stored with trigger events
- ✅ **Event generation**: `GameEvent` with event types exists
- ✅ **AbilityStore**: Central registry with `triggered_by()` method
- ✅ **Stack infrastructure**: Stack supports items with abilities
- ✅ **Priority loop**: Full priority passing system in place
- ✅ **Effect execution**: Framework for resolving effects

Missing:
- ❌ **Event firing**: No code fires events during game actions (no event log)
- ❌ **Triggered ability detection**: `AbilityStore::triggered_by()` exists but is never called
- ❌ **Triggered ability stacking**: No code puts triggered abilities on the stack
- ❌ **Player choice for multiple triggers**: No mechanism to let players choose trigger order
- ❌ **Optional triggers**: The `optional_trigger` field exists but isn't used
- ❌ **Trigger condition checking**: Triggers only check event type, not "who controlled the permanent" / "your permanent" / etc.

### 9. **Key Data Flow for Implementation**

When an action occurs (e.g., creature enters battlefield):
1. **Event Creation**: `GameEvent::enters_battlefield(permanent_id, player_id)`
2. **Event Firing**: Game stores in event log (needs implementation)
3. **Trigger Detection**: `AbilityStore::triggered_by(&event)` returns matching abilities
4. **Stacking**: Convert to `StackItem::Ability` and push onto stack
5. **Priority**: Players get priority with these items on stack
6. **Resolution**: Call `player.choose_triggered_ability()` if multiple, then execute

### 10. **Important Files and Line Numbers**

- **mtg-engine/src/abilities.rs**: Lines 305-330 (Ability struct), 332-380 (constructors), 450-456 (`should_trigger`), 1144-1214 (AbilityStore)
- **mtg-engine/src/events.rs**: Lines 24-295 (EventType enum), 305-412 (GameEvent struct)
- **mtg-engine/src/zones.rs**: Lines 429-461 (StackItem/StackItemKind), 464-525 (Stack)
- **mtg-engine/src/game.rs**: Lines 344-361 (`process_step`), 707-789 (`priority_loop`), 1025-1075 (SBA processing)
- **mtg-engine/src/state.rs**: Lines 26-107 (GameState struct, note: NO triggered ability storage!)
- **mtg-engine/src/turn.rs**: Lines 53-60 (`has_priority` function)
- **mtg-cards/src/sets/fdn.rs**: Example card implementations with triggered abilities

### Critical Insight for Your Implementation

**GameState is missing a triggered ability queue**. The Java version has `state.getTriggered(playerId)` which returns a list of triggered abilities waiting to be placed on stack. You'll need to add:

```rust
// In GameState
pub triggered_abilities: HashMap<PlayerId, Vec<TriggeredAbilityInstance>>,

// Where TriggeredAbilityInstance would be:
pub struct TriggeredAbilityInstance {
    pub ability_id: AbilityId,
    pub source_id: ObjectId,
    pub controller_id: PlayerId,
    pub chosen_mode: Option<usize>,
    // ... any trigger parameters (what creature entered, etc.)
}
```

This queue gets populated when events fire, then `checkTriggered()` processes them into stack items in player-chosen order.
agentId: ae1bb34 (for resuming to continue this agent's work if needed)
<usage>total_tokens: 91250
tool_uses: 24
duration_ms: 67307</usage>

Excellent. Now I have a thorough understanding of the triggered ability system. Let me plan the implementation:

Emit events during game actions - When things happen (ETB, damage, etc.), fire GameEvents
Add triggered ability queue to Game - Store pending triggered abilities
After SBAs, check for triggered abilities - Scan AbilityStore for abilities that should trigger
Push triggered abilities onto the stack - In APNAP order
Resolve via existing priority loop - Already works

Let me also check what resolve_top_of_stack does with ability stack items to understand how effects get executed when an ability resolves:

Excellent understanding. Let me now read the key sections I need to modify for triggered ability stacking - especially how abilities resolve from the stack:

Greppedfn resolve_top_of_stack|StackItemKind::Ability

Now let me read the AbilityStore methods more carefully, and how should_trigger works:

Greppedfn triggered_by|fn should_trigger|pub struct AbilityStore

Now I understand the full picture. The key thing I need to do:

Emit events when game actions happen (ETB, dies, damage, etc.)
After SBAs, check for triggered abilities that match recent events
Push them on the stack in APNAP order
Let the priority loop handle resolution

The infrastructure is almost entirely in place. Let me look at where events need to be emitted - particularly during permanent ETB and death:

Greppedfn move_card_to_graveyard|Permanent::new\(card|battlefield\.add\(perm|\.set_zone\(

Greppedfn move_card_to_graveyard

Now I need to implement triggered ability stacking. The approach is:

Add an event_log to Game to track events fired during the current action
Emit events at key points (ETB, dies, combat damage, draw, etc.)
After SBAs complete, check for triggered abilities that should fire
Push them onto the stack in APNAP order
Loop SBAs + triggers until stable (matching MTG rules)

However, I need to be careful about the scope. The triggered ability system is complex, and I should implement it incrementally. Let me start with the simplest version that actually works:

For this first phase, I'll add event tracking to the game state, emit events for the most common triggers like ETB, death, damage to players, life gain, and attacks, then after state-based actions resolve, scan for any triggered abilities that match those events and push them onto the stack in the right order. I need to understand how process_step currently works and where the SBA loop fits in so I can integrate this properly, and there's a key design question about when exactly events should be emitted.

The simplest approach is to emit events right after the action happens: when a permanent enters the battlefield, when it dies, when damage is dealt to a player, when life is gained, and when combat happens. Let me add an event log field to the Game struct and modify those key locations to emit the appropriate events.

Now I'll implement triggered ability stacking. This is the second most impactful item. I need to:

Add event tracking to Game
Emit events at key game actions
After SBAs, check for triggered abilities matching events
Push triggered abilities onto the stack

Let me read the current process_step flow and the event log structure:

Readevents.rs70 lines

Good - EventLog already exists. Now let me look at the Game struct to add the event_log:

Readgame.rs80 lines

Now I have all the context. Let me implement triggered ability stacking. I'll modify game.rs to:

Add event_log field to Game
Add event emission at key points
Add check_triggered_abilities() method
Modify process_step() to loop SBAs + triggers

Now add the event_log field to the Game struct:

Add event_log: EventLog::new() to the constructor:

Now modify process_step() to loop SBAs + triggered abilities:

Now I need to emit events at key locations. Let me add event emission to the key game actions:

ETB (when a permanent enters the battlefield from resolving a spell)
Attack declared (when a creature is declared as an attacker)
Life gain (when a player gains life)
Damage to player (combat damage and spell damage)

Let me find and modify the ETB point in resolve_top_of_stack:

Readgame.rs35 lines

Let me find the resolve_top_of_stack more precisely:

Greppedfn resolve_top_of_stack

Readgame.rs75 lines

Now I need to add event emission at key places. Let me modify resolve_top_of_stack to emit ETB events:

Now emit events for combat attacks in declare_attackers_step:

Readgame.rs30 lines

Let me find the attacker declaration part where I register attackers, and add event emission there:

Greppeddeclare_attacker\(\*attacker_id

Now emit events for life gain. Let me find where GainLife is handled in execute_effects:

GreppedEffect::GainLife

Also emit for lifelink damage in combat:

GreppedApply lifelink

200 of 4291